deepline 0.3.473 → 0.3.475

package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/backends/daytona-runtime-watchdog.ts

@@ -1,4 +1,9 @@
-import { STANDARD_PLAY_SANDBOX_RUNTIME_LIMITS } from '../../../plays/sandbox-runtime-limits';
+import {
+  STANDARD_PLAY_SANDBOX_RUNTIME_LIMITS,
+  MAX_PLAY_SANDBOX_RUNTIME_LIMITS,
+  validatePlaySandboxRuntimeLimits,
+  type PlaySandboxRuntimeLimits,
+} from '../../../plays/sandbox-runtime-limits';
 import { RUNTIME_SANDBOX_MEMORY_ABORT_CODE } from '../../run-failure';
 import { PLAY_RUNTIME_TRANSPORT_ATTEMPT_HEADER } from '../../runtime-contract';
 import { RUNTIME_CLAIM_HEARTBEAT_DIVISOR } from '../../runtime-constants';
@@ -11,7 +16,7 @@ import {
 /** Exit code reserved for the external runner watchdog's runtime deadline. */
 export const DAYTONA_RUNTIME_WATCHDOG_EXIT_CODE = 124;
 
-/** The cgroup memory envelope one standard sandbox is given, in MiB. */
+/** The standard profile's cgroup memory envelope, in MiB. */
 export const STANDARD_PLAY_SANDBOX_MEMORY_MIB =
   STANDARD_PLAY_SANDBOX_RUNTIME_LIMITS.memoryGiB * 1024;
 
@@ -75,6 +80,31 @@ export const PLAY_RUNNER_NODE_EXEC_ARGV: readonly string[] = [
   '--single-threaded-gc',
 ];
 
+/** Select the V8 heap envelope from the sandbox profile that will run the Play. */
+export function playRunnerNodeExecArgvForLimits(
+  limits: PlaySandboxRuntimeLimits,
+  memoryLimitMiB?: number,
+): readonly string[] {
+  const validated = validatePlaySandboxRuntimeLimits(limits);
+  const reservationMemoryMiB = validated.memoryGiB * 1024;
+  const sandboxMemoryMiB = memoryLimitMiB ?? reservationMemoryMiB;
+  if (
+    !Number.isSafeInteger(sandboxMemoryMiB) ||
+    sandboxMemoryMiB < reservationMemoryMiB ||
+    sandboxMemoryMiB > MAX_PLAY_SANDBOX_RUNTIME_LIMITS.memoryGiB * 1024
+  ) {
+    throw new Error(
+      `Invalid runner memory ceiling: ${sandboxMemoryMiB} MiB for a ${reservationMemoryMiB} MiB reservation.`,
+    );
+  }
+  return [
+    `--max-old-space-size=${Math.floor(sandboxMemoryMiB * STANDARD_PLAY_RUNNER_OLD_SPACE_SHARE)}`,
+    `--max-semi-space-size=${STANDARD_PLAY_RUNNER_MAX_SEMI_SPACE_SIZE_MIB}`,
+    '--expose-gc',
+    '--single-threaded-gc',
+  ];
+}
+
 /**
  * libuv threadpool size for the customer runner. The default is 4 and it is
  * sized for a machine, not a one-core cgroup: zlib and fs work on four threads
@@ -128,6 +158,85 @@ export const RUNNER_SANDBOX_STALL_REPORT_MS = 5_000;
 export const RUNTIME_SANDBOX_MEMORY_ABORT_REASON =
   RUNTIME_SANDBOX_MEMORY_ABORT_CODE;
 
+/** Keep anonymous memory, active cache and dirty/writeback pages in the guard. */
+export function cgroupMemoryWorkingSet(
+  usageBytes: number,
+  stat: string,
+  version: 'v1' | 'v2',
+): { workingSetBytes: number; reclaimableFileBytes: number } {
+  const values = new Map(
+    stat
+      .trim()
+      .split('\n')
+      .map((line) => {
+        const [key, value] = line.trim().split(/\s+/);
+        return [key, /^\d+$/.test(value ?? '') ? Number(value) : NaN] as const;
+      }),
+  );
+  // v1 usage includes descendants; subtract only its matching total counters.
+  const keys =
+    version === 'v2'
+      ? ['inactive_file', 'file_dirty', 'file_writeback']
+      : ['total_inactive_file', 'total_dirty', 'total_writeback'];
+  const [inactive, dirty, writeback] = keys.map((key) => values.get(key));
+  if (
+    !Number.isSafeInteger(usageBytes) ||
+    usageBytes < 0 ||
+    [inactive, dirty, writeback].some(
+      (value) =>
+        value === undefined || !Number.isSafeInteger(value) || value < 0,
+    ) ||
+    inactive! > usageBytes
+  ) {
+    return { workingSetBytes: usageBytes, reclaimableFileBytes: 0 };
+  }
+  const reclaimableFileBytes = Math.max(0, inactive! - dirty! - writeback!);
+  return {
+    workingSetBytes: usageBytes - reclaimableFileBytes,
+    reclaimableFileBytes,
+  };
+}
+
+export type SampledCgroupMemoryUsage = {
+  memoryGiBSeconds: number;
+  sampledDurationSeconds: number;
+  peakUsageBytes: number;
+  peakWorkingSetBytes: number;
+  samples: number;
+  lastSample: { monotonicAtMs: number; usageBytes: number } | null;
+};
+
+/** Fixed-size diagnostic estimate; a missing sample breaks measured coverage. */
+export function accumulateSampledCgroupMemoryUsage(
+  state: SampledCgroupMemoryUsage,
+  sample: { usageBytes: number; workingSetBytes: number } | null,
+  monotonicAtMs: number,
+  reservationMemoryBytes: number,
+): SampledCgroupMemoryUsage {
+  if (!sample) return { ...state, lastSample: null };
+  const durationSeconds = state.lastSample
+    ? Math.max(0, monotonicAtMs - state.lastSample.monotonicAtMs) / 1_000
+    : 0;
+  return {
+    memoryGiBSeconds:
+      state.memoryGiBSeconds +
+      (durationSeconds *
+        Math.max(
+          reservationMemoryBytes,
+          state.lastSample?.usageBytes ?? reservationMemoryBytes,
+        )) /
+        1024 ** 3,
+    sampledDurationSeconds: state.sampledDurationSeconds + durationSeconds,
+    peakUsageBytes: Math.max(state.peakUsageBytes, sample.usageBytes),
+    peakWorkingSetBytes: Math.max(
+      state.peakWorkingSetBytes,
+      sample.workingSetBytes,
+    ),
+    samples: state.samples + 1,
+    lastSample: { monotonicAtMs, usageBytes: sample.usageBytes },
+  };
+}
+
 /**
  * Build the parent process that owns runner liveness, the hard runtime
  * deadline, and the sandbox memory envelope outside the customer-code Node
@@ -141,14 +250,28 @@ export const RUNTIME_SANDBOX_MEMORY_ABORT_REASON =
  *   9 terminationDiagnosticPath, 10 memoryLedgerPath, 11 memoryPressurePath,
  *   12 cgroupRoot, 13 runnerPidPath.
  */
-export function buildDaytonaRuntimeWatchdogSource(): string {
+export function buildDaytonaRuntimeWatchdogSource(
+  sandboxRuntimeLimits: PlaySandboxRuntimeLimits = STANDARD_PLAY_SANDBOX_RUNTIME_LIMITS,
+  memoryLimitMiB?: number,
+): string {
+  const nodeExecArgv = playRunnerNodeExecArgvForLimits(
+    sandboxRuntimeLimits,
+    memoryLimitMiB,
+  );
   return `
 const fs = require('node:fs');
 const { spawn } = require('node:child_process');
+const cgroupMemoryWorkingSet = ${cgroupMemoryWorkingSet.toString()};
+const accumulateSampledCgroupMemoryUsage = ${accumulateSampledCgroupMemoryUsage.toString()};
+const configuredMemoryLimitBytes = ${memoryLimitMiB === undefined ? 'null' : memoryLimitMiB * 1024 * 1024};
 const runnerPath = process.argv[1];
 const configPath = process.argv[2];
 const runtimeStartedPath = process.argv[3];
 const runtimeCompletedPath = process.argv[4];
+const sampledMemoryUsagePath = configuredMemoryLimitBytes === null
+  ? ''
+  : runtimeCompletedPath + '.memory-usage.json';
+const reservationMemoryBytes = ${sandboxRuntimeLimits.memoryGiB * 1024 ** 3};
 const limitMs = Math.max(1, Number.parseInt(process.argv[5] || '', 10) || 1);
 const startupLimitMs = Math.max(1, Number.parseInt(process.argv[6] || '', 10) || 1);
 const terminalGraceMs = Math.max(1, Number.parseInt(process.argv[7] || '', 10) || 1);
@@ -161,7 +284,7 @@ const runnerPidPath = process.argv[13] || '';
 const runtimeLimitSeconds = Math.max(1, Math.ceil(limitMs / 1_000));
 const child = spawn(
   process.execPath,
-  [${PLAY_RUNNER_NODE_EXEC_ARGV.map((flag) => JSON.stringify(flag)).join(', ')}, runnerPath, configPath],
+  [${nodeExecArgv.map((flag) => JSON.stringify(flag)).join(', ')}, runnerPath, configPath],
   {
   env: {
     ...process.env,
@@ -555,6 +678,47 @@ function markRuntimeLimit() {
 let memorySource = null;
 let memoryWatchDisabledReported = false;
 let lastMemoryPressureSignalAt = 0;
+let sampledMemoryUsage = {
+  memoryGiBSeconds: 0,
+  sampledDurationSeconds: 0,
+  peakUsageBytes: 0,
+  peakWorkingSetBytes: 0,
+  samples: 0,
+  lastSample: null,
+};
+let memoryUsageWriteFailureReported = false;
+
+// This is an internal estimate, not an authoritative Modal invoice. Raw cgroup
+// usage includes cache; only the pressure guard subtracts reclaimable pages.
+// A separate parent process observes Python peaks even during spawnSync.
+function recordSampledMemoryUsage(sample) {
+  if (!sampledMemoryUsagePath) return;
+  sampledMemoryUsage = accumulateSampledCgroupMemoryUsage(
+    sampledMemoryUsage, sample, performance.now(), reservationMemoryBytes,
+  );
+  try {
+    fs.writeFileSync(sampledMemoryUsagePath + '.tmp', JSON.stringify({
+      schemaVersion: 1,
+      source: 'sampled_cgroup_estimate',
+      memoryGiBSeconds: sampledMemoryUsage.memoryGiBSeconds,
+      sampledDurationSeconds: sampledMemoryUsage.sampledDurationSeconds,
+      peakUsageBytes: sampledMemoryUsage.peakUsageBytes,
+      peakWorkingSetBytes: sampledMemoryUsage.peakWorkingSetBytes,
+      samples: sampledMemoryUsage.samples,
+      reservationMemoryMiB: reservationMemoryBytes / ${1024 ** 2},
+      observedAt: Date.now(),
+    }));
+    fs.renameSync(sampledMemoryUsagePath + '.tmp', sampledMemoryUsagePath);
+  } catch (error) {
+    if (memoryUsageWriteFailureReported) return;
+    memoryUsageWriteFailureReported = true;
+    process.stderr.write('[play-runner.memory_usage] ' + JSON.stringify({
+      event: 'sampled_memory_usage_write_failed',
+      errorName: error && typeof error.name === 'string' ? error.name : 'Error',
+      errorCode: error && typeof error.code === 'string' ? error.code : null,
+    }) + '\\n');
+  }
+}
 
 function readMemoryNumberFile(path) {
   try {
@@ -574,16 +738,22 @@ function memorySourceCandidates() {
       kind: 'cgroup_v2',
       usagePath: cgroupRoot + '/memory.current',
       limitPath: cgroupRoot + '/memory.max',
+      statPath: cgroupRoot + '/memory.stat',
+      version: 'v2',
     },
     {
       kind: 'cgroup_v1',
       usagePath: cgroupRoot + '/memory.usage_in_bytes',
       limitPath: cgroupRoot + '/memory.limit_in_bytes',
+      statPath: cgroupRoot + '/memory.stat',
+      version: 'v1',
     },
     {
       kind: 'cgroup_v1_nested',
       usagePath: cgroupRoot + '/memory/memory.usage_in_bytes',
       limitPath: cgroupRoot + '/memory/memory.limit_in_bytes',
+      statPath: cgroupRoot + '/memory/memory.stat',
+      version: 'v1',
     },
   ];
 }
@@ -593,16 +763,24 @@ function readCgroupMemory() {
   for (let index = 0; index < candidates.length; index += 1) {
     const candidate = candidates[index];
     const usageBytes = readMemoryNumberFile(candidate.usagePath);
-    const limitBytes = readMemoryNumberFile(candidate.limitPath);
-    if (usageBytes === null || limitBytes === null) continue;
+    const providerLimitBytes = readMemoryNumberFile(candidate.limitPath);
+    if (usageBytes === null || providerLimitBytes === null) continue;
+    const limitBytes = configuredMemoryLimitBytes === null
+      ? providerLimitBytes
+      : Math.min(providerLimitBytes, configuredMemoryLimitBytes);
     if (!(limitBytes > 0)) continue;
     if (limitBytes >= ${RUNNER_MEMORY_CGROUP_UNLIMITED_BYTES}) continue;
     memorySource = candidate;
+    let stat = '';
+    try { stat = fs.readFileSync(candidate.statPath, 'utf8'); } catch {}
+    const workingSet = cgroupMemoryWorkingSet(usageBytes, stat, candidate.version);
     return {
       source: candidate.kind,
       usageBytes: usageBytes,
       limitBytes: limitBytes,
       ratio: usageBytes / limitBytes,
+      ...workingSet,
+      workingSetRatio: workingSet.workingSetBytes / limitBytes,
     };
   }
   return null;
@@ -641,6 +819,8 @@ function publishMemoryPressure(sample) {
         usageBytes: sample.usageBytes,
         limitBytes: sample.limitBytes,
         ratio: sample.ratio,
+        workingSetBytes: sample.workingSetBytes,
+        reclaimableFileBytes: sample.reclaimableFileBytes,
         at: Date.now(),
       }),
     );
@@ -650,11 +830,12 @@ function publishMemoryPressure(sample) {
 const memoryWatch = setInterval(() => {
   if (settled || memoryAborted) return;
   const sample = readCgroupMemory();
+  recordSampledMemoryUsage(sample);
   if (!sample) {
     reportMemoryWatchDisabled();
     return;
   }
-  if (sample.ratio >= ${RUNNER_MEMORY_ABORT_RATIO}) {
+  if (sample.workingSetRatio >= ${RUNNER_MEMORY_ABORT_RATIO}) {
     memoryAborted = true;
     clearInterval(memoryWatch);
     process.stderr.write(
@@ -669,11 +850,13 @@ const memoryWatch = setInterval(() => {
       memoryUsageBytes: sample.usageBytes,
       memoryLimitBytes: sample.limitBytes,
       memoryUsageRatio: Math.round(sample.ratio * 10_000) / 10_000,
+      memoryWorkingSetBytes: sample.workingSetBytes,
+      memoryReclaimableFileBytes: sample.reclaimableFileBytes,
       memoryLedger: readMemoryLedger(),
     });
     return;
   }
-  if (sample.ratio >= ${RUNNER_MEMORY_PRESSURE_RATIO}) {
+  if (sample.workingSetRatio >= ${RUNNER_MEMORY_PRESSURE_RATIO}) {
     const now = Date.now();
     if (now - lastMemoryPressureSignalAt < ${RUNNER_MEMORY_PRESSURE_SIGNAL_INTERVAL_MS}) {
       return;
@@ -743,8 +926,9 @@ const startupTimer = setTimeout(() => {
 if (fs.existsSync(runtimeStartedPath)) armRuntimeDeadline();
 if (fs.existsSync(runtimeCompletedPath)) armTerminalGrace();
 
-function finish(code) {
+function finish(code, signal) {
   if (settled) return;
+  recordSampledMemoryUsage(readCgroupMemory());
   settled = true;
   clearInterval(runtimeBoundaryPoll);
   clearInterval(memoryWatch);
@@ -764,6 +948,8 @@ function finish(code) {
       ? 1
     : typeof code === 'number'
       ? code
+    : signal === 'SIGABRT'
+      ? 134
       : 1;
 }
 
@@ -779,7 +965,7 @@ child.once('exit', (code, signal) => {
     childExitCode: typeof code === 'number' ? code : null,
     childSignal: typeof signal === 'string' ? signal : null,
   });
-  finish(code);
+  finish(code, signal);
 });
 process.once('SIGTERM', () =>
   stopChild('watchdog_signal', { watchdogSignal: 'SIGTERM' }),

package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/backends/daytona.ts

@@ -40,6 +40,10 @@ import {
   PLAY_RUNNER_TERMINAL_GRACE_SECONDS,
   STANDARD_PLAY_RUNTIME_LIMIT_SECONDS,
 } from '../../runtime-constants';
+import {
+  STANDARD_PLAY_SANDBOX_RUNTIME_LIMITS,
+  validatePlaySandboxRuntimeLimits,
+} from '../../../plays/sandbox-runtime-limits';
 import {
   loadDaytonaRequiredConfig,
   loadDaytonaRunnerPathsConfig,
@@ -1842,6 +1846,20 @@ export const daytonaPlayRunnerBackend: PlayRunnerBackend = {
       ) {
         let sandboxForAttempt: DaytonaSandbox | null = null;
         let resourceAccounting: Promise<void> | null = null;
+        const trackResourceAccounting = (pending: Promise<void>) => {
+          resourceAccountingPending = true;
+          resourceAccounting = pending;
+          void pending.then(
+            () => {
+              resourceAccountingPending = false;
+            },
+            () => {
+              resourceAccountingPending = false;
+              resourceAccountingFailed = true;
+            },
+          );
+          return pending;
+        };
         // How far this sandbox's start got. The retry decision below reads it.
         let commandSent = false;
         let parkStarted = false;
@@ -1871,28 +1889,33 @@ export const daytonaPlayRunnerBackend: PlayRunnerBackend = {
             acquiredSandbox.billingStartedAt - startedAt;
           const sandbox = acquiredSandbox.sandbox;
           sandboxForAttempt = sandbox;
+          const sandboxLimits = validatePlaySandboxRuntimeLimits(
+            config.context.sandboxRuntimeLimits ?? {
+              ...STANDARD_PLAY_SANDBOX_RUNTIME_LIMITS,
+            },
+          );
           // Payload upload and session allocation do not execute customer code.
           // Overlap them with accounting, but join every resource ACK before
           // command dispatch, retry, or cancellation cleanup.
-          resourceAccountingPending = true;
-          resourceAccounting = (async () => {
-            await reportRuntimeResource(acquiredSandbox);
-            await sandboxLifecycle.settlePendingCreates();
-            for (const acquired of sandboxLifecycle.acquiredSandboxes()) {
-              await reportRuntimeResource(acquired);
-            }
-          })();
-          // Observe settlement immediately; the joins below propagate failures.
-          void resourceAccounting.then(
-            () => {
-              resourceAccountingPending = false;
-            },
-            () => {
-              resourceAccountingPending = false;
-              resourceAccountingFailed = true;
-            },
+          const resourceAccountingForAttempt = trackResourceAccounting(
+            (async () => {
+              await reportRuntimeResource(acquiredSandbox);
+              await sandboxLifecycle.settlePendingCreates();
+              for (const acquired of sandboxLifecycle.acquiredSandboxes()) {
+                await reportRuntimeResource(acquired);
+              }
+            })(),
           );
           throwIfCancellationRequested();
+          if (
+            sandbox.cpu !== sandboxLimits.cpu ||
+            sandbox.memory !== sandboxLimits.memoryGiB
+          ) {
+            await resourceAccountingForAttempt;
+            throw new Error(
+              `RUNTIME_SANDBOX_PROFILE_MISMATCH: Daytona created ${sandbox.cpu} CPU / ${sandbox.memory}GiB memory for a ${sandboxLimits.cpu} CPU / ${sandboxLimits.memoryGiB}GiB Play profile requested at create.`,
+            );
+          }
 
           const { workdir: workDir } = loadDaytonaRunnerPathsConfig();
           emitDaytonaStage(callbacks, config.context, 'workdir:resolved', {

package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/backends/local-process.ts

@@ -477,7 +477,10 @@ export const localProcessPlayRunnerBackend: PlayRunnerBackend = {
                 'node',
                 [
                   '-e',
-                  buildDaytonaRuntimeWatchdogSource(),
+                  buildDaytonaRuntimeWatchdogSource(
+                    config.context.sandboxRuntimeLimits ??
+                      STANDARD_PLAY_SANDBOX_RUNTIME_LIMITS,
+                  ),
                   runnerPath,
                   configPath,
                   runtimeStartedPath,

package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/backends/modal-resource-usage.ts

@@ -0,0 +1,222 @@
+import type { ModalClient } from 'modal';
+import { loadModalClientConfig } from '../../modal-runtime-config';
+import { MODAL_SANDBOX_COMPUTE_PRICING_USD } from '../../worker-api-types';
+
+type ResourceUsageClient = {
+  cpClient: Pick<
+    ModalClient['cpClient'],
+    'sandboxList' | 'sandboxGetResourceUsage'
+  >;
+  environmentName: ModalClient['environmentName'];
+};
+
+type ResourceUsageIdentity = {
+  source: 'provider_resource_usage';
+  sandboxId: string;
+  appId: string;
+  readStartedAt: number;
+  observedAt: number;
+  /** The provider exposes neither a finality marker nor a sample horizon. */
+  partial: true;
+};
+
+export type ModalSandboxResourceUsage = ResourceUsageIdentity &
+  (
+    | {
+        status: 'observed' | 'empty';
+        raw: {
+          cpuCoreNanosecs: number;
+          memGibNanosecs: number;
+          gpuNanosecs: number;
+          gpuType: string | null;
+        };
+        cpuCoreSeconds: number;
+        memoryGiBSeconds: number;
+        /** CPU/memory counter cost, not a bill or billing-adjusted usage. */
+        reportedResourceCostEstimateUsd: number;
+        billingAdjustment: 'unknown';
+        gpuCostIncluded: false;
+      }
+    | {
+        status: 'unavailable';
+        reason:
+          | 'deadline'
+          | 'ownership_not_observed'
+          | 'ownership_mismatch'
+          | 'invalid_provider_response'
+          | 'provider_read_failed';
+        providerErrorCode?: number;
+      }
+  );
+
+/**
+ * Preview diagnostics only. Modal's installed SDK has no high-level usage
+ * reader, so keep its typed, unsupported control-plane RPC at this edge.
+ * These counters have undocumented billing adjustment and ingestion lag;
+ * they must never become an irrevocable customer settlement fact.
+ */
+export async function readModalSandboxResourceUsage(input: {
+  sandboxId: string;
+  expectedAppId: string;
+  /** Exact selector retained by this diagnostic's sandbox creator. */
+  ownershipTags: Record<string, string>;
+  environment: 'preview';
+  /** Modal's environment name is independent of Deepline's Preview lane. */
+  modalEnvironment?: string;
+  timeoutMs?: number;
+  client?: ResourceUsageClient;
+}): Promise<ModalSandboxResourceUsage> {
+  const sandboxId = input.sandboxId.trim();
+  const appId = input.expectedAppId.trim();
+  const tags = Object.entries(input.ownershipTags);
+  const timeoutMs = input.timeoutMs ?? 10_000;
+  if (input.environment !== 'preview') {
+    throw new Error(
+      'Modal resource usage diagnostics are restricted to Preview.',
+    );
+  }
+  if (
+    !sandboxId ||
+    !appId ||
+    tags.length === 0 ||
+    tags.some(([key, value]) => !key.trim() || !value.trim())
+  ) {
+    throw new Error(
+      'Modal usage diagnostics require a sandbox id, app id, and exact non-empty creation tags.',
+    );
+  }
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+    throw new Error(
+      'Modal usage diagnostic timeout must be positive milliseconds.',
+    );
+  }
+
+  const readStartedAt = Date.now();
+  const identity = (): ResourceUsageIdentity => ({
+    source: 'provider_resource_usage',
+    sandboxId,
+    appId,
+    readStartedAt,
+    observedAt: Date.now(),
+    partial: true,
+  });
+  const unavailable = (
+    reason: Extract<
+      ModalSandboxResourceUsage,
+      { status: 'unavailable' }
+    >['reason'],
+  ): Extract<ModalSandboxResourceUsage, { status: 'unavailable' }> => ({
+    ...identity(),
+    status: 'unavailable',
+    reason,
+  });
+  const controller = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<ModalSandboxResourceUsage>((resolve) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      resolve(unavailable('deadline'));
+    }, timeoutMs);
+  });
+  const read = async (): Promise<ModalSandboxResourceUsage> => {
+    try {
+      const client = input.client ?? (await loadModalClientConfig()).client;
+      const options = {
+        signal: controller.signal,
+        timeoutMs,
+        retries: 0,
+      };
+      let beforeTimestamp = 0;
+      for (;;) {
+        controller.signal.throwIfAborted();
+        const page = await client.cpClient.sandboxList(
+          {
+            appId,
+            environmentName: client.environmentName(input.modalEnvironment),
+            includeFinished: true,
+            tags: tags.map(([tagName, tagValue]) => ({ tagName, tagValue })),
+            beforeTimestamp,
+          },
+          options,
+        );
+        controller.signal.throwIfAborted();
+        const sandbox = page.sandboxes.find((entry) => entry.id === sandboxId);
+        if (sandbox) {
+          const observedTags = new Map(
+            sandbox.tags.map((tag) => [tag.tagName, tag.tagValue]),
+          );
+          if (
+            sandbox.appId !== appId ||
+            tags.some(([key, value]) => observedTags.get(key) !== value)
+          ) {
+            return unavailable('ownership_mismatch');
+          }
+          break;
+        }
+        if (page.sandboxes.length === 0) {
+          return unavailable('ownership_not_observed');
+        }
+        const oldest = Math.min(
+          ...page.sandboxes.map((entry) => entry.createdAt),
+        );
+        if (
+          !Number.isFinite(oldest) ||
+          oldest <= 0 ||
+          (beforeTimestamp !== 0 && oldest >= beforeTimestamp)
+        ) {
+          return unavailable('invalid_provider_response');
+        }
+        beforeTimestamp = oldest;
+      }
+      const raw = await client.cpClient.sandboxGetResourceUsage(
+        { sandboxId },
+        options,
+      );
+      controller.signal.throwIfAborted();
+      const counters = [
+        raw.cpuCoreNanosecs,
+        raw.memGibNanosecs,
+        raw.gpuNanosecs,
+      ];
+      if (counters.some((value) => !Number.isSafeInteger(value) || value < 0)) {
+        return unavailable('invalid_provider_response');
+      }
+      const cpuCoreSeconds = raw.cpuCoreNanosecs / 1_000_000_000;
+      const memoryGiBSeconds = raw.memGibNanosecs / 1_000_000_000;
+      return {
+        ...identity(),
+        status: counters.every((value) => value === 0) ? 'empty' : 'observed',
+        raw: {
+          cpuCoreNanosecs: raw.cpuCoreNanosecs,
+          memGibNanosecs: raw.memGibNanosecs,
+          gpuNanosecs: raw.gpuNanosecs,
+          gpuType: raw.gpuType ?? null,
+        },
+        cpuCoreSeconds,
+        memoryGiBSeconds,
+        reportedResourceCostEstimateUsd: Number(
+          (
+            cpuCoreSeconds *
+              MODAL_SANDBOX_COMPUTE_PRICING_USD.physicalCoreSecond +
+            memoryGiBSeconds * MODAL_SANDBOX_COMPUTE_PRICING_USD.memoryGiBSecond
+          ).toFixed(12),
+        ),
+        billingAdjustment: 'unknown',
+        gpuCostIncluded: false,
+      };
+    } catch (error) {
+      const result = unavailable(
+        controller.signal.aborted ? 'deadline' : 'provider_read_failed',
+      );
+      const code = (error as { code?: unknown } | null)?.code;
+      return typeof code === 'number' && Number.isFinite(code)
+        ? { ...result, providerErrorCode: code }
+        : result;
+    }
+  };
+  try {
+    return await Promise.race([read(), deadline]);
+  } finally {
+    clearTimeout(timer);
+  }
+}