@opengeni/runtime 0.11.0 → 0.13.3

package/dist/{index-D6yi-JcU.d.ts → index-DU-KXVlx.d.ts}

@@ -4,6 +4,48 @@ import { SandboxSessionLike, ExecCommandArgs, SandboxClient, Manifest, SandboxSe
 import * as modal from 'modal';
 import { ControlRequest, ControlResponse, ErrorCode, AgentError, ExecResponse, DesktopInputRequest, ExecRequest } from '@opengeni/agent-proto';
 
+declare const WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION: 1;
+type WorkspaceTreeFingerprint = {
+    algorithm: "sha256";
+    sha256: string;
+    entryCount: number;
+    fileCount: number;
+    totalFileBytes: number;
+};
+type WorkspaceArchiveDescriptor = {
+    version: typeof WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION;
+    revision: string;
+    archiveSha256: string;
+    archiveBytes: number;
+    capturedAt: string;
+    workspace: WorkspaceTreeFingerprint;
+};
+type VerifiedWorkspaceArchive = {
+    bytes: Uint8Array;
+    base64: string;
+    descriptor: WorkspaceArchiveDescriptor;
+};
+type WorkspaceArchiveIntegrityCode = "archive_metadata_missing" | "archive_metadata_invalid" | "archive_base64_invalid" | "archive_hash_mismatch" | "archive_hydration_failed" | "workspace_fingerprint_unavailable" | "workspace_changed_during_capture" | "workspace_fingerprint_mismatch";
+declare class WorkspaceArchiveIntegrityError extends Error {
+    readonly code: WorkspaceArchiveIntegrityCode;
+    readonly name = "WorkspaceArchiveIntegrityError";
+    readonly retryable: boolean;
+    constructor(code: WorkspaceArchiveIntegrityCode, message: string, options?: {
+        retryable?: boolean;
+    });
+}
+declare function parseWorkspaceArchiveDescriptor(value: unknown): WorkspaceArchiveDescriptor | null;
+declare function readVerifiedWorkspaceArchive(base64: unknown, metadata: unknown): VerifiedWorkspaceArchive | null;
+/** Hashes names, kinds, modes, symlink targets and all file bytes through one
+ * deterministic GNU tar stream. Only the aggregate is returned; paths and file
+ * contents never enter logs or durable metadata. */
+declare function fingerprintSandboxWorkspace(session: unknown): Promise<WorkspaceTreeFingerprint>;
+/** Capture is accepted only when the complete tree is byte-identical immediately
+ * before and after the provider snapshot. A concurrent mutation makes the
+ * candidate non-durable and it is never folded onto the lease. */
+declare function captureVerifiedWorkspaceArchive(session: unknown, capturedAtMs?: number): Promise<VerifiedWorkspaceArchive>;
+declare function verifyRestoredWorkspace(session: unknown, descriptor: WorkspaceArchiveDescriptor): Promise<WorkspaceTreeFingerprint>;
+
 type RuntimeMetricsHooks = {
     onModelCall?: (input: {
         provider: string;
@@ -101,6 +143,39 @@ declare const PROVIDER_REGISTRY: Record<SandboxBackend, ProviderRegistration>;
  */
 declare function assertProviderRegistryInvariants(): void;
 
+/**
+ * Provider sandbox failure classification.
+ *
+ * This is deliberately structural and fail-closed. DNS failures often contain
+ * the word "not found" (`ENOTFOUND`) while gRPC status values are also used by
+ * unrelated SDKs and command routers. A bare numeric status (including gRPC's
+ * numeric 5) is therefore not enough to retire a provider instance. Only
+ * authoritative, non-transient evidence may retire a provider instance and
+ * license lease recovery.
+ */
+type ProviderSandboxFailureKind = "not_found" | "transient_transport" | "other";
+type ProviderSandboxFailure = {
+    kind: ProviderSandboxFailureKind;
+    /** Bounded, non-secret diagnostic suitable for logs and lifecycle events. */
+    diagnostic: string;
+};
+/** Typed transport evidence always dominates nested/string NotFound text. */
+declare function classifyProviderSandboxFailure(backendId: string, error: unknown): ProviderSandboxFailure;
+declare function isProviderSandboxNotFoundError(backendId: string, error: unknown): boolean;
+/**
+ * Whether a failure from an operation routed through an already-established
+ * sandbox proves that exact provider sandbox disappeared.
+ *
+ * Routed operations can legitimately return HTTP 404 / `NOT_FOUND` for paths,
+ * files, ports, processes, and other subresources. Those generic signals are
+ * sufficient for provider create/resume APIs, but they must never retire the
+ * live sandbox identity after an arbitrary operation. Only an explicit
+ * sandbox-scoped provider code or Modal's exact terminal sandbox grammar is
+ * authoritative on this path. Transient transport evidence still dominates.
+ */
+declare function isProviderSandboxGoneDuringRoutedOperation(backendId: string, error: unknown): boolean;
+declare function isProviderSandboxTransientError(backendId: string, error: unknown): boolean;
+
 type ModalSandboxAttribution = {
     leaseId: string;
     workspaceId: string;
@@ -120,6 +195,7 @@ type ModalOrphanSweepResult = {
     terminated: ModalOrphanSweepTermination[];
     skipped: number;
 };
+type RevalidateModalOrphanTermination = (candidate: ModalOrphanSweepTermination) => Promise<boolean>;
 declare function modalSandboxAttributionEnvironment(input: ModalSandboxAttribution): Record<string, string>;
 declare function modalSandboxAttributionTags(input: ModalSandboxAttribution): Record<string, string>;
 type ModalModule = typeof modal;
@@ -142,6 +218,9 @@ declare function sweepModalOrphanSandboxes(settings: Settings, liveLeases: LiveM
     maxTerminations?: number;
     unattributedGraceMs?: number;
     client?: ModalClientLike;
+    /** Re-read durable ownership immediately before provider termination. A
+     * false result or callback failure skips the destructive action. */
+    revalidateTermination?: RevalidateModalOrphanTermination;
 }): Promise<ModalOrphanSweepResult>;
 
 interface NegotiationContext {
@@ -152,6 +231,11 @@ interface NegotiationContext {
     liveness: "cold" | "warming" | "warm" | "draining";
     /** The lease epoch echoed on viewer heartbeats (the split-brain fence). */
     leaseEpoch: number;
+    /** Numeric/boolean archive completeness truth. Non-persistable targets use
+     * null/null/false; archive locations and provider details are never exposed. */
+    workspaceGeneration?: number | null;
+    archiveGeneration?: number | null;
+    archiveComplete?: boolean;
     /** The deployment desktop toggle (settings.sandboxDesktopEnabled). */
     desktopEnabled: boolean;
     /**
@@ -319,7 +403,7 @@ declare const DEFAULT_DESKTOP_GEOMETRY: DesktopGeometry;
  *  value to viewers by the caller; this error is for diagnostics. */
 declare class DisplayStackError extends Error {
     readonly exitCode: number;
-    readonly stage: "xvfb" | "x11vnc" | "websockify" | "paint" | "unknown";
+    readonly stage: "xvfb" | "x11vnc" | "websockify" | "paint" | "lock" | "timeout" | "unknown";
     constructor(exitCode: number, output: string);
 }
 /** Thrown when the provider session cannot run commands (a headless-only
@@ -328,12 +412,39 @@ declare class DisplayStackError extends Error {
 declare class DisplayStackUnsupportedError extends Error {
     constructor(message: string);
 }
+type DisplayStackCallerKind = "viewer" | "computer" | "unknown";
+type DisplayStackClassification = "cold" | "already_ready" | "contention" | "unknown";
+type DisplayStackTelemetryStatus = "started" | "waiting" | "completed" | "failed";
+/** Secret-free, bounded-cardinality stage observation. Provider/sandbox IDs are
+ * log correlation fields, never metric labels. */
+type DisplayStackTelemetryEvent = {
+    type: "display_stack.stage";
+    requestId: string;
+    stage: string;
+    status: DisplayStackTelemetryStatus;
+    elapsedMs: number;
+    source: "host" | "sandbox";
+    classification: DisplayStackClassification;
+    callerKind: DisplayStackCallerKind;
+    sandboxId?: string;
+    leaseEpoch?: number;
+    providerSessionId?: number;
+};
+type DisplayStackTelemetryContext = {
+    callerKind: DisplayStackCallerKind;
+    sandboxId?: string;
+    leaseEpoch?: number;
+};
 type EnsureDisplayStackOptions = {
     geometry?: DesktopGeometry;
     /** The exposed stream port; defaults to 6080. */
     port?: number;
-    /** Per-exec timeout; defaults to DISPLAY_STACK_TIMEOUT_MS. */
+    /** Whole-operation wall-clock timeout; defaults to DISPLAY_STACK_TIMEOUT_MS. */
     timeoutMs?: number;
+    /** Caller correlation. Supplying it enables the default structured log sink. */
+    telemetryContext?: DisplayStackTelemetryContext;
+    /** Optional non-blocking telemetry sink (tests/embedders may replace logging). */
+    onTelemetry?: (event: DisplayStackTelemetryEvent) => void | Promise<void>;
 };
 type EnsureDisplayStackResult = {
     /** The exposed port the stack listens on (websockify/noVNC). */
@@ -685,6 +796,10 @@ declare function deleteRecordingArtifacts(session: unknown, proc: RecordingProce
 /** The storage object key for a recording artifact (parallels the file-asset layout). */
 declare function recordingStorageKey(workspaceId: string, sessionId: string, recordingId: string, codec: RecordingCodec): string;
 
+declare function parseExecBannerSessionId(raw: string): number | null;
+declare function parseExecBannerExitCode(raw: string): number | null;
+declare function isExecSessionLostBanner(out: string, execSessionId: number): boolean;
+
 type ChannelAExecResult = {
     output?: string;
     stdout?: string;
@@ -722,6 +837,21 @@ type ChannelASession = {
         yieldTimeMs?: number;
         maxOutputTokens?: number;
     }): Promise<string>;
+    writeStdinForProcessMutation?(args: {
+        sessionId: number;
+        chars?: string;
+        yieldTimeMs?: number;
+        maxOutputTokens?: number;
+    }): Promise<string>;
+    writeStdinForProcessControl?(args: {
+        sessionId: number;
+        chars?: string;
+        yieldTimeMs?: number;
+        maxOutputTokens?: number;
+    }): Promise<string>;
+    cancelExecCommand?(opId: string): Promise<boolean>;
+    hasRetainedProcess?(providerSessionId: number): boolean;
+    execCommandForProcessControl?(providerSessionId: number, args: ChannelAExecArgs): Promise<string>;
     createEditor?(runAs?: string): ChannelAEditor;
     supportsPty?(): boolean;
 };
@@ -820,10 +950,9 @@ declare class SandboxChannelAService {
     detectReposDetailed(): Promise<RepositoryDiscoveryResult>;
     /** Detect repo roots within the workspace (for the Git.repos capability). */
     detectRepos(): Promise<string[]>;
-    /** Run a bounded command, return buffered stdout/stderr + exit code inline. The
-     *  long-running tail (when the process hasn't exited within timeoutMs) keeps
-     *  running in-box; if emitStream is set the buffered output is also published as
-     *  the agent firehose so other viewers see it. */
+    /** Run a bounded command to physical completion and return buffered output.
+     *  A deadline cancels the exact provider operation, proves its process group
+     *  absent, and settles any retained-process admission before returning 124. */
     terminalExec(req: TerminalExecRequest): Promise<TerminalExecResponse>;
     /** Open an interactive PTY: exec the shell with tty:true, yielding the numeric
      *  exec-session id the caller persists (ptyId<->execSessionId) so subsequent
@@ -843,9 +972,10 @@ declare class SandboxChannelAService {
     /** Resize an open PTY (SIGWINCH via stty against the exec-session). The SDK has
      *  no resize method; stty in the same tty session updates the geometry. */
     ptyResize(req: PtyResizeRequest, execSessionId: number): Promise<void>;
-    /** Close an open PTY: write exit/EOF. The caller marks the row closed + emits
-     *  terminal.pty.exited. */
-    ptyClose(_req: PtyCloseRequest, execSessionId: number | null): Promise<void>;
+    /** Ask an open PTY to exit and return the exact provider banner. The routing
+     * session settles durable process authority only when that banner proves this
+     * locator exited or was lost; callers must keep metadata open otherwise. */
+    ptyClose(_req: PtyCloseRequest, execSessionId: number | null): Promise<string>;
     /** The current FS revision (for the caller to persist/seed). */
     currentRevision(): number;
     private joinRoot;
@@ -862,11 +992,6 @@ declare class SandboxChannelAService {
     emitGitChanged(repoPath: string, reason: GitChangedPayload["reason"]): Promise<void>;
 }
 declare function stripExecBanner(raw: string): string;
-declare function isExecSessionLostBanner(out: string, execSessionId: number): boolean;
-declare function parseExecBannerSessionId(raw: string): number | null;
-/** Recover a completed execCommand fallback's exit status from its banner.
- * Only the banner region is inspected, so command output cannot spoof success. */
-declare function parseExecBannerExitCode(raw: string): number | null;
 declare function assertSafeRelPath(p: string): string;
 declare function parsePorcelainV2(z: string): Omit<GitStatusResponse, "revision">;
 type NumstatEntry = {
@@ -2104,7 +2229,46 @@ interface ResolvedActiveBackend {
     sandboxId: string | null;
     /** A label for diagnostics ("modal" | "selfhosted" | the sandbox name). */
     kind: string;
+    /** Exact durable home-lease epoch for a persistable provider. Absent for
+     * connected-machine and other non-persistable route targets. */
+    leaseEpoch?: number;
+    /** Exact durable provider identity paired with `leaseEpoch`. This is internal
+     * routing metadata only; it is never projected to an agent or public API. */
+    providerInstanceId?: string;
+    /** Active-pointer epoch observed when this route was resolved. The proxy fills
+     * this internally even when a resolver omits it. */
+    activeEpoch?: number;
 }
+/** Durable identity assigned to a provider exec that yielded instead of
+ * exiting. The UUID is OpenGeni authority; the numeric provider session id is
+ * only a locator within the exact copied backend route. */
+type RoutingRetainedProcess = {
+    id: string;
+    providerSessionId: number;
+};
+/** Exact copied route identity required to reconstruct an already-durable
+ * retained process after the request/runtime object that opened it is gone.
+ * The live session is deliberately not caller-supplied: adoption may bind only
+ * to this proxy's construction-time default backend, so it cannot resolve or
+ * follow the current active pointer. */
+type RoutingRetainedProcessAdoption = {
+    process: RoutingRetainedProcess;
+    backend: {
+        sandboxId: string | null;
+        leaseEpoch?: number;
+        providerInstanceId?: string;
+        activeEpoch: number;
+    };
+};
+type RoutingRetainedProcessTerminalProof = {
+    outcome: "exited";
+    exitCode: number;
+    reason: "provider_exit_banner";
+} | {
+    outcome: "lost";
+    exitCode: null;
+    reason: "provider_session_lost_banner";
+};
 interface RoutingSandboxSessionDeps {
     /**
      * The DEFAULT backend resolved at construction time (the same shape `resolve()`
@@ -2136,7 +2300,68 @@ interface RoutingSandboxSessionDeps {
     maxFenceRetries?: number;
     /** Optional structured-log sink for swap/fence transitions (diagnostics). */
     onTransition?: (event: RoutingTransitionEvent) => void;
+    /** Admit a filesystem-writing operation after resolving its exact route but
+     * before invoking the provider. A rejection fails closed and is deliberately
+     * outside provider fence-retry/error handling, so it can never replay the op
+     * against a rival backend. */
+    beforeMutation?: (input: {
+        op: string;
+        backend: ResolvedActiveBackend;
+    }) => Promise<unknown>;
+    /** Mark a mutation physically settled after its provider promise resolves OR
+     * rejects. A resolved result is also revalidated against the same durable
+     * route and attempt fence before its output is accepted. Settlement rejection
+     * leaves a fail-closed blocker and the mutation must never be replayed. */
+    afterMutation?: (input: {
+        op: string;
+        backend: ResolvedActiveBackend;
+        admission: unknown;
+        outcome: "resolved" | "rejected";
+        /** Provider result for a resolved call. Never present for rejection. */
+        result?: unknown;
+        /** Stable candidate generated before durable promotion is attempted. It is
+         * supplied only when the provider returned a positive yielded-session id. */
+        retainedProcess?: RoutingRetainedProcess;
+    }) => Promise<void>;
+    /** Admit one model/user-visible stdin mutation under the already-durable
+     * retained process authority. Control polling and helper execs never call it. */
+    beforeProcessMutation?: (input: {
+        op: string;
+        backend: ResolvedActiveBackend;
+        process: RoutingRetainedProcess;
+    }) => Promise<unknown>;
+    /** Physically settle one process-scoped stdin admission. */
+    afterProcessMutation?: (input: {
+        op: string;
+        backend: ResolvedActiveBackend;
+        process: RoutingRetainedProcess;
+        admission: unknown;
+        outcome: "resolved" | "rejected";
+        result?: unknown;
+    }) => Promise<void>;
+    /** Close the durable parent admission/process holder only after exact exit or
+     * matching provider-loss proof. Tracking is removed only after this resolves. */
+    settleProcess?: (input: {
+        backend: ResolvedActiveBackend;
+        process: RoutingRetainedProcess;
+        proof: RoutingRetainedProcessTerminalProof;
+    }) => Promise<void>;
+    /** Called only when an operation against the default/home backend throws a
+     * non-fence error. Wiring may classify definitive provider disappearance and
+     * atomically retire the exact lease epoch. Returning a result makes dispatch
+     * throw a typed recovery-required error WITHOUT replaying the operation (the
+     * original mutation may have reached the provider). */
+    onDefaultBackendError?: (input: {
+        op: string;
+        error: unknown;
+        kind: string;
+        backend: ResolvedActiveBackend;
+    }) => Promise<DefaultBackendLossResult | null>;
 }
+type DefaultBackendLossResult = {
+    leaseEpoch: number;
+    recovery: "pending" | "degraded" | "unrecoverable" | "superseded";
+};
 interface RoutingTransitionEvent {
     type: "resolved" | "fenced-retry" | "epoch-changed";
     fromEpoch: number;
@@ -2150,6 +2375,34 @@ declare class RoutingUnsupportedError extends Error {
     readonly name = "RoutingUnsupportedError";
     constructor(op: string, kind: string);
 }
+declare class RoutingBackendRecoveryRequiredError extends Error {
+    readonly op: string;
+    readonly leaseEpoch: number;
+    readonly recovery: DefaultBackendLossResult["recovery"];
+    readonly name = "RoutingBackendRecoveryRequiredError";
+    readonly retryable: boolean;
+    constructor(op: string, leaseEpoch: number, recovery: DefaultBackendLossResult["recovery"]);
+}
+/** A mutating provider call was admitted but could not be settled against the
+ * exact route that admitted it. The provider may have applied the effect, so the
+ * proxy rejects the output and explicitly forbids an automatic replay. */
+declare class RoutingMutationOutcomeUnknownError extends Error {
+    readonly op: string;
+    readonly name = "RoutingMutationOutcomeUnknownError";
+    readonly retryable = false;
+    constructor(op: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** An explicit process-aware operation named a numeric provider locator that
+ * is not retained by this routing session. Callers must never fall back to the
+ * current active pointer for such an operation. */
+declare class RoutingRetainedProcessNotFoundError extends Error {
+    readonly providerSessionId: number;
+    readonly name = "RoutingRetainedProcessNotFoundError";
+    readonly retryable = false;
+    constructor(providerSessionId: number);
+}
 /**
  * ONE stable session-shaped object the SDK binds to. Every method re-reads the
  * pointer, resolves the active backend (cached by epoch), and dispatches. A
@@ -2172,6 +2425,10 @@ declare class RoutingSandboxSession implements RoutableBackendSession {
     private cachedSandboxId;
     private cached;
     private lastResolved;
+    /** Provider session ids are scoped to one backend instance. Each entry copies
+     * that exact resolved route so pointer movement can never redirect stdin,
+     * polling, or process-group helpers to another box. */
+    private readonly retainedProcesses;
     desktopInput?: (event: unknown) => Promise<void>;
     screenshot?: () => Promise<{
         png: Uint8Array;
@@ -2204,6 +2461,20 @@ declare class RoutingSandboxSession implements RoutableBackendSession {
      * is THE per-call re-read that makes a mid-turn swap land on the next op.
      */
     private resolve;
+    private invalidate;
+    private registerRetainedProcess;
+    private retainedProcess;
+    /** Reconstruct one process that was already promoted durably by an earlier
+     * request. Adoption never reads the active pointer and never repeats parent
+     * promotion. It can bind only to the exact construction-time default backend;
+     * callers must reject non-default routes until they can independently rebuild
+     * that provider session from its copied durable identity. */
+    adoptRetainedProcess(input: RoutingRetainedProcessAdoption): void;
+    private ensureParentPromotion;
+    private settleRetainedProcess;
+    private flushPendingProcessMutation;
+    private dispatchProcessMutation;
+    private dispatchProcessControl;
     /**
      * Dispatch an op to the currently-active backend, retrying on a stale-epoch
      * fence. The sequence per attempt:
@@ -2238,6 +2509,25 @@ declare class RoutingSandboxSession implements RoutableBackendSession {
     exec(args: unknown): Promise<unknown>;
     execCommand(args: unknown): Promise<string>;
     writeStdin(args: unknown): Promise<string>;
+    /** Whether a positive provider session locator is still pinned to the exact
+     * backend that yielded it. This synchronous probe is used only to select the
+     * process-aware routing surface; it is not itself durable authority. */
+    hasRetainedProcess(providerSessionId: number): boolean;
+    /** Return only OpenGeni's durable UUID + provider locator. Backend/session
+     * objects remain private so a caller cannot forge route authority from this
+     * diagnostic handoff. */
+    retainedProcessIdentity(providerSessionId: number): RoutingRetainedProcess | null;
+    /** Model/user-visible stdin is a distinct workspace mutation admission under
+     * the durable retained-process holder. It never re-reads the active pointer. */
+    writeStdinForProcessMutation(args: unknown): Promise<string>;
+    /** Cancellation and drain polling are control operations. They stay pinned to
+     * the process backend and may prove terminal state, but never advance the
+     * workspace generation. */
+    writeStdinForProcessControl(args: unknown): Promise<string>;
+    /** Run a PID/PGID marker or signal helper on the retained process's exact
+     * backend. The helper is control-plane work and therefore has no workspace
+     * mutation admission of its own. */
+    execCommandForProcessControl(providerSessionId: number, args: unknown): Promise<string>;
     cancelExecCommand(opId: string): Promise<boolean>;
     readFile(args: unknown): Promise<string | Uint8Array>;
     writeFile(args: unknown): Promise<unknown>;
@@ -2261,7 +2551,10 @@ declare class RoutingSandboxSession implements RoutableBackendSession {
      *  direct delegate returns undefined and every lazy turn would die at bind. Return a
      *  LAZY EDITOR PROXY instead: a non-null editor whose async ops resolve the active
      *  backend (establishing the box on first use, via `dispatch`) and delegate to its
-     *  real editor — mirroring how this proxy defers exec/readFile. */
+     *  real editor — mirroring how this proxy defers exec/readFile. Even when an
+     *  eager editor already exists, returning it directly would bypass per-edit
+     *  route resolution and mutation-generation admission, so every editor is
+     *  represented by this dispatching proxy. */
     createEditor(runAs?: string): unknown;
     resolveExposedPort(port: number): Promise<ExposedPortEndpoint>;
     /** Serialize the active backend's session state. Used by the resume-by-id seam
@@ -2291,6 +2584,18 @@ interface ActiveBackendResolverDeps {
     defaultBackend: RoutableBackendSession;
     /** A label for the default backend (its backend id: "modal"/"selfhosted"/…). */
     defaultKind: string;
+    /**
+     * Re-resolve the session's HOME backend after the route cache is fenced.
+     *
+     * The normal path returns `defaultBackend` (the turn's already-established
+     * handle), but an API-side same-target repair can rematerialize that lease
+     * while a worker turn is still alive. Such a repair advances the route epoch
+     * without changing the null pointer; callers that can resume the current
+     * lease-owned identity may provide this callback so the next epoch does not
+     * keep dispatching to the dead pre-repair object. This callback must never
+     * create a provider or replay an operation.
+     */
+    resolveDefaultBackend?: (pointer: ActivePointer) => Promise<ResolvedActiveBackend>;
     /** Look up a first-class sandbox by id (the swap target). Returns null when the
      *  id is unknown or not in this workspace (the caller 409s the swap). */
     getSandbox(sandboxId: string): Promise<RoutableSandbox | null>;
@@ -2519,23 +2824,22 @@ type EstablishedSandboxSession = {
     /** Set when a create-authorized reattach found the envelope's box GONE
      *  (provider NotFound) and fell through to cold-restore. */
     lostInstanceId?: string;
+    /** Exact durable archive revision verified byte-for-byte after hydration. */
+    restoredArchive?: WorkspaceArchiveDescriptor;
 };
+declare class SandboxExecReadinessError extends Error {
+    readonly backend: string;
+    readonly code: "exec_probe_unavailable" | "exec_probe_timeout" | "exec_probe_failed";
+    readonly timeoutMs: number;
+    readonly exitCode: number | null;
+    readonly name = "SandboxExecReadinessError";
+    constructor(backend: string, code: "exec_probe_unavailable" | "exec_probe_timeout" | "exec_probe_failed", timeoutMs: number, exitCode?: number | null);
+}
+/** A provider handle is not workspace readiness. Modal can return a handle
+ * before its command router accepts exec, so every create path must pass this
+ * bounded probe before atomically publishing the lease warm/ready. */
+declare function verifySandboxExecReadiness(established: EstablishedSandboxSession, timeoutMs?: number): Promise<void>;
 type SandboxCreatedCallback = (established: EstablishedSandboxSession) => Promise<void>;
-/**
- * Per-provider NotFound discriminator. The @openai/agents-extensions
- * `isProviderSandboxNotFoundError` / `assertResumeRecreateAllowed` helpers live
- * under `@openai/agents-extensions/sandbox/shared`, which is NOT an exported
- * subpath (the package `exports` map only exposes `./sandbox/<provider>`), so we
- * re-implement the discrimination here by inspecting the thrown error shape.
- *
- * "Box no longer running" (the box was reaped / idled out / 24h-ceiling) is the
- * ONLY error that licenses a cold-restore via create(). Every other resume
- * failure (transient provider error, auth, network) must propagate so the caller
- * backs off — never spawns a rival box. We err on the side of NOT recreating:
- * an unrecognized error is treated as "not NotFound" (propagate), because a
- * false-positive recreate is the dangerous direction (double-spawn).
- */
-declare function isProviderSandboxNotFoundError(backendId: string, error: unknown): boolean;
 /**
  * Establish from one recovery envelope under an explicit creation policy. The
  * envelope is the lease's box-identity descriptor (the same per-turn `_sandbox`
@@ -2555,6 +2859,10 @@ declare function establishSandboxSessionFromEnvelope(settings: Settings, envelop
     backendOverride?: SandboxBackend;
     environment?: Record<string, string>;
     onSandboxCreated?: SandboxCreatedCallback;
+    /** Called after archive hydration but immediately before the exact workspace
+     * fingerprint probe. Lease-aware callers persist `verifying` here so a box
+     * is never observable as ready while verification is in flight. */
+    onWorkspaceRestoreVerifying?: (descriptor: WorkspaceArchiveDescriptor) => Promise<void>;
     metrics?: RuntimeMetricsHooks;
 }): Promise<EstablishedSandboxSession>;
 /**
@@ -2570,5 +2878,30 @@ declare function establishSandboxSessionFromEnvelope(settings: Settings, envelop
  * no warm-reattach).
  */
 declare function serializeEstablishedSandboxEnvelope(established: EstablishedSandboxSession): Promise<Record<string, unknown> | null>;
+/**
+ * Whether a replacement envelope contains a provider-resumable identity. An
+ * archive-only envelope is intentionally valid recovery metadata, but it is
+ * never proof that the newly-created provider box can be resumed or attached.
+ */
+declare function hasPersistableSandboxProviderIdentity(envelope: Record<string, unknown> | null | undefined): envelope is Record<string, unknown>;
+/** A replacement provider may not be published warm without a resumable
+ * identity. Archive-only state is retained only when the caller rolls back to
+ * cold and needs the verified workspace bytes for the next attempt. */
+declare class SandboxReplacementProviderStateError extends Error {
+    readonly backend: string;
+    readonly code: "replacement_provider_state_unpersistable";
+    constructor(backend: string);
+}
+declare function requirePersistableReplacementSandboxEnvelope(envelope: Record<string, unknown> | null, backend: string): Record<string, unknown>;
+/**
+ * Build the only resume envelope that may be published for a newly-created
+ * replacement sandbox. Historical state contributes durable archive pointers
+ * only; it can never substitute for serialization of the replacement's provider
+ * identity. If replacement serialization is unavailable or fails, publication
+ * keeps an archive-only envelope (when one exists) or null. The new instance id
+ * remains separately fenced on the lease, while later attach/resume fails closed
+ * rather than targeting the dead provider that initiated rematerialization.
+ */
+declare function serializeReplacementSandboxEnvelope(established: EstablishedSandboxSession, archiveSource: Record<string, unknown> | null): Promise<Record<string, unknown> | null>;
 
-export { OP_STREAM_SILENCE_TIMEOUT_MS as $, type ActiveBackendResolverDeps as A, type BackendUnresolvableCode as B, ChannelAConflictError as C, DEFAULT_DESKTOP_GEOMETRY as D, type EnsureDisplayStackOptions as E, FAULT_FIELD_WHAT_HAPPENED as F, type MintStreamTokenInput as G, MockAgentResponder as H, type MockAgentResponderOptions as I, type MockExecHandler as J, type ModalModuleLoader as K, type LiveModalSandboxLeaseAttribution as L, type MaterializeRunCredentialsOptions as M, type ModalOrphanSweepResult as N, type ModalSandboxAttribution as O, NEVER_SENT_DETAIL_KEY as P, NatsControlRpc as Q, type RunCredentialSessionReady as R, type NatsOpStreamConnection as S, NatsOpStreamTransport as T, type NatsRequestConnection as U, type NegotiationContext as V, type NormalizedRunCredentialMaterial as W, type NumstatEntry as X, OP_STREAM_ACK_INTERVAL_MS as Y, OP_STREAM_DEFAULT_WINDOW_BYTES as Z, OP_STREAM_RECONNECT_HOLD_MS as _, type RuntimeMetricsHooks as a, SelfhostedSandboxClient as a$, type OpStreamExecOutcome as a0, type OpStreamJournal as a1, type OpStreamSubscription as a2, type OpStreamTransport as a3, OpStreamUnavailableError as a4, PROVIDER_REGISTRY as a5, type ProviderConstructionContext as a6, type ProviderRegistration as a7, REPOSITORY_DISCOVERY_LIMIT as a8, type RecordingArtifactMetadata as a9, SELFHOSTED_RETRY_BACKOFF_BASE_MS as aA, SELFHOSTED_RETRY_BACKOFF_CAP_MS as aB, SELFHOSTED_RETRY_BACKOFF_FACTOR as aC, SELFHOSTED_TIMEOUT_MAX_RETRIES as aD, STREAM_PORT as aE, STREAM_TOKEN_DEFAULT_TTL_SECONDS as aF, SandboxChannelAService as aG, type SandboxChannelAServiceOptions as aH, SandboxConfigError as aI, type SandboxCreatedCallback as aJ, SandboxProviderUnavailableError as aK, SandboxResumeStateUnavailableError as aL, type SelfhostedApplyDiff as aM, SelfhostedControlError as aN, type SelfhostedEditor as aO, type SelfhostedEnrollment as aP, type SelfhostedExecArgs as aQ, type SelfhostedExecResult as aR, type SelfhostedImageOutput as aS, type SelfhostedLivenessState as aT, type SelfhostedNegotiationInput as aU, type SelfhostedOpObservation as aV, type SelfhostedOpObserver as aW, type SelfhostedOpStreamDeps as aX, type SelfhostedRelayConfig as aY, type SelfhostedRetryClock as aZ, type SelfhostedRetryDecision as a_, type RecordingCodec as aa, type RecordingContentType as ab, RecordingError as ac, type RecordingProcess as ad, RecordingUnavailableError as ae, type RepositoryDiscoveryDegradedReason as af, type RepositoryDiscoveryResult as ag, type ResolvedActiveBackend as ah, type RoutableBackendSession as ai, type RoutableSandbox as aj, RoutingSandboxSession as ak, type RoutingSandboxSessionDeps as al, type RoutingTransitionEvent as am, RoutingUnsupportedError as an, type RunCredentialCommandRunner as ao, type RunCredentialCommandSession as ap, type RunCredentialExpectedScope as aq, RunCredentialValidationError as ar, SELFHOSTED_DEFAULT_TIMEOUT_MS as as, SELFHOSTED_DRAINING_MAX_RETRIES as at, SELFHOSTED_EXEC_DRAINING_MAX_RETRIES as au, SELFHOSTED_IDEMPOTENT_READONLY_OPS as av, SELFHOSTED_INFRASTRUCTURE_FAULT_CLASSES as aw, SELFHOSTED_NEVER_SENT_MAX_RETRIES as ax, SELFHOSTED_RECONNECT_WINDOW_MS as ay, SELFHOSTED_RELAY_STREAM_PATH as az, ActiveBackendUnresolvableError as b, parseUnifiedPatch as b$, SelfhostedSession as b0, type SelfhostedSessionBuild as b1, type SelfhostedSessionDeps as b2, type SelfhostedSessionState as b3, type SelfhostedUnavailableReason as b4, type StartRecordingInput as b5, StreamPortUnavailableError as b6, type SwapTargetEstablishability as b7, TERMINAL_SERVER_TIMEOUT_MS as b8, TerminalServerError as b9, ensureModalRegistryImage as bA, ensureTerminalServer as bB, establishSandboxSessionFromEnvelope as bC, execDeadlineHint as bD, exposeStreamPort as bE, extForCodec as bF, inspectRecordingArtifact as bG, isExecSessionLostBanner as bH, isProviderSandboxNotFoundError as bI, isSelfhostedProviderNotFoundError as bJ, makeActiveBackendResolver as bK, materializeRunCredentials as bL, mintStreamToken as bM, modalSandboxAttributionEnvironment as bN, modalSandboxAttributionTags as bO, negotiateCapabilities as bP, negotiateSelfhostedCapabilities as bQ, nextDurableOpId as bR, normalizeRunCredentialsResolution as bS, offlineAgentError as bT, offlineControlResponse as bU, opAckSubject as bV, opFrameSubject as bW, parseExecBannerExitCode as bX, parseExecBannerSessionId as bY, parseNumstatZ as bZ, parsePorcelainV2 as b_, TerminalServerUnsupportedError as ba, ToolspaceTokenPathError as bb, agentErrorToControlError as bc, assertDescriptorRegistryInvariants as bd, assertProviderRegistryInvariants as be, assertSafeRelPath as bf, backendSupportsOs as bg, buildDisplayStackScript as bh, buildSelfhostedBackendSession as bi, buildStreamUrl as bj, buildTerminalServerScript as bk, clearRunCredentials as bl, clearRunCredentialsForAttempt as bm, contentTypeForCodec as bn, createSandboxClient as bo, createSandboxClientForBackend as bp, decideSelfhostedRetry as bq, decodeModalSnapshotId as br, defaultSelfhostedRetryClock as bs, deletePriorPersistedSnapshot as bt, deleteRecordingArtifacts as bu, deserializeSandboxSessionStateEnvelope as bv, desktopCapableBackend as bw, drainingExhaustedError as bx, drainingMessage as by, ensureDisplayStack as bz, type ActivePointer as c, payloadTooLargeMessage as c0, readWorkspaceArchiveFromEnvelopeSessionState as c1, recordingStorageKey as c2, renderSelfhostedFault as c3, restoredSandboxSessionStateFromEntry as c4, runCredentialPointerFile as c5, runCredentialRoot as c6, runWithToolCallCorrelation as c7, sandboxStateEntryFromRunState as c8, sanitizeOpIdToken as c9, withToolspaceTokenEnvironment as cA, withToolspaceTokenSession as cB, selectBackend as ca, selfhostedFaultClass as cb, selfhostedLiveness as cc, selfhostedRetryBackoffMs as cd, serializeEstablishedSandboxEnvelope as ce, setSelfhostedApplyDiff as cf, startRecording as cg, stopRecording as ch, stripExecBanner as ci, subjectFor as cj, swapTargetEstablishability as ck, sweepModalOrphanSandboxes as cl, tagModalSandbox as cm, tearDownDisplayStack as cn, tearDownTerminalServer as co, terminateModalSandboxById as cp, timeoutAgentError as cq, timeoutControlResponse as cr, toolspaceTokenFileForSession as cs, toolspaceTokenFileFromEnvironment as ct, uploadRecordingArtifact as cu, verifyStreamToken as cv, withRunCredentialEnvironment as cw, withRunCredentialsClient as cx, withRunCredentialsSession as cy, withToolspaceTokenClient as cz, type ChannelAEmitter as d, type ChannelAExecArgs as e, type ChannelAExecResult as f, ChannelANotFoundError as g, type ChannelASession as h, ChannelAUnavailableError as i, ChannelAUnsupportedError as j, ChannelAValidationError as k, type ControlRpc as l, DISPLAY_STACK_TIMEOUT_MS as m, type DesktopGeometry as n, DisplayStackError as o, DisplayStackUnsupportedError as p, type EnsureDisplayStackResult as q, type EnsureTerminalServerOptions as r, type EnsureTerminalServerResult as s, type EstablishedSandboxSession as t, type ExposeStreamPortInput as u, type ExposeStreamPortResult as v, type ExposedPortEndpoint as w, FAULT_FIELD_WHAT_PRESERVED as x, FAULT_FIELD_WHAT_TO_TRY as y, FAULT_FIELD_WHICH_LAYER as z };
+export { type NatsRequestConnection as $, type ActiveBackendResolverDeps as A, type BackendUnresolvableCode as B, ChannelAConflictError as C, DEFAULT_DESKTOP_GEOMETRY as D, type EnsureDisplayStackOptions as E, type ExposeStreamPortInput as F, type ExposeStreamPortResult as G, type ExposedPortEndpoint as H, FAULT_FIELD_WHAT_HAPPENED as I, FAULT_FIELD_WHAT_PRESERVED as J, FAULT_FIELD_WHAT_TO_TRY as K, FAULT_FIELD_WHICH_LAYER as L, type LiveModalSandboxLeaseAttribution as M, type MaterializeRunCredentialsOptions as N, type MintStreamTokenInput as O, MockAgentResponder as P, type MockAgentResponderOptions as Q, type RunCredentialSessionReady as R, type MockExecHandler as S, type ModalModuleLoader as T, type ModalOrphanSweepResult as U, type ModalOrphanSweepTermination as V, type ModalSandboxAttribution as W, NEVER_SENT_DETAIL_KEY as X, NatsControlRpc as Y, type NatsOpStreamConnection as Z, NatsOpStreamTransport as _, type RuntimeMetricsHooks as a, SandboxProviderUnavailableError as a$, type NegotiationContext as a0, type NormalizedRunCredentialMaterial as a1, type NumstatEntry as a2, OP_STREAM_ACK_INTERVAL_MS as a3, OP_STREAM_DEFAULT_WINDOW_BYTES as a4, OP_STREAM_RECONNECT_HOLD_MS as a5, OP_STREAM_SILENCE_TIMEOUT_MS as a6, type OpStreamExecOutcome as a7, type OpStreamJournal as a8, type OpStreamSubscription as a9, RoutingSandboxSession as aA, type RoutingSandboxSessionDeps as aB, type RoutingTransitionEvent as aC, RoutingUnsupportedError as aD, type RunCredentialCommandRunner as aE, type RunCredentialCommandSession as aF, type RunCredentialExpectedScope as aG, RunCredentialValidationError as aH, SELFHOSTED_DEFAULT_TIMEOUT_MS as aI, SELFHOSTED_DRAINING_MAX_RETRIES as aJ, SELFHOSTED_EXEC_DRAINING_MAX_RETRIES as aK, SELFHOSTED_IDEMPOTENT_READONLY_OPS as aL, SELFHOSTED_INFRASTRUCTURE_FAULT_CLASSES as aM, SELFHOSTED_NEVER_SENT_MAX_RETRIES as aN, SELFHOSTED_RECONNECT_WINDOW_MS as aO, SELFHOSTED_RELAY_STREAM_PATH as aP, SELFHOSTED_RETRY_BACKOFF_BASE_MS as aQ, SELFHOSTED_RETRY_BACKOFF_CAP_MS as aR, SELFHOSTED_RETRY_BACKOFF_FACTOR as aS, SELFHOSTED_TIMEOUT_MAX_RETRIES as aT, STREAM_PORT as aU, STREAM_TOKEN_DEFAULT_TTL_SECONDS as aV, SandboxChannelAService as aW, type SandboxChannelAServiceOptions as aX, SandboxConfigError as aY, type SandboxCreatedCallback as aZ, SandboxExecReadinessError as a_, type OpStreamTransport as aa, OpStreamUnavailableError as ab, PROVIDER_REGISTRY as ac, type ProviderConstructionContext as ad, type ProviderRegistration as ae, type ProviderSandboxFailure as af, type ProviderSandboxFailureKind as ag, REPOSITORY_DISCOVERY_LIMIT as ah, type RecordingArtifactMetadata as ai, type RecordingCodec as aj, type RecordingContentType as ak, RecordingError as al, type RecordingProcess as am, RecordingUnavailableError as an, type RepositoryDiscoveryDegradedReason as ao, type RepositoryDiscoveryResult as ap, type ResolvedActiveBackend as aq, type RevalidateModalOrphanTermination as ar, type RoutableBackendSession as as, type RoutableSandbox as at, RoutingBackendRecoveryRequiredError as au, RoutingMutationOutcomeUnknownError as av, type RoutingRetainedProcess as aw, type RoutingRetainedProcessAdoption as ax, RoutingRetainedProcessNotFoundError as ay, type RoutingRetainedProcessTerminalProof as az, ActiveBackendUnresolvableError as b, ensureTerminalServer as b$, SandboxReplacementProviderStateError as b0, SandboxResumeStateUnavailableError as b1, type SelfhostedApplyDiff as b2, SelfhostedControlError as b3, type SelfhostedEditor as b4, type SelfhostedEnrollment as b5, type SelfhostedExecArgs as b6, type SelfhostedExecResult as b7, type SelfhostedImageOutput as b8, type SelfhostedLivenessState as b9, agentErrorToControlError as bA, assertDescriptorRegistryInvariants as bB, assertProviderRegistryInvariants as bC, assertSafeRelPath as bD, backendSupportsOs as bE, buildDisplayStackScript as bF, buildSelfhostedBackendSession as bG, buildStreamUrl as bH, buildTerminalServerScript as bI, captureVerifiedWorkspaceArchive as bJ, classifyProviderSandboxFailure as bK, clearRunCredentials as bL, clearRunCredentialsForAttempt as bM, contentTypeForCodec as bN, createSandboxClient as bO, createSandboxClientForBackend as bP, decideSelfhostedRetry as bQ, decodeModalSnapshotId as bR, defaultSelfhostedRetryClock as bS, deletePriorPersistedSnapshot as bT, deleteRecordingArtifacts as bU, deserializeSandboxSessionStateEnvelope as bV, desktopCapableBackend as bW, drainingExhaustedError as bX, drainingMessage as bY, ensureDisplayStack as bZ, ensureModalRegistryImage as b_, type SelfhostedNegotiationInput as ba, type SelfhostedOpObservation as bb, type SelfhostedOpObserver as bc, type SelfhostedOpStreamDeps as bd, type SelfhostedRelayConfig as be, type SelfhostedRetryClock as bf, type SelfhostedRetryDecision as bg, SelfhostedSandboxClient as bh, SelfhostedSession as bi, type SelfhostedSessionBuild as bj, type SelfhostedSessionDeps as bk, type SelfhostedSessionState as bl, type SelfhostedUnavailableReason as bm, type StartRecordingInput as bn, StreamPortUnavailableError as bo, type SwapTargetEstablishability as bp, TERMINAL_SERVER_TIMEOUT_MS as bq, TerminalServerError as br, TerminalServerUnsupportedError as bs, ToolspaceTokenPathError as bt, type VerifiedWorkspaceArchive as bu, WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION as bv, type WorkspaceArchiveDescriptor as bw, type WorkspaceArchiveIntegrityCode as bx, WorkspaceArchiveIntegrityError as by, type WorkspaceTreeFingerprint as bz, type ActivePointer as c, toolspaceTokenFileFromEnvironment as c$, establishSandboxSessionFromEnvelope as c0, execDeadlineHint as c1, exposeStreamPort as c2, extForCodec as c3, fingerprintSandboxWorkspace as c4, hasPersistableSandboxProviderIdentity as c5, inspectRecordingArtifact as c6, isExecSessionLostBanner as c7, isProviderSandboxGoneDuringRoutedOperation as c8, isProviderSandboxNotFoundError as c9, requirePersistableReplacementSandboxEnvelope as cA, restoredSandboxSessionStateFromEntry as cB, runCredentialPointerFile as cC, runCredentialRoot as cD, runWithToolCallCorrelation as cE, sandboxStateEntryFromRunState as cF, sanitizeOpIdToken as cG, selectBackend as cH, selfhostedFaultClass as cI, selfhostedLiveness as cJ, selfhostedRetryBackoffMs as cK, serializeEstablishedSandboxEnvelope as cL, serializeReplacementSandboxEnvelope as cM, setSelfhostedApplyDiff as cN, startRecording as cO, stopRecording as cP, stripExecBanner as cQ, subjectFor as cR, swapTargetEstablishability as cS, sweepModalOrphanSandboxes as cT, tagModalSandbox as cU, tearDownDisplayStack as cV, tearDownTerminalServer as cW, terminateModalSandboxById as cX, timeoutAgentError as cY, timeoutControlResponse as cZ, toolspaceTokenFileForSession as c_, isProviderSandboxTransientError as ca, isSelfhostedProviderNotFoundError as cb, makeActiveBackendResolver as cc, materializeRunCredentials as cd, mintStreamToken as ce, modalSandboxAttributionEnvironment as cf, modalSandboxAttributionTags as cg, negotiateCapabilities as ch, negotiateSelfhostedCapabilities as ci, nextDurableOpId as cj, normalizeRunCredentialsResolution as ck, offlineAgentError as cl, offlineControlResponse as cm, opAckSubject as cn, opFrameSubject as co, parseExecBannerExitCode as cp, parseExecBannerSessionId as cq, parseNumstatZ as cr, parsePorcelainV2 as cs, parseUnifiedPatch as ct, parseWorkspaceArchiveDescriptor as cu, payloadTooLargeMessage as cv, readVerifiedWorkspaceArchive as cw, readWorkspaceArchiveFromEnvelopeSessionState as cx, recordingStorageKey as cy, renderSelfhostedFault as cz, type ChannelAEmitter as d, uploadRecordingArtifact as d0, verifyRestoredWorkspace as d1, verifySandboxExecReadiness as d2, verifyStreamToken as d3, withRunCredentialEnvironment as d4, withRunCredentialsClient as d5, withRunCredentialsSession as d6, withToolspaceTokenClient as d7, withToolspaceTokenEnvironment as d8, withToolspaceTokenSession as d9, type ChannelAExecArgs as e, type ChannelAExecResult as f, ChannelANotFoundError as g, type ChannelASession as h, ChannelAUnavailableError as i, ChannelAUnsupportedError as j, ChannelAValidationError as k, type ControlRpc as l, DISPLAY_STACK_TIMEOUT_MS as m, type DefaultBackendLossResult as n, type DesktopGeometry as o, type DisplayStackCallerKind as p, type DisplayStackClassification as q, DisplayStackError as r, type DisplayStackTelemetryContext as s, type DisplayStackTelemetryEvent as t, type DisplayStackTelemetryStatus as u, DisplayStackUnsupportedError as v, type EnsureDisplayStackResult as w, type EnsureTerminalServerOptions as x, type EnsureTerminalServerResult as y, type EstablishedSandboxSession as z };