@opengeni/runtime 0.2.3 → 0.3.0

package/dist/sandbox/index.d.ts

@@ -3,6 +3,7 @@ export { collectSandboxEnvironment, parseExposedPorts } from '@opengeni/config';
 import { SandboxBackend, CapabilityDescriptor, SandboxOs, SessionCapabilities, StreamTokenPayload, SessionEventType, SessionStructuredCapabilities, FsListRequest, FsListResponse, FsReadRequest, FsReadResponse, FsWriteRequest, FsWriteResponse, FsDeleteRequest, FsDeleteResponse, FsMoveRequest, FsMoveResponse, FsMkdirRequest, FsMkdirResponse, GitStatusRequest, GitStatusResponse, GitDiffRequest, GitDiffResponse, GitLogRequest, GitLogResponse, GitShowRequest, GitShowResponse, TerminalExecRequest, TerminalExecResponse, PtyOpenRequest, PtyOpenResponse, PtyWriteRequest, PtyResizeRequest, PtyCloseRequest, GitChangedPayload, GitDiffHunk, GitFileStatusCode, CapabilityUnavailableReason } from '@opengeni/contracts';
 export { CAPABILITY_DESCRIPTORS, CapabilityDescriptor, DESKTOP_STREAM_PORT, StreamTokenPayload, StreamTokenPayload as StreamTokenPayloadType, TERMINAL_STREAM_PORT } from '@opengeni/contracts';
 import { Manifest, SandboxClient, SandboxSessionState } from '@openai/agents/sandbox';
+import * as modal from 'modal';
 import { ControlRequest, ControlResponse, ErrorCode, AgentError, DesktopInputRequest, ExecRequest, ExecResponse } from '@opengeni/agent-proto';
 
 /**
@@ -61,6 +62,38 @@ declare const PROVIDER_REGISTRY: Record<SandboxBackend, ProviderRegistration>;
  */
 declare function assertProviderRegistryInvariants(): void;
 
