@@ -221,6 +221,11 @@ export const functionExecuteBodySchema = z
     isCustomTool: z.boolean().optional().default(false),
     /** Workspace sandbox whose dependency set this execution runs against. */
     sandboxId: z.string().optional(),
+    /**
+     * Reusable session-sandbox identity (one per Mothership chat). Honored only
+     * for trusted Mothership executions; workspace callers cannot opt in.
+     */
+    sandboxSessionKey: z.string().optional(),
     /** `all` (default) or `selected`; see mountedSecrets. */
     secretScope: z.enum(['all', 'selected']).optional(),
     /** Secret names this execution may read when secretScope is `selected`. */
 
@@ -567,6 +567,7 @@ export const env = createEnv({
     E2B_FUNCTION_TEMPLATE_ID:               z.string().refine(isImmutableE2BTemplateRef, { message: `E2B_FUNCTION_TEMPLATE_ID ${IMMUTABLE_E2B_TEMPLATE_REF_ERROR}` }).optional(), // Immutable dedicated E2B build for Function JavaScript/Python/Shell and workspace sandbox layers; no Mothership fallback
     E2B_FUNCTION_TEMPLATE_GENERATION:       z.string().refine(isValidSandboxReleaseGeneration, { message: `E2B_FUNCTION_TEMPLATE_GENERATION ${SANDBOX_RELEASE_GENERATION_ERROR}` }).optional(), // Monotonic release epoch printed by the Function E2B builder
     MOTHERSHIP_E2B_TEMPLATE_ID:             z.string().optional(),                  // Mothership code-tool template; never a Function-base fallback
+    MOTHERSHIP_SANDBOX_CLI_ENDPOINT:        z.string().optional(),                  // Sim API base the sandboxed sim CLI calls back to; defaults to NEXT_PUBLIC_APP_URL (set when the public URL is not reachable from the sandbox network)
     MOTHERSHIP_E2B_DOC_TEMPLATE_ID:         z.string().optional(),                  // Dedicated E2B template with python-pptx/docx/openpyxl/reportlab for document generation; when set (and E2B enabled), docs compile via Python instead of the JS isolated-vm path
     E2B_PI_TEMPLATE_ID:                     z.string().optional(),                  // E2B template ID/alias with the Pi CLI + git baked in (Create PR, its Babysit continuation, and Review Code)
     PI_SANDBOX_LIFETIME_MS:                 z.string().optional(),                  // Lower the Pi sandbox lifetime (ms) below the default; E2B caps a sandbox at 1h on Hobby accounts and 24h on Pro
 
@@ -306,6 +306,9 @@ function templateFor(kind: SandboxKind, imageRef?: string): string {
   return functionTemplateRef()
 }
 
+/** Metadata key that tags a sandbox with its owning session for reconnection. */
+const E2B_SESSION_METADATA_KEY = 'simSessionKey'
+
 class E2BSandboxHandle implements SandboxHandle {
   private killed = false
   private killPromise: Promise<void> | null = null
@@ -320,6 +323,10 @@ class E2BSandboxHandle implements SandboxHandle {
     return this.sandbox.sandboxId
   }
 
+  async extendLifetime(lifetimeMs: number): Promise<void> {
+    await this.sandbox.setTimeout(e2bTimeoutMs(lifetimeMs))
+  }
+
   async runCode(
     code: string,
     options: {
@@ -899,6 +906,9 @@ export const e2bProvider: SandboxProvider = {
     const createOptions = {
       apiKey,
       ...(effectiveLifetimeMs !== undefined ? { timeoutMs: effectiveLifetimeMs } : {}),
+      ...(options?.sessionKey
+        ? { metadata: { [E2B_SESSION_METADATA_KEY]: options.sessionKey } }
+        : {}),
     }
 
     const { Sandbox } = await import('@e2b/code-interpreter')
@@ -914,4 +924,31 @@ export const e2bProvider: SandboxProvider = {
         : undefined
     )
   },
+
+  async findSessionSandbox(
+    key: string,
+    options: { language?: CodeLanguage }
+  ): Promise<SandboxHandle | null> {
+    const apiKey = env.E2B_API_KEY
+    if (!apiKey) return null
+    const { Sandbox } = await import('@e2b/code-interpreter')
+    try {
+      const paginator = Sandbox.list({
+        apiKey,
+        query: { metadata: { [E2B_SESSION_METADATA_KEY]: key }, state: ['running'] },
+      })
+      const candidates = await paginator.nextItems()
+      if (candidates.length === 0) return null
+      // Oldest first: when a race created two sandboxes for one session, every
+      // later execution adopts the same one and the stragglers idle out.
+      candidates.sort((a, b) => new Date(a.startedAt).getTime() - new Date(b.startedAt).getTime())
+      const sandbox = await Sandbox.connect(candidates[0].sandboxId, { apiKey })
+      return new E2BSandboxHandle(sandbox, options.language ?? CodeLanguage.Python)
+    } catch (error) {
+      // A sandbox reaped between list and connect is an ordinary miss, and any
+      // other lookup failure degrades to a fresh create rather than an error.
+      logger.info('E2B session sandbox lookup missed', { key, error: getErrorMessage(error) })
+      return null
+    }
+  },
 }
@@ -12,6 +12,7 @@ import {
   isTimeoutAbortReason,
 } from '@/lib/core/execution-limits'
 import { recordSandboxTeardownFailure } from '@/lib/core/execution-limits/metrics'
+import { runDetached } from '@/lib/core/utils/background'
 import { buildJavaScriptRuntimeBindingsSource } from '@/lib/execution/code-placeholders/javascript-runtime'
 import { SANDBOX_SYSTEM_PATH } from '@/lib/execution/remote-sandbox/cli-tools.server'
 import {
@@ -57,6 +58,7 @@ import type {
   SandboxPrivateInput,
   SandboxProvider,
   SandboxProviderId,
+  SandboxSessionRequest,
   SandboxShellExecutionRequest,
 } from '@/lib/execution/remote-sandbox/types'
 
@@ -108,6 +110,119 @@ async function createSandbox(
   }
 }
 
+/**
+ * How long a session sandbox survives between executions before the provider
+ * reaps it. Refreshed on every acquire and release, so the clock measures idle
+ * time, not total lifetime.
+ */
+const SESSION_SANDBOX_IDLE_MS = 20 * 60_000
+
+/** Budget for a session's one-time bootstrap command (e.g. a CLI install). */
+const SESSION_BOOTSTRAP_TIMEOUT_MS = 120_000
+
+interface SandboxLease {
+  created: CreatedSandbox
+  /** Set when this execution runs in a session sandbox; absent for one-shot. */
+  session?: 'created' | 'reused'
+  /** One-shot: kills the sandbox. Session: refreshes its idle deadline. */
+  release(): Promise<void>
+}
+
+/**
+ * Acquires the sandbox an execution runs in: reconnects to the caller's live
+ * session sandbox, creates and bootstraps a fresh one under the session tag, or
+ * falls back to the classic one-shot create.
+ *
+ * A session lease never binds the abort signal to teardown — cancelling one
+ * execution must not destroy state the next turn builds on — and is never
+ * metered, because session sandboxes are server-owned rather than billed to
+ * workspace compute. Providers without session support degrade to one-shot.
+ */
+async function leaseSandbox(
+  kind: SandboxKind,
+  options: CreateSandboxOptions,
+  selected: ResolvedSandbox | null,
+  signal: AbortSignal,
+  meterUsage: boolean | undefined,
+  session: SandboxSessionRequest | undefined
+): Promise<SandboxLease> {
+  const provider = resolveProvider()
+  const sessionCapable = Boolean(session && !meterUsage && provider.findSessionSandbox)
+
+  if (session && sessionCapable) {
+    const refresh = async (sandbox: SandboxHandle) => {
+      try {
+        await sandbox.extendLifetime?.(SESSION_SANDBOX_IDLE_MS)
+      } catch (error) {
+        logger.warn('Failed to refresh session sandbox lifetime', {
+          sandboxId: sandbox.sandboxId,
+          error: getErrorMessage(error),
+        })
+      }
+    }
+    try {
+      const existing = await provider.findSessionSandbox?.(session.key, {
+        ...(options.language ? { language: options.language } : {}),
+      })
+      if (existing) {
+        await refresh(existing)
+        return {
+          created: { sandbox: existing, providerId: provider.id, startedAtMs: Date.now() },
+          session: 'reused',
+          release: () => refresh(existing),
+        }
+      }
+    } catch (error) {
+      logger.warn('Session sandbox lookup failed; creating a fresh one', {
+        key: session.key,
+        error: getErrorMessage(error),
+      })
+    }
+    const created = await createSelectedSandbox(
+      kind,
+      { ...options, lifetimeMs: SESSION_SANDBOX_IDLE_MS, sessionKey: session.key },
+      selected,
+      signal,
+      false
+    )
+    const bootstrapCommand = session.bootstrapCommand
+    if (bootstrapCommand) {
+      // Detached: the bootstrap (a CLI install, until the images bake it in)
+      // can outlast the caller's execution budget, and the first execution of a
+      // chat must not pay for it. The narrow race — the very first execution
+      // using the bootstrapped tool before the install lands — resolves on
+      // retry against the by-then bootstrapped sandbox.
+      runDetached('session-sandbox-bootstrap', async () => {
+        const bootstrap = await created.sandbox.runCommand(bootstrapCommand, {
+          timeoutMs: SESSION_BOOTSTRAP_TIMEOUT_MS,
+          rootUser: true,
+        })
+        if (bootstrap.exitCode !== 0) {
+          logger.warn('Session sandbox bootstrap exited non-zero', {
+            sandboxId: created.sandbox.sandboxId,
+            exitCode: bootstrap.exitCode,
+          })
+        }
+      })
+    }
+    return {
+      created,
+      session: 'created',
+      release: () => refresh(created.sandbox),
+    }
+  }
+
+  const created = await createSelectedSandbox(kind, options, selected, signal, meterUsage)
+  const abortBinding = bindSandboxAbort(created.sandbox, created.providerId, signal)
+  return {
+    created,
+    release: async () => {
+      abortBinding.detach()
+      await abortBinding.cleanup()
+    },
+  }
+}
+
 /**
  * Creates a sandbox, turning "that image is gone" into a rebuild rather than a
  * failure the author has to resolve by hand.
@@ -813,7 +928,7 @@ async function executeInSandboxWithinBudget(
   })
   throwIfAborted(signal)
 
-  const created = await createSelectedSandbox(
+  const lease = await leaseSandbox(
     kind,
     {
       language,
@@ -822,18 +937,20 @@ async function executeInSandboxWithinBudget(
     },
     selected,
     signal,
-    req.meterUsage
+    req.meterUsage,
+    req.session
   )
+  const created = lease.created
   const sandbox = created.sandbox
   const sandboxId = sandbox.sandboxId
-  const abortBinding = bindSandboxAbort(sandbox, created.providerId, signal)
+  const sessionField = lease.session ? { sandboxSession: lease.session } : {}
   let billableResult: SandboxExecutionResult | undefined
   let billableOutputError: unknown
 
   try {
     throwIfAborted(signal)
-    // Inside the try so a failed install or mount still kills the sandbox via the
-    // finally below. Dependencies land before the inputs so user code and its
+    // Inside the try so a failed install or mount still releases the sandbox via
+    // the finally below. Dependencies land before the inputs so user code and its
     // mounts always see a complete environment.
     //
     await provisionWithinBudget(sandbox, selected, signal)
@@ -846,10 +963,13 @@ async function executeInSandboxWithinBudget(
     )
     const executionEnvironment = {
       ...selected?.envs,
+      ...req.session?.envs,
       ...privateInputEnvironment,
     }
     const hasExecutionEnvironment =
-      selected?.envs !== undefined || Object.keys(privateInputEnvironment).length > 0
+      selected?.envs !== undefined ||
+      req.session?.envs !== undefined ||
+      Object.keys(privateInputEnvironment).length > 0
 
     let execution: SandboxCodeResult
     try {
@@ -878,6 +998,7 @@ async function executeInSandboxWithinBudget(
         stdout: execution.error.traceback || errorMessage,
         error: errorMessage,
         sandboxId,
+        ...sessionField,
       }
       if (execution.providerFailure !== 'provider_limit') billableResult = executionResult
       return executionResult
@@ -906,13 +1027,15 @@ async function executeInSandboxWithinBudget(
         stdout: cleanedStdout,
         error: SIM_RESULT_CORRUPTED_ERROR,
         sandboxId,
+        ...sessionField,
       }
     }
 
     billableResult = {
       result: extraction.result,
       stdout: cleanedStdout,
       sandboxId,
+      ...sessionField,
     }
     try {
       const { exportedFiles, exportedFileContent, collectedFiles } = await collectExportedFiles(
@@ -950,8 +1073,7 @@ async function executeInSandboxWithinBudget(
     if (cost && billableOutputError) {
       attachTrustedSandboxOutputCost(billableOutputError, cost)
     }
-    abortBinding.detach()
-    await abortBinding.cleanup()
+    await lease.release()
   }
 }
 
@@ -978,24 +1100,26 @@ async function executeShellInSandboxWithinBudget(
   })
   throwIfAborted(signal)
 
-  const created = await createSelectedSandbox(
+  const lease = await leaseSandbox(
     kind,
     { imageRef: selected?.imageRef, lifetimeMs: remainingSandboxBudgetMs(signal) },
     selected,
     signal,
-    req.meterUsage
+    req.meterUsage,
+    req.session
   )
+  const created = lease.created
   const sandbox = created.sandbox
   const sandboxId = sandbox.sandboxId
-  const abortBinding = bindSandboxAbort(sandbox, created.providerId, signal)
+  const sessionField = lease.session ? { sandboxSession: lease.session } : {}
   let billableResult: SandboxExecutionResult | undefined
   let billableOutputError: unknown
 
   try {
     throwIfAborted(signal)
-    // Inside the try so a failed install or mount still kills the sandbox via the
-    // finally below. The install shares the caller's budget rather than adding to
-    // it — see the note in `executeInSandbox`.
+    // Inside the try so a failed install or mount still releases the sandbox via
+    // the finally below. The install shares the caller's budget rather than adding
+    // to it — see the note in `executeInSandbox`.
     await provisionWithinBudget(sandbox, selected, signal)
     await writeSandboxInputs(sandbox, req.sandboxFiles, {
       rootUser: true,
@@ -1014,6 +1138,7 @@ async function executeShellInSandboxWithinBudget(
         envs: {
           ...selected?.envs,
           ...envs,
+          ...req.session?.envs,
           PATH: selected?.envs?.PATH ?? SANDBOX_SYSTEM_PATH,
           ...privateInputEnvironment,
         },
@@ -1041,7 +1166,13 @@ async function executeShellInSandboxWithinBudget(
         sandboxId,
         exitCode: result.exitCode,
       })
-      const executionResult = { result: null, stdout, error: errorMessage, sandboxId }
+      const executionResult = {
+        result: null,
+        stdout,
+        error: errorMessage,
+        sandboxId,
+        ...sessionField,
+      }
       if (result.providerFailure !== 'provider_limit') billableResult = executionResult
       return executionResult
     }
@@ -1056,6 +1187,7 @@ async function executeShellInSandboxWithinBudget(
       result: parsed,
       stdout: extraction.cleanedStdout,
       sandboxId,
+      ...sessionField,
     }
     try {
       const { exportedFiles, exportedFileContent, collectedFiles } = await collectExportedFiles(
@@ -1093,8 +1225,7 @@ async function executeShellInSandboxWithinBudget(
     if (cost && billableOutputError) {
       attachTrustedSandboxOutputCost(billableOutputError, cost)
     }
-    abortBinding.detach()
-    await abortBinding.cleanup()
+    await lease.release()
   }
 }