@opengeni/runtime 0.2.2 → 0.3.0

package/src/sandbox/display-stack.ts

@@ -24,11 +24,41 @@ import { DESKTOP_STREAM_PORT } from "@opengeni/contracts";
 export { DESKTOP_STREAM_PORT };
 export const STREAM_PORT = DESKTOP_STREAM_PORT;
 
-// The whole-stack launch is bounded by the readiness gates inside the script
-// (four loops of 50 * 0.1s = ~5s each, ~20s worst case) PLUS first-boot XFCE/dbus
-// + font-cache warm-up on a cold gVisor box. 60s gives headroom over the spike's
-// observed ~5-10s warm path without masking a genuine wedge.
-export const DISPLAY_STACK_TIMEOUT_MS = 60_000;
+// The whole-stack launch is bounded by the readiness gates inside the up-script
+// (four loops of 50 * 0.1s = ~5s each, ~20s worst case) PLUS the PAINTABLE-FRAME
+// gate we append (up to ~30s of scrot probing) PLUS first-boot XFCE/dbus + font-cache
+// warm-up on a cold gVisor box. 90s gives headroom over the spike's observed ~5-10s
+// warm path AND the cold-box paint warm-up without masking a genuine wedge.
+export const DISPLAY_STACK_TIMEOUT_MS = 90_000;
+
+// PAINTABLE-FRAME gate: poll scrot up to this many times, this many seconds apart,
+// 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). */
@@ -41,15 +71,25 @@ export type DesktopGeometry = {
 export const DEFAULT_DESKTOP_GEOMETRY: DesktopGeometry = { width: 1280, height: 800, dpi: 96 };
 
 /** Thrown when a stage of the launch script failed. exitCode 11/12/13 map to
- *  Xvfb / x11vnc / websockify respectively (the stage that died). Degradation is
- *  surfaced as a value to viewers by the caller; this error is for diagnostics. */
+ *  Xvfb / x11vnc / websockify respectively (the stage that died); 14 is the
+ *  PAINTABLE-FRAME gate (ports listening but scrot still yields an empty frame —
+ *  the display is up but not actually painting). Degradation is surfaced as a
+ *  value to viewers by the caller; this error is for diagnostics. */
 export class DisplayStackError extends Error {
   readonly exitCode: number;
-  readonly stage: "xvfb" | "x11vnc" | "websockify" | "unknown";
+  readonly stage: "xvfb" | "x11vnc" | "websockify" | "paint" | "unknown";
 
   constructor(exitCode: number, output: string) {
     const stage =
-      exitCode === 11 ? "xvfb" : exitCode === 12 ? "x11vnc" : exitCode === 13 ? "websockify" : "unknown";
+      exitCode === 11
+        ? "xvfb"
+        : exitCode === 12
+          ? "x11vnc"
+          : exitCode === 13
+            ? "websockify"
+            : exitCode === 14
+              ? "paint"
+              : "unknown";
     super(`desktop display stack failed at stage "${stage}" (exit ${exitCode})${output ? `:\n${output}` : ""}`);
     this.name = "DisplayStackError";
     this.exitCode = exitCode;
@@ -125,15 +165,52 @@ export function buildDisplayStackScript(options: EnsureDisplayStackOptions = {})
   // flock -w bounds the wait so a wedged holder can't deadlock the caller; the
   // up-script itself ALSO takes the same lock (belt + braces) so this works even
   // against an older image that predates the wrapper.
-  return (
+  //
+  // 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 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 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 —
+  // 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)"; ` +
     `else ` +
     `mkdir -p /tmp/opengeni-desktop && ` +
     `flock -w 45 /tmp/opengeni-desktop/up.outer.lock ` +
     `env ${env} opengeni-desktop-up; ` +
-    `fi`
-  );
+    `fi`;
+  const paintProbe =
+    `p=/tmp/opengeni-desktop/paint-probe.png; ` +
+    `for i in $(seq 1 ${PAINT_PROBE_ATTEMPTS}); do ` +
+    // 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.
+    // ($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} ; }`;
 }
 
 function execResultOutput(result: ExecResultLike | string): string {
@@ -157,6 +234,13 @@ function execResultExitCode(result: ExecResultLike | string): number | null {
 // bare string), we infer success from the OPENGENI_DESKTOP_UP marker and infer
 // the failing stage from the stage-failure message the script prints to stderr.
 function inferExitFromOutput(output: string): number {
+  // Check the PAINTABLE-FRAME failure FIRST: on that path the up-script already
+  // printed OPENGENI_DESKTOP_UP (bring-up succeeded) and THEN the paint gate failed,
+  // so both markers are present — the NOT_PAINTING one is the authoritative outcome.
+  // (Modal is execCommand-only, so this string-inference path is the live one.)
+  if (/OPENGENI_DESKTOP_NOT_PAINTING/.test(output)) {
+    return 14;
+  }
   if (/OPENGENI_DESKTOP_UP\b/.test(output)) {
     return 0;
   }

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

package/src/sandbox/providers/modal.ts

@@ -1,9 +1,53 @@
 import { ModalImageSelector, ModalSandboxClient } from "@openai/agents-extensions/sandbox/modal";
 import { effectiveModalIdleTimeoutSeconds } from "@opengeni/config";
+import type { Settings } from "@opengeni/config";
 import { CAPABILITY_DESCRIPTORS } from "../capabilities";
 import { SandboxConfigError } from "../errors";
 import type { ProviderRegistration } from "./types";
 
+const MODAL_ORPHAN_SWEEP_LIMIT = 50;
+const MODAL_UNATTRIBUTED_ORPHAN_GRACE_MS = 30 * 60_000;
+
+export type ModalSandboxAttribution = {
+  leaseId: string;
+  workspaceId: string;
+  sandboxGroupId: string;
+};
+
+export type LiveModalSandboxLeaseAttribution = ModalSandboxAttribution & {
+  instanceId: string | null;
+  liveness?: string;
+};
+
+export type ModalOrphanSweepTermination = {
+  sandboxId: string;
+  reason: "stale_attribution" | "unattributed";
+  tags: Record<string, string>;
+};
+
+export type ModalOrphanSweepResult = {
+  examined: number;
+  terminated: ModalOrphanSweepTermination[];
+  skipped: number;
+};
+
+export function modalSandboxAttributionEnvironment(input: ModalSandboxAttribution): Record<string, string> {
+  return {
+    OPENGENI_SANDBOX_LEASE_ID: input.leaseId,
+    OPENGENI_SANDBOX_GROUP_ID: input.sandboxGroupId,
+    OPENGENI_WORKSPACE_ID: input.workspaceId,
+  };
+}
+
+export function modalSandboxAttributionTags(input: ModalSandboxAttribution): Record<string, string> {
+  return {
+    opengeni: "true",
+    opengeni_lease_id: input.leaseId,
+    opengeni_workspace_id: input.workspaceId,
+    opengeni_sandbox_group_id: input.sandboxGroupId,
+  };
+}
+
 export const modalProvider: ProviderRegistration = {
   backend: "modal",
   descriptor: CAPABILITY_DESCRIPTORS.modal,
@@ -23,8 +67,13 @@ export const modalProvider: ProviderRegistration = {
     const options: NonNullable<ConstructorParameters<typeof ModalSandboxClient>[0]> = {
       appName: settings.modalAppName,
       timeoutMs: settings.modalTimeoutSeconds * 1000,
+      sandboxCreateTimeoutS: Math.ceil(settings.sandboxWarmingTimeoutMs / 1000),
       exposedPorts,
       env: environment,
+      // The Modal JS SDK's sandbox default command already sleeps until timeout
+      // or explicit termination. Do not let the Agents extension stamp a separate
+      // hardcoded sleep command; OPENGENI_MODAL_TIMEOUT_SECONDS owns lifetime.
+      useSleepCmd: false,
     };
     // gap-fill (module 03 §4.1): these SDK options were previously unmapped.
     // ALWAYS pin idleTimeoutMs (sandbox-file-persistence): an UNSET idle timeout
@@ -53,3 +102,179 @@ export const modalProvider: ProviderRegistration = {
     return new ModalSandboxClient(options);
   },
 };
+
+type ModalModule = typeof import("modal");
+type ModalClientLike = InstanceType<ModalModule["ModalClient"]>;
+
+function modalClientOptions(settings: Settings): ConstructorParameters<ModalModule["ModalClient"]>[0] {
+  return {
+    ...(settings.modalTokenId ? { tokenId: settings.modalTokenId } : {}),
+    ...(settings.modalTokenSecret ? { tokenSecret: settings.modalTokenSecret } : {}),
+    ...(settings.modalEnvironment ? { environment: settings.modalEnvironment } : {}),
+    ...(settings.modalTimeoutSeconds ? { timeoutMs: settings.modalTimeoutSeconds * 1000 } : {}),
+  };
+}
+
+async function createModalClient(settings: Settings): Promise<ModalClientLike> {
+  const modal = await import("modal");
+  return new modal.ModalClient(modalClientOptions(settings));
+}
+
+export async function tagModalSandbox(
+  settings: Settings,
+  sandboxId: string,
+  attribution: ModalSandboxAttribution,
+): Promise<boolean> {
+  if (!sandboxId) {
+    return false;
+  }
+  const modal = await createModalClient(settings);
+  try {
+    const sandbox = await modal.sandboxes.fromId(sandboxId);
+    await sandbox.setTags(modalSandboxAttributionTags(attribution));
+    return true;
+  } finally {
+    modal.close();
+  }
+}
+
+export async function terminateModalSandboxById(settings: Settings, sandboxId: string): Promise<boolean> {
+  if (!sandboxId) {
+    return true;
+  }
+  const modal = await createModalClient(settings);
+  try {
+    const sandbox = await modal.sandboxes.fromId(sandboxId);
+    await sandbox.terminate();
+    return true;
+  } finally {
+    modal.close();
+  }
+}
+
+type ModalSandboxInfo = {
+  id: string;
+  createdAt?: number;
+  tags?: Array<{ tagName?: string; tagValue?: string }>;
+};
+
+type ModalCpListClient = ModalClientLike & {
+  cpClient: {
+    sandboxList(input: {
+      appId?: string;
+      beforeTimestamp?: number;
+      environmentName?: string;
+      includeFinished?: boolean;
+      tags?: Array<{ tagName: string; tagValue: string }>;
+    }): Promise<{ sandboxes?: ModalSandboxInfo[] }>;
+  };
+};
+
+function tagsFromInfo(info: ModalSandboxInfo): Record<string, string> {
+  const tags: Record<string, string> = {};
+  for (const tag of info.tags ?? []) {
+    if (typeof tag.tagName === "string" && typeof tag.tagValue === "string") {
+      tags[tag.tagName] = tag.tagValue;
+    }
+  }
+  return tags;
+}
+
+function sandboxCreatedAtMs(info: ModalSandboxInfo): number | null {
+  if (typeof info.createdAt !== "number" || !Number.isFinite(info.createdAt) || info.createdAt <= 0) {
+    return null;
+  }
+  // Modal protobuf timestamps in this SDK are seconds as doubles.
+  return info.createdAt < 10_000_000_000 ? Math.floor(info.createdAt * 1000) : Math.floor(info.createdAt);
+}
+
+function attributionKey(input: Pick<ModalSandboxAttribution, "leaseId" | "workspaceId" | "sandboxGroupId">): string {
+  return `${input.workspaceId}:${input.sandboxGroupId}:${input.leaseId}`;
+}
+
+export async function sweepModalOrphanSandboxes(
+  settings: Settings,
+  liveLeases: LiveModalSandboxLeaseAttribution[],
+  options: {
+    now?: Date;
+    maxTerminations?: number;
+    unattributedGraceMs?: number;
+    client?: ModalClientLike;
+  } = {},
+): Promise<ModalOrphanSweepResult> {
+  const nowMs = options.now?.getTime() ?? Date.now();
+  const maxTerminations = options.maxTerminations ?? MODAL_ORPHAN_SWEEP_LIMIT;
+  const unattributedGraceMs = options.unattributedGraceMs ?? MODAL_UNATTRIBUTED_ORPHAN_GRACE_MS;
+  const liveByAttribution = new Map(liveLeases.map((lease) => [attributionKey(lease), lease]));
+  const ownedClient = options.client ? null : await createModalClient(settings);
+  const modal = (options.client ?? ownedClient)! as ModalCpListClient;
+  try {
+    const app = await modal.apps.fromName(settings.modalAppName, {
+      createIfMissing: false,
+      ...(settings.modalEnvironment ? { environment: settings.modalEnvironment } : {}),
+    });
+    const appId = app.appId;
+    if (!appId) {
+      return { examined: 0, terminated: [], skipped: 0 };
+    }
+
+    let examined = 0;
+    let skipped = 0;
+    const terminated: ModalOrphanSweepTermination[] = [];
+    let beforeTimestamp: number | undefined;
+    while (terminated.length < maxTerminations) {
+      const response = await modal.cpClient.sandboxList({
+        appId,
+        ...(beforeTimestamp !== undefined ? { beforeTimestamp } : {}),
+        includeFinished: false,
+        ...(settings.modalEnvironment ? { environmentName: settings.modalEnvironment } : {}),
+        tags: [],
+      });
+      const sandboxes = response.sandboxes ?? [];
+      if (sandboxes.length === 0) {
+        break;
+      }
+      for (const info of sandboxes) {
+        examined += 1;
+        const tags = tagsFromInfo(info);
+        const leaseId = tags.opengeni_lease_id;
+        const workspaceId = tags.opengeni_workspace_id;
+        const sandboxGroupId = tags.opengeni_sandbox_group_id;
+        let reason: ModalOrphanSweepTermination["reason"] | null = null;
+        if (leaseId && workspaceId && sandboxGroupId) {
+          const live = liveByAttribution.get(attributionKey({ leaseId, workspaceId, sandboxGroupId }));
+          if (!live || (live.instanceId && live.instanceId !== info.id)) {
+            reason = "stale_attribution";
+          }
+        } else {
+          const createdAtMs = sandboxCreatedAtMs(info);
+          if (createdAtMs !== null && nowMs - createdAtMs >= unattributedGraceMs) {
+            reason = "unattributed";
+          }
+        }
+
+        if (!reason) {
+          skipped += 1;
+          continue;
+        }
+        try {
+          const sandbox = await modal.sandboxes.fromId(info.id);
+          await sandbox.terminate();
+          terminated.push({ sandboxId: info.id, reason, tags });
+        } catch {
+          skipped += 1;
+        }
+        if (terminated.length >= maxTerminations) {
+          break;
+        }
+      }
+      beforeTimestamp = sandboxes[sandboxes.length - 1]?.createdAt;
+      if (beforeTimestamp === undefined) {
+        break;
+      }
+    }
+    return { examined, terminated, skipped };
+  } finally {
+    ownedClient?.close();
+  }
+}

package/src/sandbox/routing/routing-session.ts

@@ -74,7 +74,7 @@ export interface RoutableBackendSession {
   // `event` is kept `unknown` (mirroring the interface's structural style + avoiding
   // a proto import into the leaf); the SelfhostedSession takes `DesktopInputRequest["event"]`.
   desktopInput?(event: unknown): Promise<void>;
-  screenshot?(): Promise<{ png: Uint8Array; width: number; height: number }>;
+  screenshot?(): Promise<{ png: Uint8Array; width: number; height: number; nativeWidth: number; nativeHeight: number }>;
 }
 
 /** The resolved active backend for an epoch: the live session + the sandbox id it
@@ -189,7 +189,7 @@ export class RoutingSandboxSession implements RoutableBackendSession {
   // that cannot serve them. So the constructor assigns them ONLY when the
   // construction-time default backend actually implements the native surface (below).
   desktopInput?: (event: unknown) => Promise<void>;
-  screenshot?: () => Promise<{ png: Uint8Array; width: number; height: number }>;
+  screenshot?: () => Promise<{ png: Uint8Array; width: number; height: number; nativeWidth: number; nativeHeight: number }>;
 
   constructor(deps: RoutingSandboxSessionDeps) {
     this.deps = deps;

package/src/sandbox/selfhosted/session.ts

@@ -545,16 +545,32 @@ export 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. */
-  async screenshot(): Promise<{ png: Uint8Array; width: number; height: number }> {
+   *  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). */
+  async screenshot(): Promise<{
+    png: Uint8Array;
+    width: number;
+    height: number;
+    nativeWidth: number;
+    nativeHeight: number;
+  }> {
     const result = await this.call({ $case: "desktopScreenshot", desktopScreenshot: {} });
     if (result.$case !== "desktopScreenshot") {
       throw new Error(`selfhosted screenshot: unexpected result ${result.$case}`);
     }
+    const s = result.desktopScreenshot;
+    // Back-compat: an agent predating the native-geometry fields sends 0 → treat the
+    // encoded geometry AS the native geometry (scale factor 1.0, no coordinate shift).
     return {
-      png: result.desktopScreenshot.png,
-      width: result.desktopScreenshot.width,
-      height: result.desktopScreenshot.height,
+      png: s.png,
+      width: s.width,
+      height: s.height,
+      nativeWidth: s.nativeWidth || s.width,
+      nativeHeight: s.nativeHeight || s.height,
     };
   }