perf(e2b): reduce managed initialization round trips

deploy/kubernetes/BETA_CHANGELOG.md

@@ -108,3 +108,16 @@ Verify both rollout revisions and ready Service endpoints, then check public hea
 Committed hosted Environments and pending inputs notify their existing lifecycle owner. Hints preserve the lease, placement, capacity and one-shot allocation checks, with periodic recovery and one extra scan per maintenance period. The E2B helper adds bounded Create stage timings, and subprocess output collection enforces its byte limit through both copy paths. The [Sandbox Provider guide](../../docs/sandbox-provider.md#per-node-lifecycle-workers) and [E2B helper guide](../../services/core/tools/e2b-provider/README.md#observations) own the behavior and timing limitations.
 
 Validation includes database-backed ordinary/stream creation and input recovery without advancing the maintenance clock, concurrent retry and lifecycle regressions, Go race checks, Python helper tests and independent review. Production timing must be verified after rollout; these checks do not establish an end-to-end latency guarantee.
+
+## 2026-10-08 — E2B initialization round trips
+
+| Item | Value |
+| --- | --- |
+| Fork beta baseline | `89f01a50a729d2a0d024aafc193215dd9c2a31cc` |
+| Integration branch | `codex/e2b-create-roundtrips` |
+| Schema migrations / SQL / protocol changes | None |
+| Deployment requirements | Rebuild Core with its packaged E2B helper; existing Runtime template remains compatible |
+
+Create validates the managed entry point through SDK file information and a streaming open instead of starting a probe process. The initialization command returns its bounded durable receipt, removing the separate ready-file read on the successful path. Ownership and configuration checks remain mandatory; uncertain responses recover through inspection without replaying initialization. The [helper guide](../../services/core/tools/e2b-provider/README.md#create) owns these behaviors.
+
+Validation includes generated-contract checks, 11 template tests, 261 helper tests, SDK transport fixtures, real local subprocess failure/recovery checks and independent review. These checks do not establish production latency savings; compare Create stages and the full cold Session path after rollout.

services/core/tools/e2b-provider/README.md

@@ -42,9 +42,9 @@ A helper holds its allocation's lock until the SDK operation returns, even after
 
 1. Record `create_pending` with the bootstrap identity, then call `Sandbox.create` with the template, the configured timeout, the ownership metadata, `on_timeout=kill` and auto-resume disabled. A definite rejection records a settled `rejected` receipt with no sandbox IDs.
 2. Record the sandbox ID and connection material, check the sandbox domain, then read the sandbox by ID and check its ownership metadata, template and resources before writing any credential. A mismatch records a settled rejection and returns `CreateSettled` with the error.
-3. Check that `/opt/oac-e2b/managed_init.py` is readable, write the managed bootstrap input to `/root/.oac/e2b/managed-bootstrap.json` and run `managed_init.py` as root.
+3. Check that `/opt/oac-e2b/managed_init.py` has regular-file type through SDK file information, then open it through the SDK streaming file API as root and close the response without downloading its contents. This verifies readability without a remote probe process. Then write the managed bootstrap input to `/root/.oac/e2b/managed-bootstrap.json` and run `managed_init.py` as root.
 
-`managed_init.py` prepares the image as the [application-managed startup](../../deploy/e2b/README.md#startup-and-security-boundary) does, writes the [Runtime bootstrap](../../../../docs/runtime-bootstrap.md) file to `/home/runtime/runtime-bootstrap.json` (mode 0600, owned by UID 1000), sets the Environment, Session and network variables and starts `oac-daemon connect --profile default --bootstrap-file /home/runtime/runtime-bootstrap.json` as UID/GID 1000. It records process handoff in `/root/.oac/e2b/managed-ready.json` and refuses to run again once any launch record exists. `BootstrapComplete` becomes true when a later inspection reads that record with the expected identity; it does not prove enrollment or native readiness.
+`managed_init.py` prepares the image as the [application-managed startup](../../deploy/e2b/README.md#startup-and-security-boundary) does, writes the [Runtime bootstrap](../../../../docs/runtime-bootstrap.md) file to `/home/runtime/runtime-bootstrap.json` (mode 0600, owned by UID 1000), sets the Environment, Session and network variables and starts `oac-daemon connect --profile default --bootstrap-file /home/runtime/runtime-bootstrap.json` as UID/GID 1000. It records process handoff in `/root/.oac/e2b/managed-ready.json` and refuses to run again once any launch record exists. `BootstrapComplete` becomes true when Core validates that record with the expected identity. The initialization command returns the bounded durable receipt on its existing output stream, avoiding a separate file read on successful Create; Core still rereads cloud ownership and configuration before returning. If the command response is lost or its receipt is unreadable, inspection can recover the record without replaying startup; it does not prove enrollment or native readiness.
 
 An unknown Create is never repeated. A Create whose connection material was lost can be discovered and destroyed but cannot resume bootstrap, and an unconfirmed startup requires reclaiming the whole allocation.
 

services/core/tools/e2b-provider/provider.py

@@ -9,7 +9,7 @@
 from datetime import datetime, timezone
 from uuid import UUID
 
-from e2b import Sandbox, SandboxQuery, SandboxState
+from e2b import FileType, Sandbox, SandboxQuery, SandboxState
 from e2b.api.client.models.sandbox_metric import SandboxMetric
 from e2b.exceptions import AuthenticationException, FileNotFoundException, SandboxNotFoundException
 
@@ -21,6 +21,20 @@
 PREFIX = 'oac_'
 FIELDS = ('InstallationID', *REFERENCE_FIELDS)
 
+# Execute the existing protected entry point and return its durable receipt on
+# the same command stream. A read failure leaves successful startup recoverable
+# through Inspect, without replaying initialization.
+BOOTSTRAP_SCRIPT = """import runpy,sys
+runpy.run_path('/opt/oac-e2b/managed_init.py', run_name='__main__')
+try:
+    with open('/root/.oac/e2b/managed-ready.json', 'rb') as source:
+        receipt = source.read(4097)
+    if len(receipt) <= 4096:
+        sys.stdout.buffer.write(receipt)
+except OSError:
+    pass
+"""
+
 
 @contextmanager
 def create_stage(stage):
@@ -217,13 +231,17 @@ def inspect(self):
             except FileNotFoundException:
                 receipt = None
             if receipt is not None:
-                expected = record.get('bootstrap_identity')
-                if (receipt.get('identity') != expected or receipt.get('status') != 'daemon_started' or
-                        type(receipt.get('daemon_pid')) is not int or receipt['daemon_pid'] <= 0):
-                    raise Failure('ownership')
-                self.receipt.save(settled=True, bootstrap_complete=True)
+                self.accept_bootstrap_receipt(receipt)
         return cloud
 
+    def accept_bootstrap_receipt(self, receipt):
+        expected = (self.receipt.data or {}).get('bootstrap_identity')
+        if (not isinstance(receipt, dict) or receipt.get('identity') != expected or
+                receipt.get('status') != 'daemon_started' or
+                type(receipt.get('daemon_pid')) is not int or receipt['daemon_pid'] <= 0):
+            raise Failure('ownership')
+        self.receipt.save(settled=True, bootstrap_complete=True)
+
     def create(self):
         if self.receipt.data is not None:
             raise Failure('exists')
@@ -259,12 +277,20 @@ def create(self):
                 raise
         # Validate the current template entry point before writing any credential.
         with create_stage('template_check'):
-            check = run(cloud, {'Args': ['/usr/bin/python3', '-I', '-c',
-                        "import os,sys; sys.exit(78 if not os.path.isfile('/opt/oac-e2b/managed_init.py') or not os.access('/opt/oac-e2b/managed_init.py', os.R_OK) else 0)"]},
-                        self.remaining, user='root')
-            if check['ExitCode'] != 0:
+            try:
+                entry = cloud.files.get_info('/opt/oac-e2b/managed_init.py',
+                                             user='root', request_timeout=self.remaining())
+                if entry.type != FileType.FILE:
+                    self.receipt.save(status='bootstrap_failed', settled=True)
+                    raise Failure('template_invalid')
+                # A successful download can also refer to a special file. Check
+                # the type first, then verify readability without a probe process.
+                with cloud.files.read('/opt/oac-e2b/managed_init.py', format='stream',
+                                      user='root', request_timeout=self.remaining()):
+                    pass
+            except FileNotFoundException:
                 self.receipt.save(status='bootstrap_failed', settled=True)
-                raise Failure('template_invalid' if check['ExitCode'] == 78 else 'unconfirmed')
+                raise Failure('template_invalid') from None
         payload = dict(bootstrap, InstallationID=self.config['InstallationID'],
                        RuntimeBootstrap=self.q['RuntimeBootstrap'])
         del payload['CoreURL'], payload['Credential'], payload['Harness']
@@ -275,13 +301,18 @@ def create(self):
                               user='root', request_timeout=self.remaining())
         self.receipt.save(status='bootstrap_pending')
         with create_stage('bootstrap_run'):
-            result = run(cloud, {'Args': ['/usr/bin/python3', '-I', '/opt/oac-e2b/managed_init.py']},
+            result = run(cloud, {'Args': ['/usr/bin/python3', '-I', '-c', BOOTSTRAP_SCRIPT]},
                          self.remaining, user='root')
             if result['ExitCode'] != 0:
                 self.receipt.save(status='bootstrap_failed', settled=True)
                 raise Failure('unconfirmed')
         self.receipt.save(status='bootstrap_exited', settled=True)
         with create_stage('ready_inspect'):
+            try:
+                receipt = json.loads(result['Stdout'])
+            except (ValueError, KeyError):
+                raise Failure('unconfirmed') from None
+            self.accept_bootstrap_receipt(receipt)
             return self.inspect()
 
     def renew(self):