🧭 docs: Explain Code Environment Persistence

content/docs/features/code_interpreter.mdx

@@ -80,7 +80,7 @@ With [`ordinaryToolCancellation: true`](/docs/configuration/librechat_yaml/objec
 
 ### Stateful Code Sessions
 
-Stateful code sessions let a LibreChat Agent reuse one Code Interpreter sandbox workspace across executions. Files, installed packages, and working state usually carry over, making iterative analysis and multi-step file generation more efficient. Each agent selects one workspace scope:
+Stateful code sessions let a LibreChat Agent reuse retained Code Interpreter files across executions. Each execution still starts a fresh process, and the runtime may reset. Each agent selects one workspace scope:
 
 - **User workspace (recommended):** one workspace for the signed-in user across stateful-enabled agents
 - **Agent + user workspace:** one workspace for each user and agent combination
@@ -105,6 +105,22 @@ Stateful requests fail closed when the selected environment is missing, inaccess
 
 Stateful and stateless sessions do not share a live workspace. The stateful workspace may reset at any time, regardless of its selected scope. Save important outputs under `/mnt/data`, and do not otherwise rely on session state as durable storage.
 
+#### What persists between executions
+
+Approval modes control whether an operation may run; they do not change what survives after it finishes. Managed runtimes capture retained files rather than preserving an interactive shell, while attached workers preserve files in the selected registered workspace.
+
+| Backend | Files available to later calls | State that is not durable |
+| --- | --- | --- |
+| Managed, stateless | Successful outputs retained from `/mnt/data` with supported file types | The process, shell variables, current working directory, `$HOME`, `/tmp`, environment changes, global installs, and background processes |
+| Managed, stateful | Retained files under `/mnt/data`; the runtime may still reset | The process, shell variables, current working directory, `$HOME`, `/tmp`, environment changes, global installs, and background processes |
+| Attached workspace | Files written inside the selected registered workspace, including dependencies installed there | The per-call process, shell variables, current working directory, `$HOME`, `/tmp` and `$TMPDIR`, environment changes, global or system installs, and background processes |
+
+For managed execution, write a later call's inputs under `/mnt/data` and read them back explicitly. For an attached workspace, write them under the selected project and use workspace-relative paths. Pass the working directory again when a later attached command needs a subdirectory. Keep project dependencies inside the workspace, such as a repository-local virtual environment or `node_modules`.
+
+Do not hand work to a later call through an exported variable, a changed shell directory, a process left running in the background, or a file in a temporary or home directory. Software installed by the machine owner can be available to attached commands, but an Agent must treat `$HOME`, global package locations, system package locations, and machine services as operator-managed rather than mutable session storage. Long-lived services should run outside an Agent command under the machine owner's service manager.
+
+The attached worker owns filesystem, network, and process confinement. LibreChat intersects the worker's policy with deployment, user, Agent, and conversation choices; a less restrictive approval selection cannot widen the worker's policy. Workspace persistence therefore does not imply access to the rest of the host, and a permissive worker policy does not turn call-local state into durable workspace state.
+
 Files authored by stateful `create_file` and `edit_file` calls appear on the assistant message under an expandable **Workspace changes** row. It lists each unique changed path for that response and provides an authenticated download action. Downloads use LibreChat's persisted file flow when available and a secure Code Interpreter fallback otherwise. The row is a record of authored outputs, not a durable workspace snapshot; stateless outputs continue to appear as regular inline attachments.
 
 #### Attached environments and pairing