+type ModalSandboxAttribution = {
+    leaseId: string;
+    workspaceId: string;
+    sandboxGroupId: string;
+};
+type LiveModalSandboxLeaseAttribution = ModalSandboxAttribution & {
+    instanceId: string | null;
+    liveness?: string;
+};
+type ModalOrphanSweepTermination = {
+    sandboxId: string;
+    reason: "stale_attribution" | "unattributed";
+    tags: Record<string, string>;
+};
+type ModalOrphanSweepResult = {
+    examined: number;
+    terminated: ModalOrphanSweepTermination[];
+    skipped: number;
+};
+declare function modalSandboxAttributionEnvironment(input: ModalSandboxAttribution): Record<string, string>;
+declare function modalSandboxAttributionTags(input: ModalSandboxAttribution): Record<string, string>;
+type ModalModule = typeof modal;
+type ModalClientLike = InstanceType<ModalModule["ModalClient"]>;
+declare function tagModalSandbox(settings: Settings, sandboxId: string, attribution: ModalSandboxAttribution): Promise<boolean>;
+declare function terminateModalSandboxById(settings: Settings, sandboxId: string): Promise<boolean>;
+declare function sweepModalOrphanSandboxes(settings: Settings, liveLeases: LiveModalSandboxLeaseAttribution[], options?: {
+    now?: Date;
+    maxTerminations?: number;
+    unattributedGraceMs?: number;
+    client?: ModalClientLike;
+}): Promise<ModalOrphanSweepResult>;
+
 interface NegotiationContext {
     sessionId: string;
     backend: SandboxBackend;
@@ -1051,11 +1084,18 @@ declare class SelfhostedSession {
     /** Computer-use VIEW op: capture a single PNG screenshot of the machine's desktop
      *  plus its geometry (via ScreenCaptureKit / x11). NOT consent-gated (a view op —
      *  the view/control decoupling), so it works with a display but no screen-control
-     *  consent. Returns the raw encoded bytes + width/height. */
+     *  consent. Returns the raw encoded bytes + the ENCODED width/height, plus the
+     *  NATIVE (pre-downscale) geometry: when the agent had to downscale the PNG to fit
+     *  the transport's max payload, `nativeWidth`/`nativeHeight` carry the original
+     *  capture size so the computer-use layer can scale model clicks (in encoded-pixel
+     *  space) back to native pixels. An older agent leaves them 0 → read as "same as
+     *  width/height" (no downscale). */
     screenshot(): Promise<{
         png: Uint8Array;
         width: number;
         height: number;
+        nativeWidth: number;
+        nativeHeight: number;
     }>;
     /** A cheap liveness probe — request a Ping on the subject; returns true iff a
      *  responder answered (no AgentError). Used by `negotiateSelfhostedCapabilities`.
@@ -1375,6 +1415,8 @@ interface RoutableBackendSession {
         png: Uint8Array;
         width: number;
         height: number;
+        nativeWidth: number;
+        nativeHeight: number;
     }>;
 }
 /** The resolved active backend for an epoch: the live session + the sandbox id it
@@ -1457,6 +1499,8 @@ declare class RoutingSandboxSession implements RoutableBackendSession {
         png: Uint8Array;
         width: number;
         height: number;
+        nativeWidth: number;
+        nativeHeight: number;
     }>;
     constructor(deps: RoutingSandboxSessionDeps);
     /**
@@ -1689,6 +1733,7 @@ type EstablishedSandboxSession = {
     instanceId: string;
     backendId: string;
 };
+type SandboxCreatedCallback = (established: EstablishedSandboxSession) => Promise<void>;
 /**
  * Per-provider NotFound discriminator. The @openai/agents-extensions
  * `isProviderSandboxNotFoundError` / `assertResumeRecreateAllowed` helpers live
@@ -1722,6 +1767,7 @@ declare function establishSandboxSessionFromEnvelope(settings: Settings, envelop
     sessionId: string;
     backendOverride?: SandboxBackend;
     environment?: Record<string, string>;
+    onSandboxCreated?: SandboxCreatedCallback;
 }): Promise<EstablishedSandboxSession>;
 /**
  * Fold a freshly-established (or resumed) sandbox session into the persistable
@@ -1737,4 +1783,4 @@ declare function establishSandboxSessionFromEnvelope(settings: Settings, envelop
  */
 declare function serializeEstablishedSandboxEnvelope(established: EstablishedSandboxSession): Promise<Record<string, unknown> | null>;
 
-export { type ActiveBackendResolverDeps, ActiveBackendUnresolvableError, type ActivePointer, ChannelAConflictError, type ChannelAEmitter, type ChannelAExecArgs, type ChannelAExecResult, ChannelANotFoundError, type ChannelASession, ChannelAUnsupportedError, ChannelAValidationError, type ControlRpc, DEFAULT_DESKTOP_GEOMETRY, DISPLAY_STACK_TIMEOUT_MS, type DesktopGeometry, DisplayStackError, DisplayStackUnsupportedError, type EnsureDisplayStackOptions, type EnsureDisplayStackResult, type EnsureTerminalServerOptions, type EnsureTerminalServerResult, type EstablishedSandboxSession, type ExposeStreamPortInput, type ExposeStreamPortResult, type ExposedPortEndpoint, type FinalizeRecordingResult, type MintStreamTokenInput, MockAgentResponder, type MockAgentResponderOptions, type MockExecHandler, NatsControlRpc, type NatsRequestConnection, type NegotiationContext, type NumstatEntry, PROVIDER_REGISTRY, type ProviderConstructionContext, type ProviderRegistration, type RecordingCodec, type RecordingContentType, RecordingError, type RecordingProcess, RecordingUnavailableError, type ResolvedActiveBackend, type RoutableBackendSession, type RoutableSandbox, RoutingSandboxSession, type RoutingSandboxSessionDeps, type RoutingTransitionEvent, RoutingUnsupportedError, SELFHOSTED_DEFAULT_TIMEOUT_MS, SELFHOSTED_RECONNECT_WINDOW_MS, SELFHOSTED_RELAY_STREAM_PATH, STREAM_PORT, STREAM_TOKEN_DEFAULT_TTL_SECONDS, SandboxChannelAService, type SandboxChannelAServiceOptions, SandboxConfigError, SandboxProviderUnavailableError, type SelfhostedApplyDiff, SelfhostedControlError, type SelfhostedEditor, type SelfhostedEnrollment, type SelfhostedExecArgs, type SelfhostedExecResult, type SelfhostedImageOutput, type SelfhostedLivenessState, type SelfhostedNegotiationInput, type SelfhostedRelayConfig, SelfhostedSandboxClient, SelfhostedSession, type SelfhostedSessionBuild, type SelfhostedSessionDeps, type SelfhostedSessionState, type SelfhostedUnavailableReason, type StartRecordingInput, StreamPortUnavailableError, TERMINAL_SERVER_TIMEOUT_MS, TerminalServerError, TerminalServerUnsupportedError, agentErrorToControlError, assertDescriptorRegistryInvariants, assertProviderRegistryInvariants, assertSafeRelPath, backendSupportsOs, buildDisplayStackScript, buildSelfhostedBackendSession, buildStreamUrl, buildTerminalServerScript, contentTypeForCodec, createSandboxClient, createSandboxClientForBackend, decodeModalSnapshotId, deletePriorPersistedSnapshot, deleteRecordingArtifacts, deserializeSandboxSessionStateEnvelope, desktopCapableBackend, ensureDisplayStack, ensureTerminalServer, establishSandboxSessionFromEnvelope, exposeStreamPort, extForCodec, isExecSessionLostBanner, isProviderSandboxNotFoundError, isSelfhostedProviderNotFoundError, isWorkspaceEscapeError, makeActiveBackendResolver, mintStreamToken, negotiateCapabilities, negotiateSelfhostedCapabilities, offlineAgentError, offlineControlResponse, parseExecBannerSessionId, parseNumstatZ, parsePorcelainV2, parseUnifiedPatch, readRecordingBytes, readWorkspaceArchiveFromEnvelopeSessionState, recordingStorageKey, restoredSandboxSessionStateFromEntry, sandboxStateEntryFromRunState, selectBackend, selfhostedLiveness, serializeEstablishedSandboxEnvelope, setSelfhostedApplyDiff, startRecording, stopRecording, stripExecBanner, subjectFor, tearDownDisplayStack, tearDownTerminalServer, timeoutAgentError, timeoutControlResponse, verifyStreamToken };
+export { type ActiveBackendResolverDeps, ActiveBackendUnresolvableError, type ActivePointer, ChannelAConflictError, type ChannelAEmitter, type ChannelAExecArgs, type ChannelAExecResult, ChannelANotFoundError, type ChannelASession, ChannelAUnsupportedError, ChannelAValidationError, type ControlRpc, DEFAULT_DESKTOP_GEOMETRY, DISPLAY_STACK_TIMEOUT_MS, type DesktopGeometry, DisplayStackError, DisplayStackUnsupportedError, type EnsureDisplayStackOptions, type EnsureDisplayStackResult, type EnsureTerminalServerOptions, type EnsureTerminalServerResult, type EstablishedSandboxSession, type ExposeStreamPortInput, type ExposeStreamPortResult, type ExposedPortEndpoint, type FinalizeRecordingResult, type LiveModalSandboxLeaseAttribution, type MintStreamTokenInput, MockAgentResponder, type MockAgentResponderOptions, type MockExecHandler, type ModalOrphanSweepResult, type ModalSandboxAttribution, NatsControlRpc, type NatsRequestConnection, type NegotiationContext, type NumstatEntry, PROVIDER_REGISTRY, type ProviderConstructionContext, type ProviderRegistration, type RecordingCodec, type RecordingContentType, RecordingError, type RecordingProcess, RecordingUnavailableError, type ResolvedActiveBackend, type RoutableBackendSession, type RoutableSandbox, RoutingSandboxSession, type RoutingSandboxSessionDeps, type RoutingTransitionEvent, RoutingUnsupportedError, SELFHOSTED_DEFAULT_TIMEOUT_MS, SELFHOSTED_RECONNECT_WINDOW_MS, SELFHOSTED_RELAY_STREAM_PATH, STREAM_PORT, STREAM_TOKEN_DEFAULT_TTL_SECONDS, SandboxChannelAService, type SandboxChannelAServiceOptions, SandboxConfigError, type SandboxCreatedCallback, SandboxProviderUnavailableError, type SelfhostedApplyDiff, SelfhostedControlError, type SelfhostedEditor, type SelfhostedEnrollment, type SelfhostedExecArgs, type SelfhostedExecResult, type SelfhostedImageOutput, type SelfhostedLivenessState, type SelfhostedNegotiationInput, type SelfhostedRelayConfig, SelfhostedSandboxClient, SelfhostedSession, type SelfhostedSessionBuild, type SelfhostedSessionDeps, type SelfhostedSessionState, type SelfhostedUnavailableReason, type StartRecordingInput, StreamPortUnavailableError, TERMINAL_SERVER_TIMEOUT_MS, TerminalServerError, TerminalServerUnsupportedError, agentErrorToControlError, assertDescriptorRegistryInvariants, assertProviderRegistryInvariants, assertSafeRelPath, backendSupportsOs, buildDisplayStackScript, buildSelfhostedBackendSession, buildStreamUrl, buildTerminalServerScript, contentTypeForCodec, createSandboxClient, createSandboxClientForBackend, decodeModalSnapshotId, deletePriorPersistedSnapshot, deleteRecordingArtifacts, deserializeSandboxSessionStateEnvelope, desktopCapableBackend, ensureDisplayStack, ensureTerminalServer, establishSandboxSessionFromEnvelope, exposeStreamPort, extForCodec, isExecSessionLostBanner, isProviderSandboxNotFoundError, isSelfhostedProviderNotFoundError, isWorkspaceEscapeError, makeActiveBackendResolver, mintStreamToken, modalSandboxAttributionEnvironment, modalSandboxAttributionTags, negotiateCapabilities, negotiateSelfhostedCapabilities, offlineAgentError, offlineControlResponse, parseExecBannerSessionId, parseNumstatZ, parsePorcelainV2, parseUnifiedPatch, readRecordingBytes, readWorkspaceArchiveFromEnvelopeSessionState, recordingStorageKey, restoredSandboxSessionStateFromEntry, sandboxStateEntryFromRunState, selectBackend, selfhostedLiveness, serializeEstablishedSandboxEnvelope, setSelfhostedApplyDiff, startRecording, stopRecording, stripExecBanner, subjectFor, sweepModalOrphanSandboxes, tagModalSandbox, tearDownDisplayStack, tearDownTerminalServer, terminateModalSandboxById, timeoutAgentError, timeoutControlResponse, verifyStreamToken };

package/dist/sandbox/index.js

@@ -63,6 +63,8 @@ import {
   isWorkspaceEscapeError,
   makeActiveBackendResolver,
   mintStreamToken,
+  modalSandboxAttributionEnvironment,
+  modalSandboxAttributionTags,
   negotiateCapabilities,
   negotiateSelfhostedCapabilities,
   offlineAgentError,
@@ -85,12 +87,15 @@ import {
   stopRecording,
   stripExecBanner,
   subjectFor,
+  sweepModalOrphanSandboxes,
+  tagModalSandbox,
   tearDownDisplayStack,
   tearDownTerminalServer,
+  terminateModalSandboxById,
   timeoutAgentError,
   timeoutControlResponse,
   verifyStreamToken
-} from "../chunk-KNW7AMQB.js";
+} from "../chunk-D5KU3QUC.js";
 export {
   ActiveBackendUnresolvableError,
   CAPABILITY_DESCRIPTORS,
@@ -156,6 +161,8 @@ export {
   isWorkspaceEscapeError,
   makeActiveBackendResolver,
   mintStreamToken,
+  modalSandboxAttributionEnvironment,
+  modalSandboxAttributionTags,
   negotiateCapabilities,
   negotiateSelfhostedCapabilities,
   offlineAgentError,
@@ -178,8 +185,11 @@ export {
   stopRecording,
   stripExecBanner,
   subjectFor,
+  sweepModalOrphanSandboxes,
+  tagModalSandbox,
   tearDownDisplayStack,
   tearDownTerminalServer,
+  terminateModalSandboxById,
   timeoutAgentError,
   timeoutControlResponse,
   verifyStreamToken

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/runtime",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -29,8 +29,8 @@
   },
   "dependencies": {
     "@opengeni/agent-proto": "^0.2.1",
-    "@opengeni/config": "^0.2.3",
-    "@opengeni/contracts": "^0.5.0",
+    "@opengeni/config": "^0.2.4",
+    "@opengeni/contracts": "^0.6.0",
     "@openai/agents": "^0.11.6",
     "@openai/agents-extensions": "^0.11.6",
     "modal": "^0.7.4",

package/src/index.ts

@@ -441,7 +441,7 @@ export class MultiProviderModelProvider implements ModelProvider {
 
   async getModel(modelName?: string): Promise<Model> {
     if (modelName) {
-      const resolved = resolveTurnModel(this.settings, modelName);
+      const resolved = resolveTurnModel(settingsForRunScopedModelResolution(this.settings, modelName), modelName);
       if (resolved) {
         // Fail-loud floor (defense in depth): a `codex/<slug>` id must only ever
         // resolve through the synthetic codex-subscription provider (which installs
@@ -479,6 +479,27 @@ export class MultiProviderModelProvider implements ModelProvider {
   }
 }
 
+function settingsForRunScopedModelResolution(settings: Settings, modelName: string): Settings {
+  if (modelName !== settings.openaiModel) {
+    return settings;
+  }
+  const builtinAllowed = splitOpenaiAllowedModels(settings.openaiAllowedModels);
+  const fallbackBuiltin = builtinAllowed.find((id) => id !== modelName);
+  if (!fallbackBuiltin) {
+    return settings;
+  }
+  // The worker sets runSettings.openaiModel to the turn's model. For namespaced
+  // registry ids configuredModels filters the built-in entry out, but a unique
+  // bare registry id would otherwise be claimed by the built-in only because of
+  // that per-turn override. Resolve the run-scoped router against the deployment
+  // allow-list head instead; real built-in models stay in the allow-list.
+  return builtinAllowed.includes(modelName) ? settings : { ...settings, openaiModel: fallbackBuiltin };
+}
+
+function splitOpenaiAllowedModels(value: string): string[] {
+  return value.split(",").map((item) => item.trim()).filter(Boolean);
+}
+
 /**
  * A `codex/<slug>` turn reached the model router but the workspace has no active
  * Codex subscription connected (the worker overlay never injected the synthetic
@@ -711,6 +732,14 @@ export type BuildAgentOptions = {
   // restyle the persona but never drop the goal-loop contract or environment
   // block.
   instructionsTemplate?: string;
+  // Per-SESSION persona/system instructions (the per-agent-type prompt lever an
+  // embedding host supplies at session create). Composed AFTER the workspace
+  // instructionsTemplate + the non-bypassable CORE, so it refines the workspace
+  // persona for this one session without dropping the goal-loop/environment
+  // contract. Rides the SAME instructions channel (system-level) — NEVER a user/
+  // timeline message. Omitted ⇒ the composed instructions are byte-identical to
+  // a workspace-only persona.
+  sessionInstructions?: string;
   // Skills delivered by enabled capability packs. They join the bundled
   // skills in the sandbox skill index (mounted under .agents/) so
   // skills/<name> references resolve like any other indexed skill.
@@ -793,6 +822,27 @@ export function composeAgentInstructions(template: string, workspaceEnvironment?
   return core ? `${template} ${core}` : template;
 }
 
+/**
+ * Appends the per-session persona instructions to the already-composed
+ * (workspace + CORE) instructions, joined by " " — exactly the join used
+ * throughout the persona composition. The session slice is intentionally LAST
+ * (session-specific refinement of the workspace persona). An absent/blank value
+ * is a no-op that returns the composed string byte-for-byte.
+ */
+export function appendSessionInstructions(composed: string, sessionInstructions?: string): string {
+  const trimmed = sessionInstructions?.trim();
+  return trimmed ? `${composed} ${trimmed}` : composed;
+}
+
+/**
+ * Appends the one-shot genesis title directive (genesis turn only), joined by
+ * " " and always LAST so a white-label persona template or a per-session
+ * instruction can't drop it. A no-op when the hint is absent.
+ */
+export function appendGenesisTitleDirective(instructions: string, genesisTitleHint?: boolean): string {
+  return genesisTitleHint ? `${instructions} ${GENESIS_TITLE_DIRECTIVE}` : instructions;
+}
+
 const agentFileDownloads = new WeakMap<object, SandboxFileDownload[]>();
 const agentRepositoryCloneHooks = new WeakMap<object, SandboxLifecycleHook[]>();
 // TOKEN-BROKER (B1): the per-turn git token seed, stashed alongside the agent's
@@ -837,9 +887,21 @@ export function buildOpenGeniAgent(settings: Settings, resources: ResourceRef[],
     // ownership + workspace-environment block) at the {{core}} marker, or
     // appends it when the template omits the marker. With the default template
     // and no environment this is byte-identical to the historical preamble.
-    instructions: options.genesisTitleHint
-      ? `${composeAgentInstructions(options.instructionsTemplate ?? settings.agentInstructionsTemplate, options.workspaceEnvironment)} ${GENESIS_TITLE_DIRECTIVE}`
-      : composeAgentInstructions(options.instructionsTemplate ?? settings.agentInstructionsTemplate, options.workspaceEnvironment),
+    // Persona composition order (all one system-level instructions string):
+    //   1. workspace instructionsTemplate (or deployment default) with the
+    //      non-bypassable CORE substituted at {{core}} — composeAgentInstructions,
+    //   2. + the per-session persona instructions (session-specific, LAST so it
+    //      refines the workspace persona),
+    //   3. + the one-shot genesis title directive (genesis turn only).
+    // With no session instructions and no genesis hint this is byte-identical to
+    // the historical composed instructions.
+    instructions: appendGenesisTitleDirective(
+      appendSessionInstructions(
+        composeAgentInstructions(options.instructionsTemplate ?? settings.agentInstructionsTemplate, options.workspaceEnvironment),
+        options.sessionInstructions,
+      ),
+      options.genesisTitleHint,
+    ),
     modelSettings: {
       reasoning: { effort: options.reasoningEffort ?? settings.openaiReasoningEffort, summary: "detailed" },
       // Server-side compaction (OpenAI platform) requires store=false: the

package/src/sandbox/display-stack.ts

@@ -32,10 +32,34 @@ export const STREAM_PORT = DESKTOP_STREAM_PORT;
 export const DISPLAY_STACK_TIMEOUT_MS = 90_000;
 
 // PAINTABLE-FRAME gate: poll scrot up to this many times, this many seconds apart,
-// waiting for a non-empty frame before declaring the stack "up" (~30s worst case).
+// waiting for an actually-PAINTED frame before declaring the stack "up" (~30s worst case).
 const PAINT_PROBE_ATTEMPTS = 150;
 const PAINT_PROBE_INTERVAL_S = 0.2;
 
+// The paint FLOOR (bytes): a scrot at/above this size is a real painted desktop; below
+// it, the root is still unpainted and the frame would read as "blank" to the model.
+//
+// WHY A SIZE FLOOR, NOT NON-EMPTINESS (the bug this fixes): the old gate only checked
+// `[ -s frame.png ]` (non-empty). But an UNPAINTED root is never zero-byte — a fresh
+// Xvfb draws either the `-retro` weave stipple or (with `-retro` dropped) solid black,
+// and scrot happily encodes that as a small-but-non-empty PNG. So the old gate passed
+// the instant the VNC ports bound — MEASURED at ~1.4s (fast runc host) to several
+// seconds (cold gVisor) BEFORE xfdesktop finishes its first wallpaper paint — handing
+// the model the pre-paint frame. That pre-paint frame is exactly the "blank/black"
+// screenshot that 400s the model and blanks the human viewer.
+//
+// The sizes are unambiguous and were measured on the canonical desktop image (1280x800)
+// under runc — both the current staging image and a fresh local build:
+//   painted XFCE desktop (blue-gradient wallpaper + panel + icons): ~210-222 KB
+//   `-retro` stipple root (unpainted, current image):                ~17 KB
+//   solid-black root (unpainted, after we drop `-retro`):            ~13.5 KB
+// 60 KB sits ~3.5x above every unpainted state and ~3.5x below a real paint — a wide,
+// unambiguous margin. It holds against BOTH the currently-deployed `-retro` image and
+// the `-retro`-dropped image this change ships, so the runtime gate is correct before
+// AND after the image rebuild lands. (Assumes the default ~1280x800 geometry; a larger
+// framebuffer only scales the painted frame further above the floor.)
+const PAINT_MIN_BYTES = 60_000;
+
 /** Desktop geometry for the framebuffer. v1 has no live RANDR: a resolution
  *  change is a full down -> up restart (a separate op). */
 export type DesktopGeometry = {
@@ -145,18 +169,25 @@ export function buildDisplayStackScript(options: EnsureDisplayStackOptions = {})
   // PAINTABLE-FRAME GATE (the completion criterion): the up-script's readiness gates
   // only assert that Xvfb answers xdpyinfo and that x11vnc:5900 + websockify:PORT are
   // LISTENING — NOT that the display actually PAINTS. On a stone-cold gVisor box (the
-  // machine→sandbox swap-recovery turn always hits one), Xvfb can answer and the VNC
-  // ports can bind seconds BEFORE the root window / XFCE compositor is drawable, so a
-  // scrot right after the `OPENGENI_DESKTOP_UP` marker yields a ZERO-BYTE frame — which
-  // is exactly the empty screenshot that 400s the model and blanks the human viewer.
+  // machine→sandbox swap-recovery turn always hits one), Xvfb answers and the VNC ports
+  // bind ~1.4s (fast host) to several seconds BEFORE xfdesktop finishes its first
+  // wallpaper paint. In that window a scrot yields a small UNPAINTED frame (the -retro
+  // stipple or a solid-black root) — never zero-byte — which is exactly the "blank/black"
+  // screenshot that 400s the model and blanks the human viewer. (VERIFIED locally: the
+  // real xfdesktop backdrop window maps at full 1280x800 the whole time; the render is
+  // never structurally broken — it is purely this pre-paint capture race.)
+  //
   // We therefore chain a real scrot probe as the completion gate: after the up-script
-  // reports success, poll scrot until it produces a NON-EMPTY frame (bounded ~30s), and
-  // only THEN let the command exit 0. If it never paints we exit 14 so the caller sees a
-  // typed DisplayStackError("paint") — an HONEST failure the worker can degrade + log,
-  // rather than a false "up" that hands the model an empty image. `-ac` on Xvfb disables
+  // reports success, poll scrot until it produces an actually-PAINTED frame — a PNG at or
+  // above PAINT_MIN_BYTES, not merely NON-EMPTY (the old `[ -s ]` check passed on the
+  // ~17 KB pre-paint stipple immediately; that WAS the bug) — bounded ~30s, and only THEN
+  // let the command exit 0. If it never paints we exit 14 so the caller sees a typed
+  // DisplayStackError("paint") — an HONEST failure the worker can degrade + log, rather
+  // than a false "up" that hands the model an unpainted image. `-ac` on Xvfb disables
   // access control so this root-side scrot reaches :0. Runs on a pre-check hit too (cheap
   // — an already-up display paints on the first probe). Lives in the runtime-built script
-  // (not the baked image up-script) so it ships with the worker/api, no image rebuild.
+  // (not the baked image up-script) so it ships with the worker/api, no image rebuild —
+  // and its size floor holds against the currently-deployed image too.
   const bringUp =
     `if nc -z 127.0.0.1 ${port} >/dev/null 2>&1 && nc -z 127.0.0.1 5900 >/dev/null 2>&1; then ` +
     `echo "OPENGENI_DESKTOP_UP port=${port} geometry=${geometry.width}x${geometry.height} dpi=${geometry.dpi} (precheck)"; ` +
@@ -168,11 +199,15 @@ export function buildDisplayStackScript(options: EnsureDisplayStackOptions = {})
   const paintProbe =
     `p=/tmp/opengeni-desktop/paint-probe.png; ` +
     `for i in $(seq 1 ${PAINT_PROBE_ATTEMPTS}); do ` +
-    `if DISPLAY=:0 scrot -o "$p" >/dev/null 2>&1 && [ -s "$p" ]; then rm -f "$p"; break; fi; ` +
+    // Capture, then measure the PNG byte-size. `wc -c < "$p"` yields a bare integer; a
+    // failed scrot leaves sz=0. A frame at/above PAINT_MIN_BYTES is a real painted desktop.
+    `if DISPLAY=:0 scrot -o "$p" >/dev/null 2>&1; then sz=$(wc -c < "$p" 2>/dev/null || echo 0); else sz=0; fi; ` +
     `rm -f "$p"; ` +
+    `if [ "$sz" -ge ${PAINT_MIN_BYTES} ]; then break; fi; ` +
     // NOTE: NOT_PAINTING goes to STDOUT (not stderr): Modal is execCommand-only, so the
     // caller infers the outcome by string-matching the output — stdout is always captured.
-    `if [ "$i" = "${PAINT_PROBE_ATTEMPTS}" ]; then echo "OPENGENI_DESKTOP_NOT_PAINTING scrot empty after warmup"; exit 14; fi; ` +
+    // ($sz is bare shell here — no ${} braces — so JS leaves it for bash to expand.)
+    `if [ "$i" = "${PAINT_PROBE_ATTEMPTS}" ]; then echo "OPENGENI_DESKTOP_NOT_PAINTING scrot below ${PAINT_MIN_BYTES}B after warmup (last=$sz)"; exit 14; fi; ` +
     `sleep ${PAINT_PROBE_INTERVAL_S}; ` +
     `done`;
   return `mkdir -p /tmp/opengeni-desktop; { ${bringUp} ; } && { ${paintProbe} ; }`;

package/src/sandbox/index.ts

@@ -53,6 +53,16 @@ export {
   type ProviderRegistration,
   type ProviderConstructionContext,
 } from "./providers";
+export {
+  modalSandboxAttributionEnvironment,
+  modalSandboxAttributionTags,
+  sweepModalOrphanSandboxes,
+  tagModalSandbox,
+  terminateModalSandboxById,
+  type LiveModalSandboxLeaseAttribution,
+  type ModalOrphanSweepResult,
+  type ModalSandboxAttribution,
+} from "./providers/modal";
 export {
   selectBackend,
   backendSupportsOs,
@@ -540,6 +550,8 @@ export type EstablishedSandboxSession = {
   backendId: string;
 };
 
+export type SandboxCreatedCallback = (established: EstablishedSandboxSession) => Promise<void>;
+
 // The structural slice we need from a provider SandboxClient to resume by id and
 // cold-restore. Narrowed (not the full agent-loop SandboxClient) so the leaf
 // stays agent-loop-free.
@@ -616,6 +628,16 @@ function readInstanceId(session: unknown): string {
   return typeof candidate === "string" && candidate.length > 0 ? candidate : "";
 }
 
+async function terminateCreatedSandbox(client: ResumeCapableClient, session: unknown, sessionState: unknown): Promise<void> {
+  const clientWithDelete = client as { delete?: (state: unknown) => Promise<unknown> };
+  if (typeof clientWithDelete.delete === "function" && sessionState !== undefined) {
+    try { await clientWithDelete.delete(sessionState); } catch { /* best-effort */ }
+    return;
+  }
+  const sess = session as { close?: () => Promise<unknown>; terminate?: () => Promise<unknown>; kill?: () => Promise<unknown> };
+  try { await (sess.terminate ?? sess.kill ?? sess.close)?.(); } catch { /* best-effort */ }
+}
+
 /**
  * Resume the one box by id from its recovery envelope, or cold-restore from the
  * snapshot when the provider reports it gone. The envelope is the lease's
@@ -633,7 +655,12 @@ function readInstanceId(session: unknown): string {
 export async function establishSandboxSessionFromEnvelope(
   settings: Settings,
   envelope: Record<string, unknown> | null,
-  opts: { sessionId: string; backendOverride?: SandboxBackend; environment?: Record<string, string> },
+  opts: {
+    sessionId: string;
+    backendOverride?: SandboxBackend;
+    environment?: Record<string, string>;
+    onSandboxCreated?: SandboxCreatedCallback;
+  },
 ): Promise<EstablishedSandboxSession> {
   const envelopeBackend = typeof envelope?.backendId === "string" ? (envelope.backendId as SandboxBackend) : undefined;
   const backend = (opts.backendOverride ?? envelopeBackend ?? (settings.sandboxBackend as SandboxBackend));
@@ -680,6 +707,22 @@ export async function establishSandboxSessionFromEnvelope(
   // cold-restore branch (b) below.
   const coldRestore = async (resumeFallbackState?: unknown): Promise<EstablishedSandboxSession> => {
     const restored = await client.create!({ manifest: createManifest });
+    let restoredState = (restored as { state?: unknown }).state;
+    let established: EstablishedSandboxSession = {
+      client,
+      session: restored,
+      sessionState: restoredState ?? resumeFallbackState,
+      instanceId: readInstanceId(restored),
+      backendId: client.backendId,
+    };
+    if (opts.onSandboxCreated) {
+      try {
+        await opts.onSandboxCreated(established);
+      } catch (createCallbackError) {
+        await terminateCreatedSandbox(client, restored, restoredState);
+        throw createCallbackError;
+      }
+    }
     if (workspaceArchive) {
       const hydrate = (restored as { hydrateWorkspace?: (data: Uint8Array) => Promise<void> }).hydrateWorkspace;
       if (typeof hydrate === "function") {
@@ -696,21 +739,38 @@ export async function establishSandboxSessionFromEnvelope(
           // re-throwing so no box leaks. The original error semantics are preserved
           // (the re-throw propagates to the caller). This mirrors the reaper's
           // discipline: NEVER leave an orphaned box running.
-          const restoredState = (restored as { state?: unknown }).state;
-          const clientWithDelete = client as { delete?: (state: unknown) => Promise<unknown> };
-          if (typeof clientWithDelete.delete === "function" && restoredState !== undefined) {
-            try { await clientWithDelete.delete(restoredState); } catch { /* best-effort; re-throw the hydrate error below */ }
-          } else {
-            // No delete() — try a session-level close/terminate as a fallback.
-            const sess = restored as { close?: () => Promise<unknown>; terminate?: () => Promise<unknown> };
-            try { await (sess.terminate ?? sess.close)?.(); } catch { /* best-effort */ }
-          }
+          await terminateCreatedSandbox(client, restored, restoredState);
           throw hydrateError;
         }
+        const hydratedState = (restored as { state?: unknown }).state;
+        const hydratedInstanceId = readInstanceId(restored);
+        if (hydratedInstanceId && hydratedInstanceId !== established.instanceId) {
+          established = {
+            client,
+            session: restored,
+            sessionState: hydratedState ?? resumeFallbackState,
+            instanceId: hydratedInstanceId,
+            backendId: client.backendId,
+          };
+          if (opts.onSandboxCreated) {
+            try {
+              await opts.onSandboxCreated(established);
+            } catch (createCallbackError) {
+              await terminateCreatedSandbox(client, restored, hydratedState);
+              throw createCallbackError;
+            }
+          }
+        }
       }
     }
-    const restoredState = (restored as { state?: unknown }).state;
-    return { client, session: restored, sessionState: restoredState ?? resumeFallbackState, instanceId: readInstanceId(restored), backendId: client.backendId };
+    restoredState = (restored as { state?: unknown }).state;
+    return {
+      client,
+      session: restored,
+      sessionState: restoredState ?? resumeFallbackState,
+      instanceId: readInstanceId(restored),
+      backendId: client.backendId,
+    };
   };
 
   // Does the envelope carry a RESUMABLE box id (warm reattach), or only a