A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
Unify sandbox execution and async startup (#10821)
Trevor Manzcbb66e0bb4db
diff --git a/.github/workflows/test_cli.yaml b/.github/workflows/test_cli.yamlindex 3316e1e091..1a185e0c4f 100644--- a/.github/workflows/test_cli.yaml+++ b/.github/workflows/test_cli.yaml@@ -177,6 +177,8 @@ jobs:env:UV_FIND_LINKS: ${{ github.workspace }}run: |+ # Each run builds a different wheel under the same version and path.+ uv cache clean marimouv venvuv pip install --group=test-optional --group=dev marimo*.whluv run --no-project pytest -v tests/_cli/test_cli* -p no:xdist --maxfail=2diff --git a/docs/guides/exporting/sessions.md b/docs/guides/exporting/sessions.mdindex 1bae69c18c..46cee73aa6 100644--- a/docs/guides/exporting/sessions.md+++ b/docs/guides/exporting/sessions.md@@ -57,8 +57,19 @@ Use `--no-continue-on-error` to stop at the first failure.## Sandboxed execution-To execute in a sandboxed environment, pass `--sandbox`:+To execute in a sandboxed environment, install+[uv](https://docs.astral.sh/uv/getting-started/installation/) or+[pixi](https://pixi.prefix.dev/latest/installation/), then pass `--sandbox`:```bashmarimo export session notebook.py --sandbox```++`--sandbox` defaults to uv. Use `--sandbox uv` or `--sandbox pixi` (equivalently,+`--sandbox=uv` or `--sandbox=pixi`) to select+the backend explicitly; only the selected tool needs to be installed.+Use `--no-sandbox` to disable sandboxing and dependency prompts.++Each notebook executes in a separate process using its inline dependencies,+whether you export a single file or a directory. Up-to-date snapshots are+skipped before checking for the backend or preparing the notebook environment.diff --git a/docs/guides/package_management/inlining_dependencies.md b/docs/guides/package_management/inlining_dependencies.mdindex 8f7955680d..a68228df79 100644--- a/docs/guides/package_management/inlining_dependencies.md+++ b/docs/guides/package_management/inlining_dependencies.md@@ -30,9 +30,15 @@ When running with `--sandbox`, marimo:1. tracks the packages and versions used by your notebook, savingthem in the notebook file;-2. runs in an isolated virtual environment ("sandbox") that only+2. executes the notebook in an isolated virtual environment ("sandbox") that onlycontains the notebook dependencies.+For `edit` and `new`, the editor server starts in your current Python+environment. Each notebook gets its own sandboxed kernel when you open it,+whether you start with a single file or a folder. The editor can therefore+start before the notebook's dependencies are installed. Editor features such+as language servers use packages installed alongside the server.+marimo's sandbox provides two key benefits. (1) Notebooks that carry their owndependencies are easy to share — just send the `.py` file. (2) Isolating anotebook from other installed packages prevents obscure bugs.@@ -60,7 +66,8 @@ uv run notebook.pyIf your notebook needs conda packages, use Pixi as the sandbox backend.[Install Pixi](https://pixi.prefix.dev/latest/installation/) with support for`pixi install --script` (available in Pixi 0.80.0). marimo checks this capability-at startup; use `pixi self-update` if your installation predates it.+when preparing a notebook's environment; use `pixi self-update` if your+installation predates it.```bashmarimo edit --sandbox=pixi notebook.py@@ -91,8 +98,8 @@ notebook also runs standalone with `pixi run --script notebook.py`.[Pyodide](https://pyodide.org)'s package set, which has no condaequivalent: notebooks that rely on `[tool.pixi.dependencies]`cannot be exported to WASM.- - The `--sandbox` flag on `marimo export` commands always uses uv,- so conda dependencies are not available during export.+ - Session and thumbnail exports support `--sandbox=pixi`. Other export+ commands still use uv, so conda dependencies are not available there.!!! tip "Solving the notebook reproducibility crisis"diff --git a/docs/guides/publishing/thumbnails.md b/docs/guides/publishing/thumbnails.mdindex a3072ddb90..8fa032be31 100644--- a/docs/guides/publishing/thumbnails.md+++ b/docs/guides/publishing/thumbnails.md@@ -65,9 +65,18 @@ By default, thumbnails are generated without executing the notebook (fast; no oumarimo export thumbnail --execute --sandbox notebook.py```- !!! note "Requires uv"+ !!! note "Choose a sandbox backend"- `--sandbox` runs the notebook in an isolated environment and installs dependencies from inline script metadata (PEP 723). See [Inlining dependencies](../package_management/inlining_dependencies.md).+ `--sandbox` defaults to uv. Use `--sandbox=uv` or `--sandbox=pixi` to+ select the backend explicitly; only the selected tool needs to be+ installed. Use `--no-sandbox` to disable sandboxing and dependency prompts.++ Sandboxed execution installs dependencies from inline script metadata+ (PEP 723). See [Inlining dependencies](../package_management/inlining_dependencies.md).++ Each notebook executes in its own process using its inline dependencies.+ Playwright is installed for the renderer without adding it to notebook+ dependencies.!!! note "Sandbox only applies with execution"diff --git a/frontend/src/__mocks__/requests.ts b/frontend/src/__mocks__/requests.tsindex af55930bc3..148b19ba1c 100644--- a/frontend/src/__mocks__/requests.ts+++ b/frontend/src/__mocks__/requests.ts@@ -139,6 +139,13 @@ export const MockRequestClient = {getPackageList: vi.fn().mockResolvedValue({packages: [],}),+ getSandbox: vi+ .fn()+ .mockResolvedValue({ backend: null, manifest: null, filename: null }),+ updateManifest: vi+ .fn()+ .mockResolvedValue({ backend: null, manifest: null, filename: null }),+ syncSandbox: vi.fn().mockResolvedValue({ success: true }),getDependencyTree: vi.fn().mockResolvedValue({tree: null,context: { kind: "package-manager", name: "pip" },diff --git a/frontend/src/components/editor/alerts/connecting-alert.tsx b/frontend/src/components/editor/alerts/connecting-alert.tsxindex 9d16eaaca0..1ce5b803db 100644--- a/frontend/src/components/editor/alerts/connecting-alert.tsx+++ b/frontend/src/components/editor/alerts/connecting-alert.tsx@@ -1,76 +1,11 @@/* Copyright 2026 Marimo. All rights reserved. */import { useAtomValue } from "jotai";-import { LoadingEllipsis } from "@/components/icons/loading-ellipsis";-import { Spinner } from "@/components/icons/spinner";import { Button } from "@/components/ui/button";-import { DelayMount } from "@/components/utils/delay-mount";-import {- isClosedAtom,- isConnectingAtom,- isNotStartedAtom,-} from "@/core/network/connection";+import { isNotStartedAtom } from "@/core/network/connection";import { useConnectToRuntime } from "@/core/runtime/config";-import { Banner } from "@/plugins/impl/common/error-banner";-import { Tooltip } from "../../ui/tooltip";import { FloatingAlert } from "./floating-alert";-const SHORT_DELAY_MS = 1000; // 1 second-const LONG_DELAY_MS = 5000; // 5 seconds--export const ConnectingAlert: React.FC = () => {- const isConnecting = useAtomValue(isConnectingAtom);- const isClosed = useAtomValue(isClosedAtom);-- if (isConnecting) {- const subtleNotification = (- <Tooltip content="Connecting to a marimo runtime">- <div className="flex items-center">- <LoadingEllipsis size={5} className="text-yellow-500" />- </div>- </Tooltip>- );-- const longNotification = (- <Banner- kind="info"- className="flex flex-col rounded py-2 px-4 animate-in slide-in-from-top w-fit"- >- <div className="flex flex-col gap-4 justify-between items-start text-muted-foreground text-base">- <div className="flex items-center gap-2">- <Spinner className="h-4 w-4" />- <p>Connecting to a marimo runtime ...</p>- </div>- </div>- </Banner>- );-- // This waits for 1 second to show the subtle notification, then shows the long notification after 5 seconds.- return (- <DelayMount milliseconds={SHORT_DELAY_MS}>- <div className="m-0 flex items-center min-h-[28px] fixed top-5 left-1/2 transform -translate-x-1/2 z-200">- <DelayMount- milliseconds={LONG_DELAY_MS}- fallback={subtleNotification}- >- {longNotification}- </DelayMount>- </div>- </DelayMount>- );- }-- if (isClosed) {- return (- <FloatingAlert show={isClosed} kind="danger">- <div className="flex items-center gap-2">- <p>Failed to connect.</p>- </div>- </FloatingAlert>- );- }-};-export const NotStartedConnectionAlert: React.FC = () => {const isNotStarted = useAtomValue(isNotStartedAtom);const connectToRuntime = useConnectToRuntime();diff --git a/frontend/src/components/editor/alerts/connection-notice.tsx b/frontend/src/components/editor/alerts/connection-notice.tsxnew file mode 100644index 0000000000..32da3e1fcf--- /dev/null+++ b/frontend/src/components/editor/alerts/connection-notice.tsx@@ -0,0 +1,140 @@+/* Copyright 2026 Marimo. All rights reserved. */+import { useAtomValue } from "jotai";+import { AlertCircleIcon, ArrowRightIcon } from "lucide-react";+import { useState } from "react";+import { Spinner } from "@/components/icons/spinner";+import { Button } from "@/components/ui/button";+import { hasCellsAtom } from "@/core/cells/cells";+import type { AppConfig } from "@/core/config/config-schema";+import { connectionAtom } from "@/core/network/connection";+import { connectionNoticeAtom } from "@/core/network/connection-notice";+import { WebSocketState } from "@/core/websocket/types";+import { useDelayElapsed } from "@/hooks/useDelayElapsed";+import { useInterval } from "@/hooks/useInterval";+import { cn } from "@/utils/cn";+import { SandboxErrorOutput } from "../chrome/panels/sandbox-panel";+import { chromeAtom, useChromeActions } from "../chrome/state";+import { VerticalLayoutWrapper } from "../renderers/vertical-layout/vertical-layout-wrapper";++export const ConnectionNotice = ({+ appConfig,+ onRetry,+}: {+ appConfig: AppConfig;+ onRetry: () => void;+}) => {+ const notice = useAtomValue(connectionNoticeAtom);+ const connection = useAtomValue(connectionAtom);+ const hasCells = useAtomValue(hasCellsAtom);+ const chrome = useAtomValue(chromeAtom);+ const packagesOpen =+ (chrome.isSidebarOpen && chrome.selectedPanel === "packages") ||+ (chrome.isDeveloperPanelOpen &&+ chrome.selectedDeveloperPanelTab === "packages");+ const elapsed = useDelayElapsed(notice?.pending ? 500 : 0);+ const { openApplication } = useChromeActions();++ // Reconnection uses the footer indicator while existing cells stay visible.+ if (+ !notice ||+ !elapsed ||+ (hasCells &&+ connection.state === WebSocketState.CONNECTING &&+ connection.phase === "reconnecting")+ ) {+ return null;+ }++ return (+ <VerticalLayoutWrapper+ appConfig={appConfig}+ className="shrink-0 pb-0 sm:pb-0 print:hidden"+ innerClassName="pb-0 sm:pb-0 pr-4"+ >+ <section+ aria-label="Notebook startup"+ className={cn(+ "text-muted-foreground",+ hasCells+ ? "mt-4 mb-8 border rounded-lg px-5 py-5"+ : "max-w-sm mx-auto mt-16 sm:mt-24 px-4",+ hasCells && !notice.pending && "border-(--red-7)",+ )}+ >+ <div role="status" className="flex items-center gap-2.5">+ {notice.pending ? (+ <Spinner className="size-4 shrink-0" aria-hidden={true} />+ ) : (+ <AlertCircleIcon+ className="size-4 shrink-0 text-(--red-11)"+ aria-hidden={true}+ />+ )}+ <h2+ className={cn(+ "text-base",+ notice.pending+ ? "font-normal text-foreground"+ : "font-medium text-(--red-11)",+ )}+ >+ {notice.title}+ </h2>+ </div>+ <div className="ml-6.5">+ <p+ className={cn(+ "mt-3 text-sm leading-7",+ !notice.pending && "text-foreground",+ )}+ >+ {notice.description}+ </p>+ {!notice.sandbox && notice.error && (+ <SandboxErrorOutput error={notice.error} />+ )}+ <div className="mt-5 flex flex-wrap items-center gap-x-6 gap-y-3">+ {!packagesOpen && (notice.sandbox || notice.pending) && (+ <Button+ variant="text"+ size="xs"+ className="h-auto p-0 text-xs gap-1.5"+ onClick={() => openApplication("packages")}+ >+ {notice.pending ? "View setup details" : "Open Packages"}+ <ArrowRightIcon className="size-3" aria-hidden={true} />+ </Button>+ )}+ {!notice.pending && !notice.sandbox && (+ <Button variant="outline" size="xs" onClick={onRetry}>+ Try again+ </Button>+ )}+ {notice.pending && <StartupElapsedTime />}+ </div>+ </div>+ </section>+ </VerticalLayoutWrapper>+ );+};++function StartupElapsedTime() {+ const [startedAt] = useState(Date.now);+ const [seconds, setSeconds] = useState(0);+ useInterval(() => setSeconds(Math.floor((Date.now() - startedAt) / 1000)), {+ delayMs: 1000,+ whenVisible: true,+ });+ const duration =+ seconds < 60+ ? `${seconds}s`+ : `${Math.floor(seconds / 60)}m ${seconds % 60}s`;+ return (+ <span+ className="text-xs text-muted-foreground/70 tabular-nums"+ aria-live="off"+ >+ Elapsed {duration}+ </span>+ );+}diff --git a/frontend/src/components/editor/app-container.tsx b/frontend/src/components/editor/app-container.tsxindex 0fe0b3833d..49a5a052bd 100644--- a/frontend/src/components/editor/app-container.tsx+++ b/frontend/src/components/editor/app-container.tsx@@ -4,8 +4,11 @@ import type React from "react";import type { PropsWithChildren } from "react";import type { AppConfig } from "@/core/config/config-schema";import { PyodideLoader } from "@/core/wasm/PyodideLoader";-import { isAppClosed } from "@/core/websocket/connection-utils";-import type { ConnectionStatus } from "@/core/websocket/types";+import {+ type ConnectionStatus,+ WebSocketClosedReason,+ WebSocketState,+} from "@/core/websocket/types";import { cn } from "@/utils/cn";import { DynamicFavicon } from "./dynamic-favicon";import { StatusOverlay } from "./header/status";@@ -44,7 +47,10 @@ export const AppContainer: React.FC<PropsWithChildren<Props>> = ({data-connection-state={connectionState}className={cn("mathjax_ignore",- isAppClosed(connectionState) && "disconnected",+ connection.state === WebSocketState.CLOSED &&+ connection.code !==+ WebSocketClosedReason.KERNEL_STARTUP_ERROR &&+ "disconnected","bg-background w-full h-full text-textColor","flex flex-col overflow-y-auto",width === "full" && "config-width-full",diff --git a/frontend/src/components/editor/chrome/panels/__tests__/packages-panel.test.tsx b/frontend/src/components/editor/chrome/panels/__tests__/packages-panel.test.tsxindex c6f81cb6c9..a258d8d1b7 100644--- a/frontend/src/components/editor/chrome/panels/__tests__/packages-panel.test.tsx+++ b/frontend/src/components/editor/chrome/panels/__tests__/packages-panel.test.tsx@@ -1,6 +1,13 @@/* Copyright 2026 Marimo. All rights reserved. */-import { fireEvent, render, screen } from "@testing-library/react";+import {+ act,+ fireEvent,+ render,+ screen,+ waitFor,+ within,+} from "@testing-library/react";import { Provider } from "jotai";import { beforeEach, describe, expect, it, vi } from "vitest";import { MockRequestClient } from "@/__mocks__/requests";@@ -10,6 +17,9 @@ import type {DependencyTreeNode,DependencyTreeResponse,} from "@/core/network/types";+import { withPackageInvalidation } from "@/core/packages/package-data";+import { useInstallPackages } from "@/core/packages/useInstallPackage";+import { sandboxAtom, sandboxSyncAtom } from "@/core/packages/sandbox-state";import { store } from "@/core/state/jotai";import PackagesPanel from "../packages-panel";@@ -51,16 +61,22 @@ function renderPanel(context: DependencyTreeResponse["context"],tree: DependencyTreeNode = emptyTree,) {- const getPackageList = vi.fn().mockResolvedValue({ packages: [] });store.set(- requestClientAtom,- MockRequestClient.create({- getPackageList,- getDependencyTree: vi.fn().mockResolvedValue({ tree, context }),- }),+ sandboxAtom,+ context.kind === "sandbox"+ ? { backend: context.backend, manifest: "", filename: "notebook.py" }+ : null,);+ store.set(sandboxSyncAtom, { pending: false, error: null });+ const getPackageList = vi.fn().mockResolvedValue({ packages: [] });+ const client = MockRequestClient.create({+ getPackageList,+ getDependencyTree: vi.fn().mockResolvedValue({ tree, context }),+ });+ store.set(requestClientAtom, client);return {+ client,getPackageList,...render(<Provider store={store}>@@ -141,3 +157,94 @@ describe("PackagesPanel", () => {expect(getPackageList).toHaveBeenCalledOnce();});});++it("refreshes an open panel when a package is installed elsewhere, after installation succeeds", async () => {+ const { promise, resolve } = Promise.withResolvers<{ success: boolean }>();+ const client = MockRequestClient.create({+ addPackage: vi.fn(() => promise),+ getDependencyTree: vi+ .fn()+ .mockResolvedValueOnce({+ tree: emptyTree,+ context: { kind: "sandbox", backend: "uv" },+ })+ .mockResolvedValue({+ tree: populatedTree,+ context: { kind: "sandbox", backend: "uv" },+ }),+ });+ store.set(sandboxAtom, {+ backend: "uv",+ manifest: "",+ filename: "notebook.py",+ });+ store.set(sandboxSyncAtom, { pending: false, error: null });+ store.set(requestClientAtom, withPackageInvalidation(client));+ function InstallElsewhere() {+ const { handleInstallPackages } = useInstallPackages();+ return (+ <button onClick={() => handleInstallPackages(["polars"])}>+ Install from another panel+ </button>+ );+ }+ render(+ <Provider store={store}>+ <TooltipProvider>+ <PackagesPanel />+ <InstallElsewhere />+ </TooltipProvider>+ </Provider>,+ );+ await screen.findByPlaceholderText("Add packages to uv sandbox...");+ fireEvent.click(+ screen.getByRole("button", { name: "Install from another panel" }),+ );+ expect(client.getDependencyTree).toHaveBeenCalledTimes(1);+ await act(async () => resolve({ success: true }));+ await waitFor(() =>+ expect(client.getDependencyTree).toHaveBeenCalledTimes(2),+ );+ expect(await screen.findByText("polars")).toBeInTheDocument();+});++it.each(["uv", "pixi", "list"] as const)(+ "allows upgrading marimo but not removing it in the %s view",+ async (view) => {+ const tree = {+ ...populatedTree,+ dependencies: [+ ...populatedTree.dependencies,+ { name: "marimo", version: "0.24.0", tags: [], dependencies: [] },+ ],+ };+ const { client, getPackageList } = renderPanel(+ view === "list"+ ? { kind: "package-manager", name: "pip" }+ : { kind: "sandbox", backend: view },+ tree,+ );+ getPackageList.mockResolvedValue({ packages: tree.dependencies });+ vi.mocked(client.addPackage).mockResolvedValue({ success: true });+ if (view === "list") {+ fireEvent.click(await screen.findByRole("button", { name: "List" }));+ }+ const role = view === "list" ? "row" : "treeitem";+ const marimo = within(await screen.findByRole(role, { name: /marimo/ }));+ expect(marimo.getByText(/0\.24\.0/)).toBeInTheDocument();+ expect(+ marimo.queryByRole("button", { name: "Remove" }),+ ).not.toBeInTheDocument();+ const polars = within(screen.getByRole(role, { name: /polars/ }));+ expect(polars.getByRole("button", { name: "Remove" })).toBeInTheDocument();+ fireEvent.click(marimo.getByRole("button", { name: "Upgrade" }));+ await waitFor(() =>+ expect(client.addPackage).toHaveBeenCalledWith({+ package: "marimo",+ upgrade: true,+ group: undefined,+ }),+ );+ expect(client.removePackage).not.toHaveBeenCalled();+ },+);diff --git a/frontend/src/components/editor/chrome/panels/__tests__/sandbox-recovery.test.tsx b/frontend/src/components/editor/chrome/panels/__tests__/sandbox-recovery.test.tsxnew file mode 100644index 0000000000..1b8592bb59--- /dev/null+++ b/frontend/src/components/editor/chrome/panels/__tests__/sandbox-recovery.test.tsx@@ -0,0 +1,165 @@+/* Copyright 2026 Marimo. All rights reserved. */+// @vitest-environment jsdom+import {+ act,+ fireEvent,+ render,+ screen,+ waitFor,+ within,+} from "@testing-library/react";+import { Provider } from "jotai";+import { beforeEach, expect, it, vi } from "vitest";+import { MockRequestClient } from "@/__mocks__/requests";+import { AppConfigSchema } from "@/core/config/config-schema";+import { ConnectionNotice } from "@/components/editor/alerts/connection-notice";+import { TooltipProvider } from "@/components/ui/tooltip";+import { kernelStartupErrorAtom } from "@/core/errors/state";+import { connectionAtom } from "@/core/network/connection";+import { requestClientAtom } from "@/core/network/requests";+import {+ sandboxActionsAtom,+ sandboxAtom,+ sandboxSyncAtom,+} from "@/core/packages/sandbox-state";+import { filenameAtom } from "@/core/saving/file-state";+import { store } from "@/core/state/jotai";+import { WebSocketClosedReason, WebSocketState } from "@/core/websocket/types";+import { chromeAtom } from "../../state";+import PackagesPanel from "../packages-panel";+import { SandboxController } from "../sandbox-controller";++vi.mock("@/plugins/impl/code/LazyAnyLanguageCodeMirror", () => ({+ LazyAnyLanguageCodeMirror: ({+ value,+ onChange,+ editable,+ }: {+ value: string;+ onChange: (value: string) => void;+ editable: boolean;+ }) => (+ <textarea+ aria-label="Notebook manifest"+ value={value}+ readOnly={!editable}+ onChange={(event) => onChange(event.target.value)}+ />+ ),+}));++const manifest =+ 'dependencies = ["numpy==0.0.0"]\n\n[tool.custom]\nlabel = "experiment"\n';+const failed = {+ state: WebSocketState.CLOSED,+ code: WebSocketClosedReason.KERNEL_STARTUP_ERROR,+ phase: "preparing-environment",+ reason: "Kernel startup failed",+} as const;+beforeEach(() => {+ store.set(sandboxAtom, { backend: "uv", manifest, filename: "notebook.py" });+ store.set(sandboxSyncAtom, { pending: false, error: null });+ store.set(sandboxActionsAtom, null);+ store.set(connectionAtom, failed);+ store.set(kernelStartupErrorAtom, "resolver output\n no solution");+ store.set(filenameAtom, "notebook.py");+ store.set(chromeAtom, {+ selectedPanel: "packages",+ isSidebarOpen: false,+ isDeveloperPanelOpen: false,+ selectedDeveloperPanelTab: "errors",+ });+});+function mount(+ client: ReturnType<typeof MockRequestClient.create>,+ reconnect = vi.fn(async () => {}),+) {+ store.set(requestClientAtom, client);+ return render(+ <Provider store={store}>+ <TooltipProvider>+ <SandboxController onReconnect={reconnect} />+ <ConnectionNotice+ appConfig={AppConfigSchema.parse({})}+ onRetry={reconnect}+ />+ <PackagesPanel />+ </TooltipProvider>+ </Provider>,+ );+}+function requests() {+ return MockRequestClient.create({+ getSandbox: vi.fn(async () => ({+ backend: "uv",+ manifest,+ filename: "notebook.py",+ })),+ updateManifest: vi.fn(async ({ contents }) => ({+ backend: "uv",+ manifest: contents,+ filename: "notebook.py",+ })),+ syncSandbox: vi.fn(async () => ({ success: true, reconnect: true })),+ });+}++it("keeps a whole-manifest repair open through failure and closes only after sync succeeds", async () => {+ const client = requests();+ const { promise: saved, resolve: finishSave } = Promise.withResolvers<void>();+ vi.mocked(client.updateManifest).mockImplementation(async ({ contents }) => {+ await saved;+ return { backend: "uv", manifest: contents, filename: "notebook.py" };+ });+ const reconnect = vi.fn(async () => {+ store.set(kernelStartupErrorAtom, null);+ store.set(connectionAtom, {+ state: WebSocketState.CONNECTING,+ phase: "preparing-environment",+ });+ });+ mount(client, reconnect);+ fireEvent.click(await screen.findByRole("button", { name: "Open Packages" }));+ expect(store.get(chromeAtom).isSidebarOpen).toBe(true);+ expect(screen.getByLabelText("Error details")).toHaveTextContent(+ "resolver output",+ );+ fireEvent.click(screen.getByRole("button", { name: "Edit manifest…" }));+ const editor = await screen.findByRole("textbox", {+ name: "Notebook manifest",+ });+ const replacement =+ '# A completely different manifest\n[tool.custom]\nlabel = "updated"\n';+ fireEvent.change(editor, { target: { value: replacement } });+ fireEvent.click(screen.getByRole("button", { name: "Save & sync" }));+ expect(screen.getByRole("dialog")).toBeInTheDocument();+ expect(reconnect).not.toHaveBeenCalled();+ await act(async () => finishSave());+ await waitFor(() => expect(reconnect).toHaveBeenCalledTimes(1));+ expect(client.updateManifest).toHaveBeenCalledWith({+ fileKey: "notebook.py",+ previous: manifest,+ contents: replacement,+ });+ expect(screen.getByRole("dialog")).toBeInTheDocument();+ act(() => {+ store.set(connectionAtom, failed);+ store.set(kernelStartupErrorAtom, "another resolver failure");+ });+ const dialog = within(screen.getByRole("dialog"));+ expect(await dialog.findByLabelText("Error details")).toHaveTextContent(+ "another resolver failure",+ );+ expect(+ dialog.getByRole("textbox", { name: "Notebook manifest" }),+ ).toHaveValue(replacement);+ await waitFor(() =>+ expect(dialog.getByRole("button", { name: "Sync" })).toBeEnabled(),+ );+ fireEvent.click(dialog.getByRole("button", { name: "Sync" }));+ await waitFor(() => expect(reconnect).toHaveBeenCalledTimes(2));+ act(() => store.set(connectionAtom, { state: WebSocketState.OPEN }));+ await waitFor(() =>+ expect(screen.queryByRole("dialog")).not.toBeInTheDocument(),+ );+});diff --git a/frontend/src/components/editor/chrome/panels/packages-panel.tsx b/frontend/src/components/editor/chrome/panels/packages-panel.tsxindex 9f3b03e9ff..15a1b14e0b 100644--- a/frontend/src/components/editor/chrome/panels/packages-panel.tsx+++ b/frontend/src/components/editor/chrome/panels/packages-panel.tsx@@ -7,6 +7,7 @@ import {HelpCircleIcon,} from "lucide-react";import React from "react";+import { connectionNoticeAtom } from "@/core/network/connection-notice";import { useOpenSettingsToTab } from "@/components/app-config/state";import { Spinner } from "@/components/icons/spinner";import { SearchInput } from "@/components/ui/input";@@ -20,25 +21,22 @@ import {} from "@/components/ui/table";import { Tooltip } from "@/components/ui/tooltip";import { toast } from "@/components/ui/use-toast";-import { useResolvedMarimoConfig } from "@/core/config/config";-import { useRequestClient } from "@/core/network/requests";+import { isConnectedAtom } from "@/core/network/connection";import type {DependencyTreeNode,DependencyTreeResponse,} from "@/core/network/types";+import { sandboxAtom, sandboxSyncAtom } from "@/core/packages/sandbox-state";import { stripPackageManagerPrefix } from "@/core/packages/package-input-utils";-import {- showPackageRestartToast,- showRemovePackageToast,- showUpgradePackageToast,-} from "@/core/packages/toast-components";+import { usePackageAction } from "@/core/packages/usePackageAction";+import { usePackageDependencies } from "@/core/packages/usePackageDependencies";import { useInstallPackages } from "@/core/packages/useInstallPackage";import { isWasm } from "@/core/wasm/utils";-import { useAsyncData } from "@/hooks/useAsyncData";import { ErrorBanner } from "@/plugins/impl/common/error-banner";import { cn } from "@/utils/cn";import { copyToClipboard } from "@/utils/copy";import { Events } from "@/utils/events";+import { SandboxFooter, SandboxStartupPanel } from "./sandbox-panel";import { PanelEmptyState } from "./empty-state";import { PACKAGES_INPUT_ID, packagesToInstallAtom } from "./packages-utils";@@ -71,36 +69,44 @@ const PackageActionButton: React.FC<{};const PackagesPanel: React.FC = () => {- const [config] = useResolvedMarimoConfig();- const packageManager = config.package_management.manager;- const { getDependencyTree, getPackageList } = useRequestClient();+ const sandbox = useAtomValue(sandboxAtom);+ const connected = useAtomValue(isConnectedAtom);+ const notice = useAtomValue(connectionNoticeAtom);+ const operation = useAtomValue(sandboxSyncAtom);+ if (sandbox?.backend) {+ return (+ <div className="flex flex-col flex-1 min-h-0 overflow-hidden">+ {notice && (!operation.pending || !connected) ? (+ <SandboxStartupPanel />+ ) : (+ <PackageContents />+ )}+ <SandboxFooter />+ </div>+ );+ }+ if (notice) {+ return (+ <div className="p-4 text-sm text-muted-foreground">+ <div className="flex items-center gap-2">+ {notice.pending && <Spinner className="size-3" />}+ {notice.title}+ </div>+ {notice.error && (+ <pre className="mt-3 text-xs whitespace-pre-wrap break-words max-h-52 overflow-auto">+ {notice.error}+ </pre>+ )}+ </div>+ );+ }+ return <PackageContents />;+};+const PackageContents: React.FC = () => {+ const { pending: syncing } = useAtomValue(sandboxSyncAtom);const [userViewMode, setUserViewMode] = React.useState<ViewMode | null>(null);- const {- data: dependencies,- error,- refetch,- isPending,- } = useAsyncData(async () => {- // A sandbox's list and tree both inspect the same environment. Wait for- // the context before issuing the list request so sandboxes do that work- // only once; non-sandbox managers still need both views.- const dependencyTreeResponse = await getDependencyTree();- if (dependencyTreeResponse.context.kind === "sandbox") {- return {- list: [],- context: dependencyTreeResponse.context,- tree: dependencyTreeResponse.tree,- };- }-- const listPackagesResponse = await getPackageList();- return {- list: listPackagesResponse.packages,- context: dependencyTreeResponse.context,- tree: dependencyTreeResponse.tree,- };- }, [packageManager]);+ const { data: dependencies, error, isPending } = usePackageDependencies();// Only show on the first loadif (isPending) {@@ -122,58 +128,49 @@ const PackagesPanel: React.FC = () => {const viewMode = isSandbox? "tree": resolveViewMode(userViewMode, isTreeSupported);- const scopeLabel = sandboxBackend- ? `${sandboxBackend} sandbox`- : name && name !== "<root>"- ? "project"- : "environment";- const scopeTitle = sandboxBackend- ? `Dependencies are managed by the ${sandboxBackend} sandbox selected when marimo started.`- : scopeLabel;+ const scopeLabel = name && name !== "<root>" ? "project" : "environment";return (<div className="flex-1 flex flex-col overflow-hidden">- <InstallPackageForm context={dependencies.context} onSuccess={refetch} />- {(isTreeSupported || isSandbox) && (+ <fieldset disabled={syncing} className="contents">+ <InstallPackageForm context={dependencies.context} />+ </fieldset>+ {isTreeSupported && !isSandbox && (<div className="flex items-center justify-between px-2 py-1 border-b">- {isTreeSupported && !isSandbox ? (- <div className="flex gap-1">- <button- type="button"- className={cn(- "px-2 py-1 text-xs rounded",- viewMode === "list"- ? "bg-accent text-accent-foreground"- : "text-muted-foreground hover:text-foreground",- )}- onClick={() => setUserViewMode("list")}- >- List- </button>- <button- type="button"- className={cn(- "px-2 py-1 text-xs rounded",- viewMode === "tree"- ? "bg-accent text-accent-foreground"- : "text-muted-foreground hover:text-foreground",- )}- onClick={() => setUserViewMode("tree")}- >- Tree- </button>- </div>- ) : (- <div />- )}+ <div className="flex gap-1">+ <button+ type="button"+ className={cn(+ "px-2 py-1 text-xs rounded",+ viewMode === "list"+ ? "bg-accent text-accent-foreground"+ : "text-muted-foreground hover:text-foreground",+ )}+ onClick={() => setUserViewMode("list")}+ >+ List+ </button>+ <button+ type="button"+ className={cn(+ "px-2 py-1 text-xs rounded",+ viewMode === "tree"+ ? "bg-accent text-accent-foreground"+ : "text-muted-foreground hover:text-foreground",+ )}+ onClick={() => setUserViewMode("tree")}+ >+ Tree+ </button>+ </div><div className="flex items-center gap-2"><divclassName="items-center border px-2 py-0.5 text-xs transition-colors focus:outline-hidden focus:ring-2 focus:ring-ring focus:ring-offset-2 text-foreground rounded-sm text-ellipsis block overflow-hidden max-w-fit font-medium"- title={scopeTitle}+ title={scopeLabel}>{scopeLabel}</div>- {name && !isSandbox && (+ {name && (<span className="text-xs text-muted-foreground">{name}{version && ` v${version}`}@@ -183,13 +180,12 @@ const PackagesPanel: React.FC = () => {</div>)}{viewMode === "list" ? (- <PackagesList packages={dependencies.list} onSuccess={refetch} />+ <PackagesList packages={dependencies.list} />) : (<DependencyTreetree={dependencies.tree}error={error}sandboxBackend={sandboxBackend}- onSuccess={refetch}/>)}</div>@@ -200,8 +196,7 @@ export default PackagesPanel;const InstallPackageForm: React.FC<{context: PackageInstallationContext;- onSuccess: () => void;-}> = ({ onSuccess, context }) => {+}> = ({ context }) => {const [input, setInput] = React.useState("");const { handleClick: openSettings } = useOpenSettingsToTab();const isSandbox = context.kind === "sandbox";@@ -222,7 +217,6 @@ const InstallPackageForm: React.FC<{const { loading, handleInstallPackages } = useInstallPackages();const onSuccessInstallPackages = () => {- onSuccess();setInput("");};@@ -363,9 +357,8 @@ const InstallPackageForm: React.FC<{};const PackagesList: React.FC<{- onSuccess: () => void;packages: { name: string; version: string }[];-}> = ({ onSuccess, packages }) => {+}> = ({ packages }) => {// Sort case-insensitively so packages are strictly alphabetical// regardless of capitalization (package managers sort inconsistently).const sortedPackages = React.useMemo(@@ -410,8 +403,8 @@ const PackagesList: React.FC<{<TableCell>{item.name}</TableCell><TableCell>{item.version}</TableCell><TableCell className="flex justify-end">- <UpgradeButton packageName={item.name} onSuccess={onSuccess} />- <RemoveButton packageName={item.name} onSuccess={onSuccess} />+ <UpgradeButton packageName={item.name} />+ <RemoveButton packageName={item.name} /></TableCell></TableRow>))}@@ -423,40 +416,14 @@ const PackagesList: React.FC<{const UpgradeButton: React.FC<{packageName: string;tags?: { kind: string; value: string }[];- onSuccess: () => void;-}> = ({ packageName, tags, onSuccess }) => {- const [loading, setLoading] = React.useState(false);- const { addPackage } = useRequestClient();-- // Hide upgrade button in WASM+}> = ({ packageName, tags }) => {+ const { loading, run } = usePackageAction("upgrade", packageName, tags);if (isWasm()) {return null;}- const handleUpgradePackage = async () => {- try {- setLoading(true);- const group = tags?.find((tag) => tag.kind === "group")?.value;- const response = await addPackage({- package: packageName,- upgrade: true,- group,- });- if (response.restartRequired) {- showPackageRestartToast();- } else if (response.success) {- onSuccess();- showUpgradePackageToast(packageName);- } else {- showUpgradePackageToast(packageName, response.error);- }- } finally {- setLoading(false);- }- };-return (- <PackageActionButton onClick={handleUpgradePackage} loading={loading}>+ <PackageActionButton onClick={run} loading={loading}>Upgrade</PackageActionButton>);@@ -465,34 +432,14 @@ const UpgradeButton: React.FC<{const RemoveButton: React.FC<{packageName: string;tags?: { kind: string; value: string }[];- onSuccess: () => void;-}> = ({ packageName, tags, onSuccess }) => {- const [loading, setLoading] = React.useState(false);- const { removePackage } = useRequestClient();-- const handleRemovePackage = async () => {- try {- setLoading(true);- const group = tags?.find((tag) => tag.kind === "group")?.value;- const response = await removePackage({- package: packageName,- group,- });- if (response.restartRequired) {- showPackageRestartToast();- } else if (response.success) {- onSuccess();- showRemovePackageToast(packageName);- } else {- showRemovePackageToast(packageName, response.error);- }- } finally {- setLoading(false);- }- };+}> = ({ packageName, tags }) => {+ const { loading, run } = usePackageAction("remove", packageName, tags);+ if (packageName.toLowerCase() === "marimo") {+ return null;+ }return (- <PackageActionButton onClick={handleRemovePackage} loading={loading}>+ <PackageActionButton onClick={run} loading={loading}>Remove</PackageActionButton>);@@ -502,8 +449,7 @@ const DependencyTree: React.FC<{tree: DependencyTreeNode | null;error?: Error | null;sandboxBackend: "uv" | "pixi" | null;- onSuccess: () => void;-}> = ({ tree, error, sandboxBackend, onSuccess }) => {+}> = ({ tree, error, sandboxBackend }) => {const [expandedNodes, setExpandedNodes] = React.useState<Set<string>>(new Set(),);@@ -570,7 +516,6 @@ const DependencyTree: React.FC<{isTopLevel={true}expandedNodes={expandedNodes}onToggle={toggleNode}- onSuccess={onSuccess}/></div>))}@@ -586,16 +531,7 @@ const DependencyTreeNode: React.FC<{isTopLevel?: boolean;expandedNodes: Set<string>;onToggle: (nodeId: string) => void;- onSuccess: () => void;-}> = ({- nodeId,- node,- level,- isTopLevel = false,- expandedNodes,- onToggle,- onSuccess,-}) => {+}> = ({ nodeId, node, level, isTopLevel = false, expandedNodes, onToggle }) => {const hasChildren = node.dependencies.length > 0;const isExpanded = expandedNodes.has(nodeId);const indent = isTopLevel ? 0 : 16 + level * 16; // Top-level uses CSS padding, children use calculated indent@@ -709,17 +645,9 @@ const DependencyTreeNode: React.FC<{{/* Actions for top-level packages */}{isTopLevel && (<div className="flex gap-1 invisible group-hover:visible">- <UpgradeButton- packageName={node.name}- tags={node.tags}- onSuccess={onSuccess}- />+ <UpgradeButton packageName={node.name} tags={node.tags} />- <RemoveButton- packageName={node.name}- tags={node.tags}- onSuccess={onSuccess}- />+ <RemoveButton packageName={node.name} tags={node.tags} /></div>)}</div>@@ -736,7 +664,6 @@ const DependencyTreeNode: React.FC<{isTopLevel={false}expandedNodes={expandedNodes}onToggle={onToggle}- onSuccess={onSuccess}/>))}</div>diff --git a/frontend/src/components/editor/chrome/panels/sandbox-controller.tsx b/frontend/src/components/editor/chrome/panels/sandbox-controller.tsxnew file mode 100644index 0000000000..632ad232ae--- /dev/null+++ b/frontend/src/components/editor/chrome/panels/sandbox-controller.tsx@@ -0,0 +1,106 @@+/* Copyright 2026 Marimo. All rights reserved. */+import { Suspense } from "react";+import { Spinner } from "@/components/icons/spinner";+import { Button } from "@/components/ui/button";+import {+ Dialog,+ DialogContent,+ DialogDescription,+ DialogFooter,+ DialogHeader,+ DialogTitle,+} from "@/components/ui/dialog";+import { useSandboxController } from "@/core/packages/useSandboxController";+import { LazyAnyLanguageCodeMirror } from "@/plugins/impl/code/LazyAnyLanguageCodeMirror";+import { useTheme } from "@/theme/useTheme";+import { Paths } from "@/utils/paths";+import { SandboxErrorOutput } from "./sandbox-panel";++export function SandboxController({+ onReconnect,+}: {+ onReconnect: () => Promise<void>;+}) {+ const {+ filename,+ open,+ setOpen,+ draft,+ setDraft,+ dirty,+ loading,+ saving,+ pending,+ error,+ diagnostic,+ conflict,+ loadManifest,+ saveAndSync,+ } = useSandboxController(onReconnect);+ const { theme } = useTheme();+ return (+ <Dialog open={open} onOpenChange={setOpen}>+ <DialogContent className="sm:max-w-xl grid-cols-1 max-h-[80vh] overflow-auto">+ <DialogHeader>+ <DialogTitle>Edit manifest</DialogTitle>+ <DialogDescription className="font-mono text-xs">+ {Paths.basename(filename ?? "Untitled notebook")} · script metadata+ </DialogDescription>+ </DialogHeader>+ {draft !== null && !loading ? (+ <Suspense fallback={<Spinner />}>+ <LazyAnyLanguageCodeMirror+ language="toml"+ theme={theme}+ value={draft}+ onChange={setDraft}+ editable={!pending}+ height="260px"+ basicSetup={{ lineNumbers: false, foldGutter: false }}+ className="border rounded overflow-hidden"+ aria-label="Notebook manifest"+ />+ </Suspense>+ ) : (+ !error && <Spinner />+ )}+ {diagnostic && <SandboxErrorOutput error={diagnostic} />}+ {conflict && (+ <Button variant="text" size="sm" onClick={loadManifest}>+ Discard draft and reload manifest+ </Button>+ )}+ <DialogFooter className="items-center sm:justify-between gap-3">+ <span className="text-xs text-muted-foreground mr-auto">+ {loading+ ? "Loading…"+ : dirty+ ? "Unsaved changes"+ : draft !== null+ ? "Saved"+ : ""}+ </span>+ <Button variant="text" size="sm" onClick={() => setOpen(false)}>+ Close+ </Button>+ <Button+ size="sm"+ disabled={draft === null || pending}+ onClick={saveAndSync}+ >+ {pending && <Spinner className="size-3 mr-2" />}+ {loading+ ? "Loading…"+ : saving+ ? "Saving…"+ : pending+ ? "Syncing…"+ : dirty+ ? "Save & sync"+ : "Sync"}+ </Button>+ </DialogFooter>+ </DialogContent>+ </Dialog>+ );+}diff --git a/frontend/src/components/editor/chrome/panels/sandbox-panel.tsx b/frontend/src/components/editor/chrome/panels/sandbox-panel.tsxnew file mode 100644index 0000000000..07e14f5e2c--- /dev/null+++ b/frontend/src/components/editor/chrome/panels/sandbox-panel.tsx@@ -0,0 +1,173 @@+/* Copyright 2026 Marimo. All rights reserved. */+import { useAtomValue } from "jotai";+import {+ AlertCircleIcon,+ ChevronUpIcon,+ FileCodeIcon,+ RefreshCwIcon,+} from "lucide-react";+import { connectionNoticeAtom } from "@/core/network/connection-notice";+import { Spinner } from "@/components/icons/spinner";+import { Button } from "@/components/ui/button";+import {+ DropdownMenu,+ DropdownMenuContent,+ DropdownMenuItem,+ DropdownMenuTrigger,+} from "@/components/ui/dropdown-menu";+import { Tooltip } from "@/components/ui/tooltip";+import { isConnectedAtom } from "@/core/network/connection";+import {+ sandboxActionsAtom,+ sandboxAtom,+ sandboxSyncAtom,+} from "@/core/packages/sandbox-state";+import { cn } from "@/utils/cn";++export function SandboxErrorOutput({ error }: { error: string }) {+ return (+ <pre+ tabIndex={0}+ aria-label="Error details"+ className="mt-3 p-3 rounded border bg-muted/30 text-xs text-muted-foreground whitespace-pre min-w-0 max-w-full max-h-52 overflow-auto"+ >+ {error}+ </pre>+ );+}++export function SandboxStartupPanel() {+ const notice = useAtomValue(connectionNoticeAtom);+ const sandbox = useAtomValue(sandboxAtom);+ const actions = useAtomValue(sandboxActionsAtom);+ if (!notice) {+ return null;+ }+ return (+ <div className="flex-1 min-h-0 overflow-auto p-4 text-sm">+ <div+ className={cn(+ "flex items-center gap-2",+ notice.pending+ ? "text-muted-foreground"+ : "font-medium text-(--red-11)",+ )}+ >+ {notice.pending ? (+ <Spinner className="size-4 shrink-0" aria-hidden={true} />+ ) : (+ <AlertCircleIcon className="size-4 shrink-0" aria-hidden={true} />+ )}+ <h2>{notice.title}</h2>+ </div>+ {!notice.pending && (+ <>+ <p className="mt-2 text-foreground">{notice.description}</p>+ {notice.error && <SandboxErrorOutput error={notice.error} />}+ <div className="flex items-center gap-2 mt-3">+ <Button+ variant="outline"+ size="xs"+ disabled={!actions || sandbox?.manifest == null}+ onClick={() => actions?.editManifest()}+ >+ Edit manifest…+ </Button>+ <Button+ variant="text"+ size="xs"+ disabled={!actions}+ onClick={() => actions?.sync()}+ >+ Retry sync+ </Button>+ </div>+ {sandbox?.manifest == null && (+ <p className="mt-3 text-xs text-muted-foreground">+ A manifest will be available once this new notebook starts.+ </p>+ )}+ </>+ )}+ </div>+ );+}++export function SandboxFooter() {+ const sandbox = useAtomValue(sandboxAtom);+ const connected = useAtomValue(isConnectedAtom);+ const actions = useAtomValue(sandboxActionsAtom);+ const operation = useAtomValue(sandboxSyncAtom);+ const notice = useAtomValue(connectionNoticeAtom);+ if (!sandbox?.backend) {+ return null;+ }+ const pending = operation.pending || notice?.pending;+ const status = operation.pending+ ? "Syncing sandbox…"+ : (notice?.title ?? (connected ? "Sandbox ready" : "Sandbox not started"));+ return (+ <div className="border-t p-1.5 shrink-0">+ <DropdownMenu>+ <Tooltip content={status}>+ <DropdownMenuTrigger asChild={true}>+ <button+ type="button"+ className="flex items-center gap-2 w-full px-2 py-1.5 rounded text-xs text-muted-foreground hover:bg-accent data-[state=open]:bg-accent"+ aria-label={`${sandbox.backend} sandbox actions`}+ >+ <span+ role="status"+ aria-label={status}+ className={cn(+ "size-1.5 shrink-0 rounded-full",+ pending+ ? "bg-amber-500 motion-safe:animate-pulse"+ : notice+ ? "bg-(--red-9)"+ : connected+ ? "bg-emerald-500"+ : "bg-muted-foreground",+ )}+ />+ <span>{sandbox.backend} sandbox</span>+ <span className="ml-auto">+ {pending+ ? operation.pending+ ? "Syncing…"+ : notice?.title+ : ""}+ </span>+ <ChevronUpIcon className="size-3" />+ </button>+ </DropdownMenuTrigger>+ </Tooltip>+ <DropdownMenuContent+ side="top"+ align="start"+ className="w-52"+ sideOffset={8}+ >+ <DropdownMenuItem+ disabled={pending || !actions}+ onSelect={() => {+ void actions?.sync();+ }}+ >+ <RefreshCwIcon className="size-3.5 mr-2" />+ Sync+ </DropdownMenuItem>+ <DropdownMenuItem+ disabled={!actions || sandbox.manifest === null}+ onSelect={() => {+ void actions?.editManifest();+ }}+ >+ <FileCodeIcon className="size-3.5 mr-2" />+ Edit manifest…+ </DropdownMenuItem>+ </DropdownMenuContent>+ </DropdownMenu>+ </div>+ );+}diff --git a/frontend/src/components/editor/chrome/wrapper/footer-items/backend-status.tsx b/frontend/src/components/editor/chrome/wrapper/footer-items/backend-status.tsxindex d2f79264f8..ff0b17fafa 100644--- a/frontend/src/components/editor/chrome/wrapper/footer-items/backend-status.tsx+++ b/frontend/src/components/editor/chrome/wrapper/footer-items/backend-status.tsx@@ -42,7 +42,9 @@ export const BackendConnectionStatus: React.FC = () => {const { isFetching, error, data, refetch } = useAsyncData(async () => {// If the connection is not connected, returnif (!isAppConnected(connection)) {- setConnectionStatus("disconnected");+ setConnectionStatus(+ isAppConnecting(connection) ? "connecting" : "disconnected",+ );return;}diff --git a/frontend/src/components/editor/header/__tests__/status.test.tsx b/frontend/src/components/editor/header/__tests__/status.test.tsxindex 84d90c9709..ad8acd215b 100644--- a/frontend/src/components/editor/header/__tests__/status.test.tsx+++ b/frontend/src/components/editor/header/__tests__/status.test.tsx@@ -66,24 +66,12 @@ describe("StatusOverlay disconnect indicator", () => {expect((button as HTMLButtonElement).disabled).toBe(true);});- it.each([- [- WebSocketClosedReason.KERNEL_STARTUP_ERROR,- "Failed to start kernel sandbox",- ],- ])(- "renders a disabled button for non-recoverable close reason %s",- (code, reason) => {- const onReconnect = vi.fn();- const { getByTestId } = renderOverlay(- { state: WebSocketState.CLOSED, code, reason },- onReconnect,- );-- const button = getByTestId("disconnected-indicator") as HTMLButtonElement;- expect(button.disabled).toBe(true);- fireEvent.click(button);- expect(onReconnect).not.toHaveBeenCalled();- },- );+ it("leaves editor startup failures to the inline notice", () => {+ const { queryByTestId } = renderOverlay({+ state: WebSocketState.CLOSED,+ code: WebSocketClosedReason.KERNEL_STARTUP_ERROR,+ reason: "Failed to start kernel sandbox",+ });+ expect(queryByTestId("disconnected-indicator")).not.toBeInTheDocument();+ });});diff --git a/frontend/src/components/editor/header/status.tsx b/frontend/src/components/editor/header/status.tsxindex 56e1cbe62e..1471bd01c2 100644--- a/frontend/src/components/editor/header/status.tsx+++ b/frontend/src/components/editor/header/status.tsx@@ -20,10 +20,12 @@ export const StatusOverlay: React.FC<{onReconnect?: () => void;}> = ({ connection, isRunning, onReconnect }) => {const { mode } = useAtomValue(viewStateAtom);- const isClosed = connection.state === WebSocketState.CLOSED;+ const isClosed =+ connection.state === WebSocketState.CLOSED &&+ (mode === "read" ||+ connection.code !== WebSocketClosedReason.KERNEL_STARTUP_ERROR);const isOpen = connection.state === WebSocketState.OPEN;- // Only KERNEL_DISCONNECTED is recoverable by a retry. KERNEL_STARTUP_ERROR- // would deterministically fail the same way.+ // Editor startup failures have their own recovery UI.const canReconnect =isClosed && connection.code === WebSocketClosedReason.KERNEL_DISCONNECTED;diff --git a/frontend/src/components/editor/renderers/cell-array.tsx b/frontend/src/components/editor/renderers/cell-array.tsxindex 843deda29d..1badb7cb4b 100644--- a/frontend/src/components/editor/renderers/cell-array.tsx+++ b/frontend/src/components/editor/renderers/cell-array.tsx@@ -43,10 +43,7 @@ import type { AppMode } from "../../../core/mode";import { useHotkey } from "../../../hooks/useHotkey";import { type Theme, useTheme } from "../../../theme/useTheme";import { AddCellWithAI } from "../ai/add-cell-with-ai";-import {- ConnectingAlert,- NotStartedConnectionAlert,-} from "../alerts/connecting-alert";+import { NotStartedConnectionAlert } from "../alerts/connecting-alert";import { FloatingOutline } from "../chrome/panels/outline/floating-outline";import { useChromeActions } from "../chrome/state";import { Column } from "../columns/cell-column";@@ -140,7 +137,6 @@ const CellArrayInternal: React.FC<CellArrayProps> = ({<PackageAlert /><StartupLogsAlert /><StdinBlockingAlert />- <ConnectingAlert /><NotebookBanner width={appConfig.width} />{/* Only show if not cells, otherwise running a single cell will start the connection */}{cellIds.idLength === 0 && <NotStartedConnectionAlert />}diff --git a/frontend/src/core/MarimoApp.tsx b/frontend/src/core/MarimoApp.tsxindex cdd6edd936..235dc09936 100644--- a/frontend/src/core/MarimoApp.tsx+++ b/frontend/src/core/MarimoApp.tsx@@ -12,7 +12,6 @@ import { getInitialAppMode } from "@/core/mode";import { CssVariables } from "@/theme/ThemeProvider";import { reactLazyWithPreload } from "@/utils/lazy";import { ErrorBoundary } from "../components/editor/boundary/ErrorBoundary";-import { KernelStartupErrorModal } from "../components/editor/KernelStartupErrorModal";import { TracebackModalContainer } from "../components/editor/TracebackModalContainer";import { ModalProvider } from "../components/modal/ImperativeModal";import { Toaster } from "../components/ui/toaster";@@ -105,7 +104,6 @@ const Providers = memo(({ children }: PropsWithChildren) => {{children}<Toaster /><TailwindIndicator />- <KernelStartupErrorModal /><TracebackModalContainer /></ModalProvider></LocaleProvider>diff --git a/frontend/src/core/edit-app.tsx b/frontend/src/core/edit-app.tsxindex ee06beb066..9c8c48cb07 100644--- a/frontend/src/core/edit-app.tsx+++ b/frontend/src/core/edit-app.tsx@@ -9,7 +9,8 @@ import { useAtomValue, useSetAtom } from "jotai";import { useEffect } from "react";import { NotStartedConnectionAlert } from "@/components/editor/alerts/connecting-alert";import { Controls } from "@/components/editor/controls/Controls";-import { AppHeader } from "@/components/editor/header/app-header";+import { SandboxController } from "@/components/editor/chrome/panels/sandbox-controller";+import { ConnectionNotice } from "@/components/editor/alerts/connection-notice";import { FilenameForm } from "@/components/editor/header/filename-form";import { MultiCellActionToolbar } from "@/components/editor/navigation/multi-cell-action-toolbar";import { ViewerBanner } from "@/components/editor/viewer-banner";@@ -158,6 +159,7 @@ export const EditApp: React.FC<AppProps> = ({return (<>+ <SandboxController onReconnect={reconnect} /><AppContainerconnection={connection}isRunning={isRunning}@@ -165,10 +167,9 @@ export const EditApp: React.FC<AppProps> = ({onReconnect={reconnect}><ViewerBanner />- <AppHeader- connection={connection}+ <divclassName={cn(- "pt-4 sm:pt-12 pb-2 mb-4 print:hidden z-50",+ "pt-4 sm:pt-12 pb-6 print:hidden z-50",// Keep the header sticky when scrolling horizontally, for column mode"sticky left-0",)}@@ -178,7 +179,9 @@ export const EditApp: React.FC<AppProps> = ({<FilenameForm filename={filename} /></div>)}- </AppHeader>+ </div>++ <ConnectionNotice appConfig={appConfig} onRetry={reconnect} />{/* Don't render until we have a single cell. NotStartedConnectionAlertstill covers the "no remote runtime started" prompt. */}diff --git a/frontend/src/core/errors/state.ts b/frontend/src/core/errors/state.tsindex 13c001d715..334b198291 100644--- a/frontend/src/core/errors/state.ts+++ b/frontend/src/core/errors/state.ts@@ -7,8 +7,7 @@ import { generateUUID } from "@/utils/uuid";import type { Banner } from "../kernel/messages";/**- * Atom for storing kernel startup error message.- * When set to a non-null value, shows a modal with the error details.+ * Full startup diagnostics, retained until a new connection attempt or readiness.*/export const kernelStartupErrorAtom = atom<string | null>(null);diff --git a/frontend/src/core/islands/bootstrap.ts b/frontend/src/core/islands/bootstrap.tsindex 81c2620c3d..70c07d30d5 100644--- a/frontend/src/core/islands/bootstrap.ts+++ b/frontend/src/core/islands/bootstrap.ts@@ -201,6 +201,7 @@ function handleMessage(case "storage-download-ready":case "secret-keys-result":case "startup-logs":+ case "startup-progress":case "interrupted":case "reconnected":case "cache-cleared":diff --git a/frontend/src/core/islands/bridge.ts b/frontend/src/core/islands/bridge.tsindex 6830a8b2be..c3f48cc750 100644--- a/frontend/src/core/islands/bridge.ts+++ b/frontend/src/core/islands/bridge.ts@@ -370,6 +370,9 @@ export class IslandsPyodideBridge implements RunRequests, EditRequests {addPackage = throwNotImplemented;removePackage = throwNotImplemented;getPackageList = throwNotImplemented;+ getSandbox = throwNotImplemented;+ updateManifest = throwNotImplemented;+ syncSandbox = throwNotImplemented;getDependencyTree = throwNotImplemented;getRecentFiles = throwNotImplemented;getWorkspaceFiles = throwNotImplemented;diff --git a/frontend/src/core/network/connection-notice.ts b/frontend/src/core/network/connection-notice.tsnew file mode 100644index 0000000000..7061ef398a--- /dev/null+++ b/frontend/src/core/network/connection-notice.ts@@ -0,0 +1,84 @@+/* Copyright 2026 Marimo. All rights reserved. */+import { atom } from "jotai";+import { kernelStartupErrorAtom } from "@/core/errors/state";+import { sandboxAtom, sandboxSyncAtom } from "@/core/packages/sandbox-state";+import { WebSocketClosedReason, WebSocketState } from "@/core/websocket/types";+import { connectionAtom } from "./connection";++export const connectionNoticeAtom = atom((get) => {+ const connection = get(connectionAtom);+ const backend = get(sandboxAtom)?.backend;+ const sandbox = Boolean(backend);+ const sync = get(sandboxSyncAtom);+ if (+ sandbox &&+ (sync.pending || sync.error) &&+ connection.state === WebSocketState.OPEN+ ) {+ return {+ sandbox,+ title: sync.pending ? "Syncing sandbox…" : "Sandbox sync failed",+ description: sync.pending+ ? "Applying the saved manifest to this notebook’s environment."+ : "Review the error details, then try again.",+ pending: sync.pending,+ error: sync.error,+ };+ }+ if (connection.state === WebSocketState.CONNECTING) {+ const messages = {+ "preparing-environment": {+ title: backend+ ? `Preparing ${backend} sandbox…`+ : "Preparing environment…",+ description:+ "Getting this notebook’s Python environment ready. The first start can take a few minutes.",+ },+ "starting-kernel": {+ title: "Starting notebook…",+ description:+ "The environment is prepared. Waiting for the Python kernel to connect to this notebook.",+ },+ reconnecting: {+ title: "Reconnecting…",+ description:+ "The connection was interrupted. Your notebook and existing outputs stay visible while the kernel reconnects.",+ },+ };+ return {+ sandbox,+ ...(connection.phase+ ? messages[connection.phase]+ : {+ title: "Connecting…",+ description: "Waiting for the notebook’s kernel to connect.",+ }),+ pending: true,+ error: null,+ };+ }+ if (connection.state === WebSocketState.CLOSED) {+ const startupFailed =+ connection.code === WebSocketClosedReason.KERNEL_STARTUP_ERROR;+ const environmentFailed =+ startupFailed && connection.phase === "preparing-environment";+ return {+ sandbox,+ title: environmentFailed+ ? "Sandbox setup failed"+ : startupFailed+ ? "Kernel failed to start"+ : connection.reason,+ description: environmentFailed+ ? "The notebook can’t run yet."+ : startupFailed+ ? "The Python kernel could not start. Check the error details, then try again."+ : "The connection to the notebook’s kernel was lost.",+ pending: false,+ error: startupFailed+ ? (get(kernelStartupErrorAtom) ?? connection.reason)+ : null,+ };+ }+ return null;+});diff --git a/frontend/src/core/network/requests-lazy.ts b/frontend/src/core/network/requests-lazy.tsindex 8a30594d18..25ac2c2d64 100644--- a/frontend/src/core/network/requests-lazy.ts+++ b/frontend/src/core/network/requests-lazy.ts@@ -93,6 +93,9 @@ const ACTIONS: Record<keyof AllRequests, Action> = {saveUserConfig: "throwError",sendShutdown: "throwError",getPackageList: "throwError",+ getSandbox: "serverOnly",+ updateManifest: "serverOnly",+ syncSandbox: "serverOnly",getDependencyTree: "throwError",addPackage: "throwError",removePackage: "throwError",diff --git a/frontend/src/core/network/requests-network.ts b/frontend/src/core/network/requests-network.tsindex 47de80a1de..3a17562b1c 100644--- a/frontend/src/core/network/requests-network.ts+++ b/frontend/src/core/network/requests-network.ts@@ -532,6 +532,18 @@ export function createNetworkRequests(): EditRequests & RunRequests {}).then(handleResponseReturnNull);},+ getSandbox: (request) =>+ getClient()+ .POST("/api/packages/sandbox", { body: request, params: getParams() })+ .then(handleResponse),+ updateManifest: (request) =>+ getClient()+ .POST("/api/packages/manifest", { body: request, params: getParams() })+ .then(handleResponse),+ syncSandbox: (request) =>+ getClient()+ .POST("/api/packages/sync", { body: request, params: getParams() })+ .then(handleResponse),addPackage: (request) => {return getClient().POST("/api/packages/add", {diff --git a/frontend/src/core/network/requests-static.ts b/frontend/src/core/network/requests-static.tsindex 901f08d268..6cf6350232 100644--- a/frontend/src/core/network/requests-static.ts+++ b/frontend/src/core/network/requests-static.ts@@ -98,6 +98,9 @@ export function createStaticRequests(): EditRequests & RunRequests {addPackage: throwNotInEditMode,removePackage: throwNotInEditMode,getPackageList: throwNotInEditMode,+ getSandbox: throwNotInEditMode,+ updateManifest: throwNotInEditMode,+ syncSandbox: throwNotInEditMode,getDependencyTree: throwNotInEditMode,listSecretKeys: throwNotInEditMode,writeSecret: throwNotInEditMode,diff --git a/frontend/src/core/network/requests-toasting.tsx b/frontend/src/core/network/requests-toasting.tsxindex c9397269cf..f686da15bc 100644--- a/frontend/src/core/network/requests-toasting.tsx+++ b/frontend/src/core/network/requests-toasting.tsx@@ -79,6 +79,9 @@ export function createErrorToastingRequests(addPackage: "Failed to add package",removePackage: "Failed to remove package",getPackageList: "Failed to get package list",+ getSandbox: "",+ updateManifest: "",+ syncSandbox: "",getDependencyTree: "Failed to get dependency tree",listSecretKeys: "Failed to fetch secrets",writeSecret: "Failed to write secret",diff --git a/frontend/src/core/network/resolve.ts b/frontend/src/core/network/resolve.tsindex 2a62903e74..9c0d26c3db 100644--- a/frontend/src/core/network/resolve.ts+++ b/frontend/src/core/network/resolve.ts@@ -1,4 +1,5 @@/* Copyright 2026 Marimo. All rights reserved. */+import { withPackageInvalidation } from "../packages/package-data";import { getRuntimeManager } from "../runtime/config";import { isStaticNotebook } from "../static/static-state";import { PyodideBridge } from "../wasm/bridge";@@ -20,5 +21,5 @@ export function resolveRequestClient(): EditRequests & RunRequests {getRuntimeManager(),);}- return createErrorToastingRequests(base);+ return withPackageInvalidation(createErrorToastingRequests(base));}diff --git a/frontend/src/core/network/types.ts b/frontend/src/core/network/types.tsindex 4cb233d666..78208f0c1c 100644--- a/frontend/src/core/network/types.ts+++ b/frontend/src/core/network/types.ts@@ -69,6 +69,10 @@ export type ListPackagesResponse = schemas["ListPackagesResponse"];export type DependencyTreeResponse = schemas["DependencyTreeResponse"];export type DependencyTreeNode = schemas["DependencyTreeNode"];+export type SandboxRequest = schemas["SandboxRequest"];+export type SandboxResponse = schemas["SandboxResponse"];+export type UpdateManifestRequest = schemas["UpdateManifestRequest"];+export type SyncSandboxResponse = schemas["SyncSandboxResponse"];export type PackageOperationResponse = schemas["PackageOperationResponse"];export type InstantiateNotebookRequest = schemas["InstantiateNotebookRequest"];export type MarimoConfig = schemas["MarimoConfig"];@@ -246,6 +250,9 @@ export interface EditRequests {autoExportAsMarkdown: (request: AutoExportAsMarkdownRequest) => Promise<null>;autoExportAsIPYNB: (request: AutoExportAsIPYNBRequest) => Promise<null>;updateCellOutputs: (request: UpdateCellOutputsRequest) => Promise<null>;+ getSandbox: (request: SandboxRequest) => Promise<SandboxResponse>;+ updateManifest: (request: UpdateManifestRequest) => Promise<SandboxResponse>;+ syncSandbox: (request: SandboxRequest) => Promise<SyncSandboxResponse>;// Package requestsgetPackageList: () => Promise<ListPackagesResponse>;getDependencyTree: () => Promise<DependencyTreeResponse>;diff --git a/frontend/src/core/packages/__tests__/usePackageAction.test.tsx b/frontend/src/core/packages/__tests__/usePackageAction.test.tsxnew file mode 100644index 0000000000..8bb41da40d--- /dev/null+++ b/frontend/src/core/packages/__tests__/usePackageAction.test.tsx@@ -0,0 +1,129 @@+/* Copyright 2026 Marimo. All rights reserved. */+import { act, renderHook } from "@testing-library/react";+import { createStore, Provider } from "jotai";+import { beforeEach, describe, expect, it, vi } from "vitest";+import { MockRequestClient } from "@/__mocks__/requests";+import { toast } from "@/components/ui/use-toast";+import { requestClientAtom } from "@/core/network/requests";+import type { PackageOperationResponse } from "@/core/network/types";+import { usePackageAction } from "../usePackageAction";++vi.mock("@/components/ui/use-toast", () => ({ toast: vi.fn() }));++function setup(action: "upgrade" | "remove") {+ const client = MockRequestClient.create();+ const store = createStore();+ store.set(requestClientAtom, client);+ return {+ request: vi.mocked(+ action === "upgrade" ? client.addPackage : client.removePackage,+ ),+ ...renderHook(+ () =>+ usePackageAction(action, "numpy", [{ kind: "group", value: "dev" }]),+ {+ wrapper: ({ children }) => (+ <Provider store={store}>{children}</Provider>+ ),+ },+ ),+ };+}++describe("usePackageAction", () => {+ beforeEach(() => vi.clearAllMocks());++ it.each([+ { action: "upgrade", title: "Package upgraded", upgrade: true },+ { action: "remove", title: "Package removed" },+ ] as const)(+ "preserves dependency groups and prevents duplicate $action requests",+ async ({ action, title, ...options }) => {+ const { result, request } = setup(action);+ const { promise, resolve } =+ Promise.withResolvers<PackageOperationResponse>();+ request.mockReturnValue(promise);+ let pending: Promise<void>;+ act(() => {+ pending = result.current.run();+ });+ expect(result.current.loading).toBe(true);+ await act(async () => {+ await result.current.run();+ });+ expect(request).toHaveBeenCalledExactlyOnceWith({+ package: "numpy",+ group: "dev",+ ...options,+ });+ await act(async () => {+ resolve({ success: true });+ await pending;+ });+ expect(result.current.loading).toBe(false);+ expect(toast).toHaveBeenCalledExactlyOnceWith(+ expect.objectContaining({ title }),+ );+ },+ );++ it("reports saved changes requiring a restart without claiming success", async () => {+ const { result, request } = setup("upgrade");+ request.mockResolvedValue({ success: false, restartRequired: true });+ await act(async () => {+ await result.current.run();+ });+ expect(toast).toHaveBeenCalledExactlyOnceWith(+ expect.objectContaining({+ title: "Changes saved — restart required",+ }),+ );+ });++ it.each([+ {+ response: { success: false, error: "resolver failed" },+ description: "resolver failed",+ },+ { response: { success: false }, description: expect.any(String) },+ ])(+ "reports failed responses as errors: $response",+ async ({ response, description }) => {+ const { result, request } = setup("remove");+ request.mockResolvedValue(response);+ await act(async () => {+ await result.current.run();+ });+ expect(toast).toHaveBeenCalledExactlyOnceWith(+ expect.objectContaining({+ title: "Failed to remove package",+ description,+ variant: "danger",+ }),+ );+ },+ );++ it("reports request errors and allows a retry", async () => {+ const { result, request } = setup("remove");+ request.mockRejectedValueOnce(new Error("offline"));+ await act(async () => {+ await result.current.run();+ });+ expect(toast).toHaveBeenCalledExactlyOnceWith(+ expect.objectContaining({+ title: "Failed to remove package",+ description: "offline",+ variant: "danger",+ }),+ );+ expect(result.current.loading).toBe(false);+ request.mockResolvedValue({ success: true });+ await act(async () => {+ await result.current.run();+ });+ expect(toast).toHaveBeenLastCalledWith(+ expect.objectContaining({ title: "Package removed" }),+ );+ });+});diff --git a/frontend/src/core/packages/__tests__/useSandboxController.test.tsx b/frontend/src/core/packages/__tests__/useSandboxController.test.tsxnew file mode 100644index 0000000000..7343e85119--- /dev/null+++ b/frontend/src/core/packages/__tests__/useSandboxController.test.tsx@@ -0,0 +1,165 @@+/* Copyright 2026 Marimo. All rights reserved. */+import { act, renderHook, waitFor } from "@testing-library/react";+import { Provider } from "jotai";+import { beforeEach, describe, expect, it, vi } from "vitest";+import { MockRequestClient } from "@/__mocks__/requests";+import { kernelStartupErrorAtom } from "@/core/errors/state";+import { connectionAtom } from "@/core/network/connection";+import { requestClientAtom } from "@/core/network/requests";+import type {+ SandboxResponse,+ SyncSandboxResponse,+} from "@/core/network/types";+import { filenameAtom } from "@/core/saving/file-state";+import { store } from "@/core/state/jotai";+import { WebSocketState } from "@/core/websocket/types";+import { HTTPError } from "@/utils/errors";+import { packageDataVersionAtom } from "../package-data";+import {+ sandboxActionsAtom,+ sandboxAtom,+ sandboxSyncAtom,+} from "../sandbox-state";+import { useSandboxController } from "../useSandboxController";++vi.mock("../toast-components", () => ({+ showPackageRestartToast: vi.fn(),+ showSandboxSyncToast: vi.fn(),+}));++const manifest = 'dependencies = ["numpy"]';+const sandbox: SandboxResponse = {+ backend: "uv",+ manifest,+ filename: "notebook.py",+};++beforeEach(() => {+ store.set(sandboxAtom, null);+ store.set(sandboxSyncAtom, { pending: false, error: null });+ store.set(sandboxActionsAtom, null);+ store.set(connectionAtom, { state: WebSocketState.OPEN });+ store.set(kernelStartupErrorAtom, null);+ store.set(filenameAtom, "notebook.py");+ store.set(packageDataVersionAtom, 0);+});++function setup() {+ const client = MockRequestClient.create({+ getSandbox: vi.fn().mockResolvedValue(sandbox),+ updateManifest: vi.fn(async ({ contents }) => ({+ ...sandbox,+ manifest: contents,+ })),+ syncSandbox: vi.fn().mockResolvedValue({ success: true, reconnect: false }),+ });+ store.set(requestClientAtom, client);+ const reconnect = vi.fn<() => Promise<void>>().mockResolvedValue(undefined);+ return {+ client,+ reconnect,+ ...renderHook(() => useSandboxController(reconnect), {+ wrapper: ({ children }) => <Provider store={store}>{children}</Provider>,+ }),+ };+}++describe("useSandboxController", () => {+ it("keeps a conflicting draft across closing and only discards it on explicit reload", async () => {+ const { result, client } = setup();+ vi.mocked(client.updateManifest).mockRejectedValue(+ new HTTPError(409, "Conflict", { detail: "Manifest changed on disk" }),+ );+ await act(async () => {+ await store.get(sandboxActionsAtom)?.editManifest();+ });+ act(() => result.current.setDraft("dependencies = []"));+ await act(async () => {+ await result.current.saveAndSync();+ });+ expect(client.updateManifest).toHaveBeenCalledExactlyOnceWith({+ fileKey: "notebook.py",+ previous: manifest,+ contents: "dependencies = []",+ });+ expect(result.current).toMatchObject({+ open: true,+ draft: "dependencies = []",+ dirty: true,+ conflict: true,+ diagnostic: "Manifest changed on disk",+ pending: false,+ });+ expect(client.syncSandbox).not.toHaveBeenCalled();+ act(() => result.current.setOpen(false));+ await act(async () => {+ await store.get(sandboxActionsAtom)?.editManifest();+ });+ expect(result.current.draft).toBe("dependencies = []");+ await act(async () => {+ await result.current.loadManifest();+ });+ expect(result.current).toMatchObject({+ draft: manifest,+ dirty: false,+ conflict: false,+ diagnostic: null,+ });+ });++ it("shares sync progress across callers and refreshes packages without reconnecting", async () => {+ const { client, reconnect } = setup();+ const { promise, resolve } = Promise.withResolvers<SyncSandboxResponse>();+ vi.mocked(client.syncSandbox).mockReturnValue(promise);+ const actions = store.get(sandboxActionsAtom)!;+ let pending: Promise<boolean>;+ act(() => {+ pending = actions.sync();+ });+ expect(store.get(sandboxSyncAtom)).toEqual({ pending: true, error: null });+ await act(async () => {+ expect(await actions.sync()).toBe(false);+ });+ expect(client.syncSandbox).toHaveBeenCalledTimes(1);+ await act(async () => {+ resolve({ success: true, reconnect: false });+ expect(await pending).toBe(true);+ });+ expect(store.get(sandboxSyncAtom)).toEqual({ pending: false, error: null });+ expect(store.get(packageDataVersionAtom)).toBe(1);+ expect(reconnect).not.toHaveBeenCalled();+ });++ it("reports sync failure and clears it when retrying", async () => {+ const { client } = setup();+ const actions = store.get(sandboxActionsAtom)!;+ vi.mocked(client.syncSandbox).mockRejectedValueOnce(new Error("offline"));+ await act(async () => {+ expect(await actions.sync()).toBe(false);+ });+ expect(store.get(sandboxSyncAtom)).toEqual({+ pending: false,+ error: "offline",+ });+ await act(async () => {+ expect(await actions.sync()).toBe(true);+ });+ expect(store.get(sandboxSyncAtom)).toEqual({ pending: false, error: null });+ });++ it("ignores stale metadata after a filename change and unregisters actions on unmount", async () => {+ const { client, unmount } = setup();+ await waitFor(() => expect(store.get(sandboxAtom)).toEqual(sandbox));+ const { promise, resolve } = Promise.withResolvers<SandboxResponse>();+ vi.mocked(client.getSandbox).mockReturnValueOnce(promise);+ act(() => store.set(filenameAtom, "old.py"));+ const current = { ...sandbox, filename: "current.py" };+ vi.mocked(client.getSandbox).mockResolvedValue(current);+ act(() => store.set(filenameAtom, "current.py"));+ await waitFor(() => expect(store.get(sandboxAtom)).toEqual(current));+ await act(async () => resolve({ ...sandbox, filename: "old.py" }));+ expect(store.get(sandboxAtom)).toEqual(current);+ unmount();+ expect(store.get(sandboxActionsAtom)).toBeNull();+ });+});diff --git a/frontend/src/core/packages/package-data.ts b/frontend/src/core/packages/package-data.tsnew file mode 100644index 0000000000..1bdb655509--- /dev/null+++ b/frontend/src/core/packages/package-data.ts@@ -0,0 +1,35 @@+/* Copyright 2026 Marimo. All rights reserved. */+import { atom } from "jotai";+import type {+ EditRequests,+ PackageOperationResponse,+ RunRequests,+} from "@/core/network/types";+import { store } from "@/core/state/jotai";++export const packageDataVersionAtom = atom(0);+export function invalidatePackageData() {+ store.set(packageDataVersionAtom, (version) => version + 1);+}++/** Refresh package consumers regardless of which UI initiated a mutation. */+export function withPackageInvalidation(+ client: EditRequests & RunRequests,+): EditRequests & RunRequests {+ function invalidateAfter<Request, Response extends PackageOperationResponse>(+ request: (body: Request) => Promise<Response>,+ ) {+ return async (body: Request) => {+ const result = await request(body);+ if (result.success || result.restartRequired) {+ invalidatePackageData();+ }+ return result;+ };+ }+ return {+ ...client,+ addPackage: invalidateAfter(client.addPackage),+ removePackage: invalidateAfter(client.removePackage),+ };+}diff --git a/frontend/src/core/packages/sandbox-state.ts b/frontend/src/core/packages/sandbox-state.tsnew file mode 100644index 0000000000..dbf66d26e5--- /dev/null+++ b/frontend/src/core/packages/sandbox-state.ts@@ -0,0 +1,15 @@+/* Copyright 2026 Marimo. All rights reserved. */+import { atom } from "jotai";+import type { SandboxResponse } from "@/core/network/types";++export const sandboxAtom = atom<SandboxResponse | null>(null);+export const sandboxSyncAtom = atom<{ pending: boolean; error: string | null }>(+ {+ pending: false,+ error: null,+ },+);+export const sandboxActionsAtom = atom<{+ sync: () => Promise<boolean>;+ editManifest: () => Promise<void>;+} | null>(null);diff --git a/frontend/src/core/packages/toast-components.tsx b/frontend/src/core/packages/toast-components.tsxindex 04bf76f252..a8ff6c7023 100644--- a/frontend/src/core/packages/toast-components.tsx+++ b/frontend/src/core/packages/toast-components.tsx@@ -29,6 +29,17 @@ export const showPackageRestartToast = () => {});};+export const showSandboxSyncToast = () => {+ toast({+ title: "Sandbox environment synced",+ description: (+ <div className="text-xs text-muted-foreground">+ Some Python packages may require a kernel restart to see changes.+ </div>+ ),+ });+};+export const showAddPackageToast = (packageName: string | string[],error?: string | null,diff --git a/frontend/src/core/packages/useInstallPackage.ts b/frontend/src/core/packages/useInstallPackage.tsindex 9d25188c27..28ff085ff8 100644--- a/frontend/src/core/packages/useInstallPackage.ts+++ b/frontend/src/core/packages/useInstallPackage.ts@@ -37,10 +37,10 @@ export function useInstallPackages(): {showPackageRestartToast();} else if (response.success) {showAddPackageToast(packages);+ onSuccess?.();} else {showAddPackageToast(packages, response.error);}- onSuccess?.();} catch (error) {Logger.error(error);} finally {diff --git a/frontend/src/core/packages/usePackageAction.ts b/frontend/src/core/packages/usePackageAction.tsnew file mode 100644index 0000000000..7f6c49b453--- /dev/null+++ b/frontend/src/core/packages/usePackageAction.ts@@ -0,0 +1,51 @@+/* Copyright 2026 Marimo. All rights reserved. */+import { useRef, useState } from "react";+import useEvent from "react-use-event-hook";+import { useRequestClient } from "@/core/network/requests";+import type { DependencyTreeNode } from "@/core/network/types";+import { prettyError } from "@/utils/errors";+import {+ showPackageRestartToast,+ showRemovePackageToast,+ showUpgradePackageToast,+} from "./toast-components";++/** Shared mutation lifecycle for package actions in both list and tree views. */+export function usePackageAction(+ action: "upgrade" | "remove",+ packageName: string,+ tags?: DependencyTreeNode["tags"],+) {+ const { addPackage, removePackage } = useRequestClient();+ const [loading, setLoading] = useState(false);+ const inFlight = useRef(false);+ const run = useEvent(async () => {+ if (inFlight.current) {+ return;+ }+ inFlight.current = true;+ setLoading(true);+ const showResult =+ action === "upgrade" ? showUpgradePackageToast : showRemovePackageToast;+ try {+ const group = tags?.find((tag) => tag.kind === "group")?.value;+ const request = { package: packageName, group };+ const response = await (action === "upgrade"+ ? addPackage({ ...request, upgrade: true })+ : removePackage(request));+ if (response.restartRequired) {+ showPackageRestartToast();+ } else if (response.success) {+ showResult(packageName);+ } else {+ showResult(packageName, response.error || "Package operation failed.");+ }+ } catch (error) {+ showResult(packageName, prettyError(error));+ } finally {+ inFlight.current = false;+ setLoading(false);+ }+ });+ return { loading, run };+}diff --git a/frontend/src/core/packages/usePackageDependencies.ts b/frontend/src/core/packages/usePackageDependencies.tsnew file mode 100644index 0000000000..60b240e550--- /dev/null+++ b/frontend/src/core/packages/usePackageDependencies.ts@@ -0,0 +1,22 @@+/* Copyright 2026 Marimo. All rights reserved. */+import { useAtomValue } from "jotai";+import { useResolvedMarimoConfig } from "@/core/config/config";+import { useRequestClient } from "@/core/network/requests";+import { useAsyncData } from "@/hooks/useAsyncData";+import { packageDataVersionAtom } from "./package-data";++/** Load the available package views and refresh them after package mutations. */+export function usePackageDependencies() {+ const packageDataVersion = useAtomValue(packageDataVersionAtom);+ const [config] = useResolvedMarimoConfig();+ const packageManager = config.package_management.manager;+ const { getDependencyTree, getPackageList } = useRequestClient();++ return useAsyncData(async () => {+ const { context, tree } = await getDependencyTree();+ // Both sandbox endpoints inspect the same environment; only fetch it once.+ const list =+ context.kind === "sandbox" ? [] : (await getPackageList()).packages;+ return { list, context, tree };+ }, [getDependencyTree, getPackageList, packageManager, packageDataVersion]);+}diff --git a/frontend/src/core/packages/useSandboxController.ts b/frontend/src/core/packages/useSandboxController.tsnew file mode 100644index 0000000000..059cbc8e1d--- /dev/null+++ b/frontend/src/core/packages/useSandboxController.ts@@ -0,0 +1,188 @@+/* Copyright 2026 Marimo. All rights reserved. */+import { useAtom, useAtomValue, useSetAtom } from "jotai";+import { useEffect, useRef, useState } from "react";+import useEvent from "react-use-event-hook";+import { kernelStartupErrorAtom } from "@/core/errors/state";+import { connectionAtom } from "@/core/network/connection";+import { useRequestClient } from "@/core/network/requests";+import { useFilename } from "@/core/saving/filename";+import { waitFor } from "@/core/state/jotai";+import { isWasm } from "@/core/wasm/utils";+import { WebSocketState } from "@/core/websocket/types";+import { HTTPError, prettyError } from "@/utils/errors";+import { invalidatePackageData } from "./package-data";+import {+ sandboxActionsAtom,+ sandboxAtom,+ sandboxSyncAtom,+} from "./sandbox-state";+import {+ showPackageRestartToast,+ showSandboxSyncToast,+} from "./toast-components";++/** Mount once with the editor so manifest drafts survive closing Packages. */+export function useSandboxController(onReconnect: () => Promise<void>) {+ const requests = useRequestClient();+ const filename = useFilename();+ const connection = useAtomValue(connectionAtom);+ const startupError = useAtomValue(kernelStartupErrorAtom);+ const setSandbox = useSetAtom(sandboxAtom);+ const [operation, setOperation] = useAtom(sandboxSyncAtom);+ const setActions = useSetAtom(sandboxActionsAtom);+ const [open, setOpen] = useState(false);+ const [document, setDocument] = useState<{+ original: string;+ draft: string;+ } | null>(null);+ const [error, setError] = useState<string | null>(null);+ const [saving, setSaving] = useState(false);+ const [loading, setLoading] = useState(false);+ const [conflict, setConflict] = useState(false);+ const inFlight = useRef(false);+ const dirty = document !== null && document.original !== document.draft;++ useEffect(() => {+ if (isWasm()) {+ return;+ }+ let cancelled = false;+ requests+ .getSandbox({ fileKey: filename })+ .then((value) => {+ if (!cancelled) {+ setSandbox(value);+ }+ })+ .catch(() => {+ /* A connection error is already shown by the editor. */+ });+ return () => {+ cancelled = true;+ };+ }, [requests, filename, connection.state, setSandbox]);++ const sync = useEvent(async () => {+ if (inFlight.current || connection.state === WebSocketState.CONNECTING) {+ return false;+ }+ inFlight.current = true;+ setOperation((value) => ({ ...value, pending: true, error: null }));+ try {+ const result = await requests.syncSandbox({ fileKey: filename });+ if (result.restartRequired) {+ showPackageRestartToast();+ }+ if (!result.success) {+ throw new Error(result.error ?? "Sandbox sync failed.");+ }+ if (result.reconnect) {+ await onReconnect();+ const status = await waitFor(+ connectionAtom,+ (value) =>+ value.state === WebSocketState.OPEN ||+ value.state === WebSocketState.CLOSED,+ );+ if (status.state === WebSocketState.CLOSED) {+ return false;+ }+ }+ if (!result.reconnect) {+ invalidatePackageData();+ }+ showSandboxSyncToast();+ return true;+ } catch (cause) {+ setOperation((value) => ({ ...value, error: prettyError(cause) }));+ return false;+ } finally {+ inFlight.current = false;+ setOperation((value) => ({ ...value, pending: false }));+ }+ });++ const loadManifest = useEvent(async () => {+ setLoading(true);+ setError(null);+ setConflict(false);+ try {+ const result = await requests.getSandbox({ fileKey: filename });+ setSandbox(result);+ if (result.manifest === null) {+ throw new Error("No notebook manifest is available yet.");+ }+ setDocument({ original: result.manifest, draft: result.manifest });+ } catch (cause) {+ setError(prettyError(cause));+ } finally {+ setLoading(false);+ }+ });++ const editManifest = useEvent(async () => {+ setOpen(true);+ if (!dirty) {+ await loadManifest();+ }+ });++ useEffect(() => {+ setActions({ sync, editManifest });+ return () => {+ setActions(null);+ };+ }, [sync, editManifest, setActions]);++ const saveAndSync = async () => {+ if (!document || loading || saving || operation.pending) {+ return;+ }+ setSaving(true);+ setError(null);+ try {+ if (dirty) {+ const result = await requests.updateManifest({+ fileKey: filename,+ contents: document.draft,+ previous: document.original,+ });+ setSandbox(result);+ if (result.manifest !== null) {+ setDocument({ original: result.manifest, draft: result.manifest });+ }+ }+ if (await sync()) {+ setOpen(false);+ }+ } catch (cause) {+ setError(prettyError(cause));+ setConflict(cause instanceof HTTPError && cause.status === 409);+ } finally {+ setSaving(false);+ }+ };+ const pending =+ saving ||+ loading ||+ operation.pending ||+ connection.state === WebSocketState.CONNECTING;+ const diagnostic = error ?? operation.error ?? startupError;+ return {+ filename,+ open,+ setOpen,+ draft: document?.draft ?? null,+ setDraft: (draft: string) =>+ setDocument((value) => value && { ...value, draft }),+ dirty,+ loading,+ saving,+ pending,+ error,+ diagnostic,+ conflict,+ loadManifest,+ saveAndSync,+ };+}diff --git a/frontend/src/core/run-app.tsx b/frontend/src/core/run-app.tsxindex 8786ab48dc..14dd778dc2 100644--- a/frontend/src/core/run-app.tsx+++ b/frontend/src/core/run-app.tsx@@ -3,6 +3,7 @@import { atom, useAtomValue } from "jotai";import { ArrowLeftIcon } from "lucide-react";import { useEffect } from "react";+import { KernelStartupErrorModal } from "@/components/editor/KernelStartupErrorModal";import { AppContainer } from "@/components/editor/app-container";import { AppHeader } from "@/components/editor/header/app-header";import { ProgressiveBoundary } from "@/components/lifecycle/ProgressiveBoundary";@@ -78,6 +79,7 @@ export const RunApp: React.FC<AppProps> = ({ appConfig, hideHeader }) => {width={appConfig.width}onReconnect={reconnect}>+ <KernelStartupErrorModal /><AppHeaderconnection={connection}className={hideHeader ? "hidden" : "sm:pt-8"}diff --git a/frontend/src/core/wasm/bridge.ts b/frontend/src/core/wasm/bridge.tsindex 0d375ae20a..d272006c55 100644--- a/frontend/src/core/wasm/bridge.ts+++ b/frontend/src/core/wasm/bridge.ts@@ -640,6 +640,17 @@ export class PyodideBridge implements RunRequests, EditRequests {return response;};+ getSandbox: EditRequests["getSandbox"] = async () => ({+ backend: null,+ manifest: null,+ filename: null,+ });+ updateManifest: EditRequests["updateManifest"] = async () => {+ throw new Error("Sandboxes are not supported in WebAssembly");+ };+ syncSandbox: EditRequests["syncSandbox"] = async () => {+ throw new Error("Sandboxes are not supported in WebAssembly");+ };getDependencyTree: EditRequests["getDependencyTree"] = async () => {// WASM doesn't support dependency trees yetreturn {diff --git a/frontend/src/core/websocket/__tests__/useMarimoKernelConnection.hook.test.tsx b/frontend/src/core/websocket/__tests__/useMarimoKernelConnection.hook.test.tsxindex 368fa97c50..523deb3f90 100644--- a/frontend/src/core/websocket/__tests__/useMarimoKernelConnection.hook.test.tsx+++ b/frontend/src/core/websocket/__tests__/useMarimoKernelConnection.hook.test.tsx@@ -1,11 +1,25 @@/* Copyright 2026 Marimo. All rights reserved. */// @vitest-environment jsdom-import { act, renderHook } from "@testing-library/react";+import {+ act,+ fireEvent,+ render,+ renderHook,+ screen,+} from "@testing-library/react";import { createStore, Provider as JotaiProvider } from "jotai";import type React from "react";import { ErrorBoundary } from "react-error-boundary";-import { beforeEach, describe, expect, it, type Mock, vi } from "vitest";+import {+ afterEach,+ beforeEach,+ describe,+ expect,+ it,+ type Mock,+ vi,+} from "vitest";vi.mock("@/core/websocket/useWebSocket", async () => {const actual =@@ -26,6 +40,13 @@ vi.mock("@/core/runtime/config", async () => {};});+import { MockNotebook } from "@/__mocks__/notebook";+import { cellId } from "@/__tests__/branded";+import { notebookAtom } from "@/core/cells/cells";+import { AppConfigSchema } from "@/core/config/config-schema";+import { ConnectionNotice } from "@/components/editor/alerts/connection-notice";+import { kernelStartupErrorAtom } from "@/core/errors/state";+import type { NotificationPayload } from "@/core/kernel/messages";import { useRuntimeManager } from "@/core/runtime/config";import { initialRunCompletedAtom } from "../../kernel/state";import { connectionAtom } from "../../network/connection";@@ -188,3 +209,192 @@ describe("useMarimoKernelConnection messages", () => {expect(store.get(initialRunCompletedAtom)).toBe(true);});});++it.each(["kernel-ready", "reconnected"])(+ "waits for %s before marking the session connected",+ async (op) => {+ const store = createStore();+ store.set(connectionAtom, { state: WebSocketState.CONNECTING });+ vi.mocked(useConnectionTransport).mockClear();+ vi.mocked(useConnectionTransport).mockReturnValue(+ makeTransport(WebSocket.OPEN),+ );+ vi.mocked(useRuntimeManager).mockReturnValue(+ makeRuntimeManager() as unknown as ReturnType<typeof useRuntimeManager>,+ );+ renderConnectionHook(store);+ const options = vi.mocked(useConnectionTransport).mock.calls.at(-1)![0];++ await act(async () => {+ await options.onOpen(new Event("open"));+ });+ expect(store.get(connectionAtom).state).toBe(WebSocketState.CONNECTING);++ act(() => {+ options.onMessage(+ new MessageEvent("message", {+ data: JSON.stringify({+ op,+ data: {+ op,+ cell_ids: [],+ codes: [],+ names: [],+ configs: [],+ layout: null,+ resumed: true,+ ui_values: {},+ last_executed_code: {},+ last_execution_time: {},+ app_config: { width: "normal" },+ kiosk: false,+ capabilities: { terminal: false },+ auto_instantiated: false,+ consumer_capabilities: { edit: true, interact: true },+ },+ }),+ }),+ );+ });+ expect(store.get(connectionAtom).state).toBe(WebSocketState.OPEN);+ },+);++describe("connection notice", () => {+ beforeEach(() => vi.useFakeTimers());+ afterEach(() => vi.useRealTimers());++ function renderNotice() {+ const store = createStore();+ store.set(connectionAtom, { state: WebSocketState.CONNECTING });+ const transport = makeTransport(WebSocket.OPEN);+ vi.mocked(useConnectionTransport).mockReturnValue(transport);+ vi.mocked(useRuntimeManager).mockReturnValue(+ makeRuntimeManager() as unknown as ReturnType<typeof useRuntimeManager>,+ );+ const Connection = () => {+ const { reconnect } = useMarimoKernelConnection({+ sessionId: "test-session" as SessionId,+ autoInstantiate: false,+ setCells: () => {},+ });+ return (+ <ConnectionNotice+ appConfig={AppConfigSchema.parse({})}+ onRetry={reconnect}+ />+ );+ };+ render(+ <JotaiProvider store={store}>+ <ErrorBoundary fallback={null}>+ <Connection />+ </ErrorBoundary>+ </JotaiProvider>,+ );+ const options = vi.mocked(useConnectionTransport).mock.calls.at(-1)![0];+ const send = (data: NotificationPayload["data"]) =>+ act(() => {+ options.onMessage(+ new MessageEvent("message", {+ data: JSON.stringify({ op: data.op, data }),+ }),+ );+ });+ return { store, transport, options, send };+ }++ it("keeps elapsed time across startup phases and leaves reconnection to the footer once cells are available", () => {+ const { store, options, send } = renderNotice();+ send({ op: "startup-progress", phase: "preparing-environment" });+ expect(+ screen.queryByRole("region", { name: "Notebook startup" }),+ ).not.toBeInTheDocument();+ act(() => vi.advanceTimersByTime(500));+ expect(screen.getByRole("status")).toHaveTextContent(+ "Preparing environment",+ );+ act(() => vi.advanceTimersByTime(35_000));+ expect(screen.getByText("Elapsed 35s")).toBeInTheDocument();+ act(() =>+ store.set(+ notebookAtom,+ MockNotebook.notebookState({+ cellData: { [cellId("test")]: { code: "answer = 42" } },+ }),+ ),+ );+ send({ op: "startup-progress", phase: "starting-kernel" });+ expect(screen.getByRole("status")).toHaveTextContent("Starting notebook");+ expect(screen.getByText("Elapsed 35s")).toBeInTheDocument();+ send({ op: "reconnected" });+ expect(+ screen.queryByRole("region", { name: "Notebook startup" }),+ ).not.toBeInTheDocument();+ act(() => options.onClose(new CloseEvent("close")));+ act(() => vi.advanceTimersByTime(500));+ expect(store.get(connectionAtom)).toEqual({+ state: WebSocketState.CONNECTING,+ phase: "reconnecting",+ });+ expect(+ screen.queryByRole("region", { name: "Notebook startup" }),+ ).not.toBeInTheDocument();+ });++ it("does not flash a notice when startup finishes within the delay", () => {+ const { send } = renderNotice();+ send({ op: "startup-progress", phase: "preparing-environment" });+ act(() => vi.advanceTimersByTime(200));+ send({ op: "startup-progress", phase: "starting-kernel" });+ act(() => vi.advanceTimersByTime(200));+ expect(+ screen.queryByRole("region", { name: "Notebook startup" }),+ ).not.toBeInTheDocument();+ send({ op: "reconnected" });+ act(() => vi.advanceTimersByTime(500));+ expect(+ screen.queryByRole("region", { name: "Notebook startup" }),+ ).not.toBeInTheDocument();+ });++ it.each([+ ["preparing-environment", "Sandbox setup failed"],+ ["starting-kernel", "Kernel failed to start"],+ ] as const)(+ "keeps a %s failure available until the user retries",+ async (phase, title) => {+ const { store, transport, options, send } = renderNotice();+ send({ op: "startup-progress", phase });+ const error = "A full diagnostic\nwith <stderr> details";+ send({ op: "kernel-startup-error", error });+ transport.readyState = WebSocket.CLOSED;+ act(() =>+ options.onClose(+ new CloseEvent("close", { reason: "MARIMO_KERNEL_STARTUP_ERROR" }),+ ),+ );+ expect(screen.getByRole("status")).toHaveTextContent(title);+ act(() => vi.advanceTimersByTime(30_000));+ expect(screen.getByRole("status")).toHaveTextContent(title);+ expect(screen.getByLabelText("Error details")).toHaveTextContent(error, {+ normalizeWhitespace: false,+ });+ expect(transport.reconnect).not.toHaveBeenCalled();+ await act(async () =>+ fireEvent.click(screen.getByRole("button", { name: "Try again" })),+ );+ expect(transport.reconnect).toHaveBeenCalledOnce();+ expect(store.get(kernelStartupErrorAtom)).toBeNull();+ expect(+ screen.queryByRole("button", { name: "Try again" }),+ ).not.toBeInTheDocument();+ send({ op: "startup-progress", phase: "preparing-environment" });+ act(() => vi.advanceTimersByTime(500));+ expect(screen.getByRole("status")).toHaveTextContent(+ "Preparing environment",+ );+ expect(screen.getByText("Elapsed 0s")).toBeInTheDocument();+ },+ );+});diff --git a/frontend/src/core/websocket/types.ts b/frontend/src/core/websocket/types.tsindex 1bb4af0530..5cd37223e2 100644--- a/frontend/src/core/websocket/types.ts+++ b/frontend/src/core/websocket/types.ts@@ -1,5 +1,11 @@/* Copyright 2026 Marimo. All rights reserved. */+import type { NotificationMessageData } from "../kernel/messages";++type ConnectionPhase =+ | NotificationMessageData<"startup-progress">["phase"]+ | "reconnecting";+// TODO: rename to ConnectionStateexport const WebSocketState = {NOT_STARTED: "NOT_STARTED",@@ -28,10 +34,14 @@ export type ConnectionStatus =* Human-readable reason for closing the connection.*/reason: string;+ phase?: ConnectionPhase;+ }+ | {+ state: typeof WebSocketState.CONNECTING;+ phase?: ConnectionPhase;}| {state:- | typeof WebSocketState.CONNECTING| typeof WebSocketState.OPEN| typeof WebSocketState.CLOSING| typeof WebSocketState.NOT_STARTED;diff --git a/frontend/src/core/websocket/useMarimoKernelConnection.tsx b/frontend/src/core/websocket/useMarimoKernelConnection.tsxindex 36b638f7ec..8f4e8a3f5c 100644--- a/frontend/src/core/websocket/useMarimoKernelConnection.tsx+++ b/frontend/src/core/websocket/useMarimoKernelConnection.tsx@@ -1,5 +1,6 @@/* Copyright 2026 Marimo. All rights reserved. */+import { invalidatePackageData } from "@/core/packages/package-data";import { useAtom, useAtomValue, useSetAtom } from "jotai";import { useRef } from "react";import { useErrorBoundary } from "react-error-boundary";@@ -240,7 +241,15 @@ export function useMarimoKernelConnection(opts: {case "reload":reloadSafe();return;+ case "startup-progress":+ setConnection({+ state: WebSocketState.CONNECTING,+ phase: msg.data.phase,+ });+ return;case "kernel-ready": {+ setKernelStartupError(null);+ setConnection({ state: WebSocketState.OPEN });setInitialRunCompleted(Boolean(msg.data.resumed || msg.data.auto_instantiated),);@@ -363,6 +372,16 @@ export function useMarimoKernelConnection(opts: {});return;case "installing-package-alert":+ if (+ msg.data.source !== "server" &&+ msg.data.log_status !== "append" &&+ msg.data.log_status !== "start" &&+ Object.values(msg.data.packages).some(+ (status) => status === "installed" || status === "restart-required",+ )+ ) {+ invalidatePackageData();+ }addPackageAlert({...msg.data,kind: "installing",@@ -439,6 +458,8 @@ export function useMarimoKernelConnection(opts: {return;case "reconnected":+ setKernelStartupError(null);+ setConnection({ state: WebSocketState.OPEN });return;case "focus-cell":@@ -482,6 +503,7 @@ export function useMarimoKernelConnection(opts: {return;}shouldTryReconnecting.current = true;+ setKernelStartupError(null);setConnection({ state: WebSocketState.CONNECTING });const healthy = await runtimeManager.reconcileFromHealth();if (!healthy) {@@ -513,17 +535,11 @@ export function useMarimoKernelConnection(opts: {headers: () => runtimeManager.headers(),/**- * Open callback. Set the connection status to open.+ * The transport is open; kernel-ready establishes session readiness.*/onOpen: async () => {// If we are open, we can reset our reconnecting flag.shouldTryReconnecting.current = true;-- // DO NOT COMMIT THIS UNCOMMENTED- // Uncomment to emulate a slow connection- // await new Promise((resolve) => setTimeout(resolve, 10_000));-- setConnection({ state: WebSocketState.OPEN });},/**@@ -565,7 +581,26 @@ export function useMarimoKernelConnection(opts: {onClose: (e) => {Logger.warn("WebSocket closed", e.code, e.reason);const decision = classifyCloseEvent(e);- setConnection(decision.status);+ setConnection((previous) => {+ const status = decision.status;+ if (+ status.state === WebSocketState.CLOSED &&+ status.code === WebSocketClosedReason.KERNEL_STARTUP_ERROR &&+ (previous.state === WebSocketState.CONNECTING ||+ previous.state === WebSocketState.CLOSED)+ ) {+ return { ...status, phase: previous.phase };+ }+ if (+ status.state === WebSocketState.CONNECTING &&+ (previous.state === WebSocketState.OPEN ||+ (previous.state === WebSocketState.CONNECTING &&+ previous.phase === "reconnecting"))+ ) {+ return { ...status, phase: "reconnecting" };+ }+ return status;+ });if (decision.kind === "terminal" && decision.closeTransport) {ws.close(); // close to prevent reconnectingreturn;diff --git a/frontend/src/stories/sandbox.stories.tsx b/frontend/src/stories/sandbox.stories.tsxnew file mode 100644index 0000000000..d13f596837--- /dev/null+++ b/frontend/src/stories/sandbox.stories.tsx@@ -0,0 +1,308 @@+/* Copyright 2026 Marimo. All rights reserved. */+import type { Meta, StoryObj } from "@storybook/react-vite";+import { createStore, Provider, useAtomValue } from "jotai";+import { useEffect, useRef, useState } from "react";+import { ConnectionNotice } from "@/components/editor/alerts/connection-notice";+import {+ SandboxFooter,+ SandboxStartupPanel,+} from "@/components/editor/chrome/panels/sandbox-panel";+import { SandboxController } from "@/components/editor/chrome/panels/sandbox-controller";+import { chromeAtom } from "@/components/editor/chrome/state";+import { Cell } from "@/components/editor/notebook-cell";+import { VerticalLayoutWrapper } from "@/components/editor/renderers/vertical-layout/vertical-layout-wrapper";+import {+ createNotebookActions,+ notebookAtom,+ notebookReducer,+} from "@/core/cells/cells";+import { userConfigAtom } from "@/core/config/config";+import {+ AppConfigSchema,+ defaultUserConfig,+} from "@/core/config/config-schema";+import { kernelStartupErrorAtom } from "@/core/errors/state";+import { connectionAtom } from "@/core/network/connection";+import { requestClientAtom } from "@/core/network/requests";+import { createStaticRequests } from "@/core/network/requests-static";+import {+ sandboxActionsAtom,+ sandboxAtom,+ sandboxSyncAtom,+} from "@/core/packages/sandbox-state";+import { filenameAtom } from "@/core/saving/file-state";+import { WebSocketClosedReason, WebSocketState } from "@/core/websocket/types";+import { HTTPError } from "@/utils/errors";++const manifest = `requires-python = ">=3.13"+dependencies = ["marimo", "polars", "rich==999.0.0"]++[tool.uv]+index-url = "https://pypi.org/simple"++[tool.notebook]+description = "Explore bike trips"+`;+const resolutionError = `No solution found when resolving dependencies:+ Because there is no version of rich==999.0.0 and your script depends+ on rich==999.0.0, your script's requirements are unsatisfiable.`;++interface Props {+ surface: "notebook" | "packages" | "manifest";+ phase:+ | "preparing"+ | "starting"+ | "failed"+ | "ready"+ | "syncing"+ | "sync-failed";+ existingCells: boolean;+ backend: "uv" | "pixi";+ saveResult: "success" | "failure" | "stale";+ theme: "light" | "dark";+}++function OpenManifest() {+ const actions = useAtomValue(sandboxActionsAtom);+ const opened = useRef(false);+ useEffect(() => {+ if (actions && !opened.current) {+ opened.current = true;+ void actions.editManifest();+ }+ }, [actions]);+ return null;+}++function SandboxStory(props: Props) {+ const [store] = useState(() => {+ const state = createStore();+ let currentManifest =+ props.phase === "failed"+ ? manifest+ : manifest.replace("rich==999.0.0", "rich>=13.0.0");+ const config = defaultUserConfig();+ state.set(userConfigAtom, {+ ...config,+ display: { ...config.display, theme: props.theme },+ });+ state.set(filenameAtom, "bike_trips.py");+ state.set(sandboxAtom, {+ backend: props.backend,+ manifest: currentManifest,+ filename: "bike_trips.py",+ });+ state.set(chromeAtom, {+ selectedPanel: "packages",+ isSidebarOpen: props.surface !== "notebook",+ isDeveloperPanelOpen: false,+ selectedDeveloperPanelTab: "errors",+ });+ state.set(+ connectionAtom,+ props.phase === "preparing" || props.phase === "starting"+ ? {+ state: WebSocketState.CONNECTING,+ phase:+ props.phase === "preparing"+ ? "preparing-environment"+ : "starting-kernel",+ }+ : props.phase === "failed"+ ? {+ state: WebSocketState.CLOSED,+ code: WebSocketClosedReason.KERNEL_STARTUP_ERROR,+ reason: "Kernel startup failed",+ phase: "preparing-environment",+ }+ : { state: WebSocketState.OPEN },+ );+ state.set(+ kernelStartupErrorAtom,+ props.phase === "failed" ? resolutionError : null,+ );+ state.set(sandboxSyncAtom, {+ pending: props.phase === "syncing",+ error: props.phase === "sync-failed" ? resolutionError : null,+ });+ if (props.existingCells) {+ const actions = createNotebookActions((action) =>+ state.set(notebookAtom, (value) => notebookReducer(value, action)),+ );+ actions.createNewCell({+ cellId: "__end__",+ before: false,+ code: 'import polars as pl\n\ntrips = pl.read_csv("bike_trips.csv")\ntrips.head()',+ autoFocus: false,+ });+ }+ state.set(requestClientAtom, {+ ...createStaticRequests(),+ getSandbox: async () => ({+ backend: props.backend,+ manifest: currentManifest,+ filename: "bike_trips.py",+ }),+ updateManifest: async ({ contents }) => {+ if (props.saveResult === "stale") {+ throw new HTTPError(+ 409,+ "The manifest changed on disk. Reopen it before saving.",+ );+ }+ currentManifest = contents;+ return {+ backend: props.backend,+ manifest: currentManifest,+ filename: "bike_trips.py",+ };+ },+ syncSandbox: async () => {+ await new Promise((resolve) => setTimeout(resolve, 2000));+ if (props.saveResult === "failure") {+ return {+ success: false,+ error:+ "Failed to download rich from https://pypi.org/simple/rich/\n Request failed after 3 retries: connection timed out",+ restartRequired: false,+ reconnect: false,+ };+ }+ state.set(connectionAtom, { state: WebSocketState.OPEN });+ state.set(kernelStartupErrorAtom, null);+ return {+ success: true,+ error: null,+ restartRequired: false,+ reconnect: false,+ };+ },+ });+ return state;+ });+ const appConfig = AppConfigSchema.parse({ width: "full" });+ const reconnect = async () => {+ store.set(connectionAtom, { state: WebSocketState.OPEN });+ };+ return (+ <Provider store={store}>+ <SandboxController onReconnect={reconnect} />+ {props.surface === "manifest" && <OpenManifest />}+ <div+ data-testid="sandbox-story"+ className="bg-background text-foreground"+ style={{+ width: props.surface === "notebook" ? 820 : 400,+ }}+ >+ {props.surface === "notebook" && (+ <>+ <ConnectionNotice appConfig={appConfig} onRetry={reconnect} />+ {store.get(notebookAtom).cellIds.inOrderIds.map((cellId) => (+ <VerticalLayoutWrapper key={cellId} appConfig={appConfig}>+ <Cell+ cellId={cellId}+ theme={props.theme}+ mode="edit"+ showPlaceholder={false}+ canDelete={true}+ isCollapsed={false}+ collapseCount={0}+ canMoveX={false}+ userConfig={store.get(userConfigAtom)}+ />+ </VerticalLayoutWrapper>+ ))}+ </>+ )}+ {props.surface === "packages" &&+ (props.phase === "failed" ||+ props.phase === "sync-failed" ||+ props.phase === "preparing" ? (+ <SandboxStartupPanel />+ ) : (+ <SandboxFooter />+ ))}+ </div>+ </Provider>+ );+}++const meta = {+ title: "Sandbox/States",+ component: SandboxStory,+ parameters: { layout: "centered" },+ args: {+ surface: "notebook",+ phase: "preparing",+ existingCells: true,+ backend: "uv",+ saveResult: "success",+ theme: "light",+ },+ render: (args, context) => (+ <SandboxStory+ key={JSON.stringify([args, context.globals.theme])}+ {...args}+ theme={context.globals.theme === "dark" ? "dark" : "light"}+ />+ ),+} satisfies Meta<typeof SandboxStory>;+export default meta;+type Story = StoryObj<typeof meta>;++export const ExistingNotebookPreparing: Story = {+ name: "Startup notice / preparing",+};+export const EmptyNotebookPreparing: Story = {+ name: "Empty notebook / preparing",+ args: { existingCells: false },+};+export const StartingKernel: Story = {+ name: "Startup notice / starting kernel",+ args: { phase: "starting" },+};+export const ExistingNotebookFailed: Story = {+ name: "Startup notice / failed",+ args: { phase: "failed" },+};+export const EmptyNotebookFailed: Story = {+ name: "Empty notebook / failed",+ args: { phase: "failed", existingCells: false },+};+export const PackagesPreparing: Story = {+ name: "Setup details / preparing",+ args: { surface: "packages" },+};+export const PackagesFailed: Story = {+ name: "Setup details / failed",+ args: { surface: "packages", phase: "failed" },+};+export const PackagesReady: Story = {+ name: "Status row / ready",+ args: { surface: "packages", phase: "ready" },+};+export const PackagesSyncing: Story = {+ name: "Status row / syncing",+ args: { surface: "packages", phase: "syncing" },+};+export const PackagesSyncFailed: Story = {+ name: "Setup details / sync failed",+ args: { surface: "packages", phase: "sync-failed" },+};+export const PixiPackagesReady: Story = {+ name: "Status row / pixi",+ args: { surface: "packages", phase: "ready", backend: "pixi" },+};+export const ManifestEditor: Story = {+ name: "Manifest / edit",+ args: { surface: "manifest", phase: "failed" },+};+export const ManifestSyncFails: Story = {+ name: "Manifest / failed save",+ args: { surface: "manifest", phase: "failed", saveResult: "failure" },+};+export const ManifestChangedOnDisk: Story = {+ name: "Manifest / changed on disk",+ args: { surface: "manifest", phase: "failed", saveResult: "stale" },+};diff --git a/marimo/_cli/cli.py b/marimo/_cli/cli.pyindex a37e99881d..84bae8a51b 100644--- a/marimo/_cli/cli.py+++ b/marimo/_cli/cli.py@@ -26,7 +26,7 @@ from marimo._cli.errors import ()from marimo._cli.export.commands import exportfrom marimo._cli.files.file_path import validate_name-from marimo._cli.help_formatter import ColoredCommand, ColoredGroup, RunCommand+from marimo._cli.help_formatter import ColoredGroup, SandboxCommandfrom marimo._cli.pair.commands import pairfrom marimo._cli.parse_args import parse_argsfrom marimo._cli.parser_ux import show_compact_usage_error@@ -283,36 +283,7 @@ class _OptionalValueOption(click.Option):self.flag_value = opt_flag_value-def _normalize_sandbox_args(args: list[str]) -> list[str]:- """Give a bare `--sandbox` its backwards-compatible uv value.-- Click options cannot reliably accept both an optional value and a- following positional argument. Normalize the bare spelling before Click- parses it. Explicit backends use `--sandbox=pixi`; following paths named- `uv` or `pixi` and arguments after `--` remain positional arguments.- """- normalized = list(args)- try:- limit = normalized.index("--")- except ValueError:- limit = len(normalized)- for index, token in enumerate(normalized[:limit]):- if token == "--sandbox":- normalized[index] = "--sandbox=uv"- return normalized---class _SandboxCommand(ColoredCommand):- def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:- return super().parse_args(ctx, _normalize_sandbox_args(args))---class _SandboxRunCommand(RunCommand):- def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:- return super().parse_args(ctx, _normalize_sandbox_args(args))--[email protected](cls=_SandboxCommand, help=edit_help_msg)[email protected](cls=SandboxCommand, help=edit_help_msg)@click.option("-p","--port",@@ -505,8 +476,9 @@ def edit(name: str | None,args: tuple[str, ...],) -> None:- from marimo._cli.sandbox import SandboxMode, resolve_sandbox+ from marimo._cli.sandbox import ensure_server_environment, resolve_sandbox+ stdin_notebook = Nonepass_on_stdin = token_password_file == "-"# We support unix-style piping, e.g. cat notebook.py | marimo editif (@@ -519,6 +491,7 @@ def edit("notebook.py", "py", stdin_contents, temp_dir)name = path.absolute_name+ stdin_notebook = nameif prompt_run_in_docker_container(name, trusted=trusted):from marimo._cli.run_docker import run_in_docker@@ -568,33 +541,10 @@ def edit(# We check this after name validation, because this will convert# URLs into local file paths- # Resolve sandbox mode: None, SandboxMode.SINGLE, or SandboxMode.MULTI- sandbox_mode, sandbox_backend = resolve_sandbox(+ sandbox_backend = resolve_sandbox(sandbox=sandbox, no_sandbox=no_sandbox, name=name)-- # Single-file sandbox: the server runs from the script environment- if sandbox_mode is SandboxMode.SINGLE:- from marimo._cli.sandbox import run_in_sandbox-- sys.exit(- run_in_sandbox(- sys.argv[1:],- name=name,- extras=["lsp"],- backend=sandbox_backend,- )- )-- # Multi-file sandbox: use IPC kernels with per-notebook sandboxed venvs- if sandbox_mode is SandboxMode.MULTI:- # Enable script metadata management for sandboxed notebooks- os.environ["MARIMO_MANAGE_SCRIPT_METADATA"] = "true"- GLOBAL_SETTINGS.MANAGE_SCRIPT_METADATA = True- os.environ["MARIMO_SANDBOX_MODE"] = "multi"- GLOBAL_SETTINGS.SANDBOX_MODE = "multi"- os.environ["MARIMO_SANDBOX_BACKEND"] = sandbox_backend- GLOBAL_SETTINGS.SANDBOX_BACKEND = sandbox_backend+ ensure_server_environment(sandbox_backend, stdin_notebook=stdin_notebook)# Check shared memory availability early (required for edit mode to# communicate between the server process and kernel subprocess)@@ -654,7 +604,7 @@ def edit(server_startup_command=server_startup_command,asset_url=asset_url,timeout=timeout,- sandbox_mode=sandbox_mode,+ sandbox=sandbox_backend,startup_tip=choose_startup_tip(click.get_current_context()),)@@ -693,7 +643,7 @@ new_help_msg = "\n".join()[email protected](cls=_SandboxCommand, help=new_help_msg)[email protected](cls=SandboxCommand, help=new_help_msg)@click.option("-p","--port",@@ -788,18 +738,10 @@ def new(timeout: float | None,prompt: str | None,) -> None:- if sandbox and not no_sandbox:- from marimo._cli.sandbox import backend_from_flag, run_in_sandbox+ from marimo._cli.sandbox import ensure_server_environment, resolve_sandbox- # TODO: consider adding recommended as well- sys.exit(- run_in_sandbox(- sys.argv[1:],- name=None,- extras=["lsp"],- backend=backend_from_flag(sandbox),- )- )+ sandbox_backend = resolve_sandbox(sandbox, no_sandbox, name=None)+ ensure_server_environment(sandbox_backend)workspace: NotebookWorkspace | None = None@@ -877,6 +819,7 @@ def new(redirect_console_to_browser=True,ttl_seconds=None,timeout=timeout,+ sandbox=sandbox_backend,startup_tip=choose_startup_tip(click.get_current_context()),)@@ -1008,7 +951,7 @@ def _create_run_workspace(@main.command(- cls=_SandboxRunCommand,+ cls=SandboxCommand,help="""Run a notebook as an app in read-only mode.If NAME is a url, the notebook will be downloaded to a temporary file.@@ -1206,8 +1149,6 @@ def run(args: tuple[str, ...],) -> None:from marimo._cli.sandbox import (- SandboxMode,- backend_from_flag,resolve_sandbox,run_in_sandbox,)@@ -1285,31 +1226,17 @@ def run(# We check this after name validation, because this will convert# URLs into local file paths- if is_multi:- # Gallery mode: use MULTI sandbox (IPC kernels) or None- sandbox_mode = (- SandboxMode.MULTI if sandbox and not no_sandbox else None- )- sandbox_backend = backend_from_flag(sandbox)- else:- sandbox_mode, sandbox_backend = resolve_sandbox(- sandbox=sandbox, no_sandbox=no_sandbox, name=validated_paths[0]- )- if sandbox_mode is SandboxMode.SINGLE:- sys.exit(- run_in_sandbox(- sys.argv[1:],- name=validated_paths[0],- backend=sandbox_backend,- )+ sandbox_backend = resolve_sandbox(+ sandbox, no_sandbox, None if is_multi else validated_paths[0]+ )+ if sandbox_backend and not is_multi:+ sys.exit(+ run_in_sandbox(+ sys.argv[1:],+ name=validated_paths[0],+ backend=sandbox_backend,)-- # Multi-file sandbox: use IPC kernels with per-notebook sandboxed venvs- if sandbox_mode is SandboxMode.MULTI:- # Kernel launches read the backend from the global; without- # this, `marimo run --sandbox=pixi` would launch uv kernels.- os.environ["MARIMO_SANDBOX_BACKEND"] = sandbox_backend- GLOBAL_SETTINGS.SANDBOX_BACKEND = sandbox_backend+ )workspace = _create_run_workspace(validated_paths, watch=watch)@@ -1340,7 +1267,7 @@ def run(redirect_console_to_browser=redirect_console_to_browser,server_startup_command=server_startup_command,asset_url=asset_url,- sandbox_mode=sandbox_mode,+ sandbox=sandbox_backend,startup_tip=choose_startup_tip(click.get_current_context()),show_tracebacks=show_tracebacks,execute_opengraph_generators=execute_opengraph_generators,diff --git a/marimo/_cli/development/commands.py b/marimo/_cli/development/commands.pyindex 3af1014882..adab26d3d8 100644--- a/marimo/_cli/development/commands.py+++ b/marimo/_cli/development/commands.py@@ -391,6 +391,10 @@ def _generate_server_api_schema() -> dict[str, Any]:packages.PackageOperationResponse,packages.RemovePackageRequest,packages.DependencyTreeResponse,+ packages.SandboxRequest,+ packages.SandboxResponse,+ packages.UpdateManifestRequest,+ packages.SyncSandboxResponse,lsp.LspHealthResponse,lsp.LspRestartRequest,lsp.LspRestartResponse,diff --git a/marimo/_cli/export/_common.py b/marimo/_cli/export/_common.pyindex ff57efea9e..b9b8bf074e 100644--- a/marimo/_cli/export/_common.py+++ b/marimo/_cli/export/_common.py@@ -4,28 +4,22 @@ from __future__ import annotationsimport contextlibimport jsonimport signal-import subprocessimport threading-from dataclasses import dataclassfrom pathlib import Pathfrom typing import TYPE_CHECKING, Anyimport click+from marimo._environments.process import run_commandfrom marimo._server.files.directory_scanner import DirectoryScannerfrom marimo._server.workspace import flatten_filesfrom marimo._utils.http import HTTPException, HTTPStatusfrom marimo._utils.marimo_path import MarimoPath-from marimo._utils.subprocess import kill_subprocessif TYPE_CHECKING:from collections.abc import Iterable, Iterator- from marimo._environments.environment import Environment---def is_multi_target(paths: list[Path]) -> bool:- return len(paths) > 1 or any(path.is_dir() for path in paths)+ from marimo._environments.sandbox import Backenddef collect_notebooks(paths: Iterable[Path]) -> list[MarimoPath]:@@ -52,46 +46,6 @@ def collect_notebooks(paths: Iterable[Path]) -> list[MarimoPath]:return [notebooks[k] for k in sorted(notebooks)]-@dataclass(frozen=True)-class SandboxTarget:- """Where a sandboxed export runs.-- `environment` is the notebook's script environment, or None for a- notebook without a metadata block, which runs ephemerally.- """-- environment: Environment | None---class SandboxVenvPool:- """Caches synchronized script environments by notebook path."""-- def __init__(self) -> None:- self._targets: dict[str, SandboxTarget] = {}-- def get_target(self, notebook_path: str) -> SandboxTarget:- from marimo._environments.backends import sync_notebook- from marimo._environments.uv import UvMissingScriptMetadataError-- key = str(Path(notebook_path).resolve())- existing = self._targets.get(key)- if existing is not None:- return existing-- try:- target = SandboxTarget(- environment=sync_notebook(key, backend="uv")- )- except UvMissingScriptMetadataError:- target = SandboxTarget(environment=None)- self._targets[key] = target- return target-- def close(self) -> None:- # uv owns the environments; there is nothing to remove.- self._targets.clear()--@contextlib.contextmanagerdef _export_termination_signals() -> Iterator[None]:"""Let termination unwind the runner so its isolated child is reaped."""@@ -115,39 +69,40 @@ def _export_termination_signals() -> Iterator[None]:signal.signal(signum, handler)-def run_python_subprocess(+async def run_python_subprocess(*,- sandbox: SandboxTarget,+ notebook_path: str,+ backend: Backend,script: str,payload: dict[str, Any],action: str,) -> str:- from marimo._environments.backends import launch_fallback- from marimo._environments.environment import launch+ from marimo._environments.backends import (+ launch,+ launch_fallback,+ sync_notebook_async,+ )+ from marimo._environments.errors import MissingScriptMetadataErrorfrom marimo._environments.overlay import runtime_overlayargs = ["-c", script, json.dumps(payload)]- if sandbox.environment is not None:- plan = launch(sandbox.environment, args, overlay=runtime_overlay())- else:- plan = launch_fallback(args)- with (- _export_termination_signals(),- subprocess.Popen(- list(plan.argv),- env=plan.env,- start_new_session=plan.start_new_session,- stdout=subprocess.PIPE,- stderr=subprocess.PIPE,- text=True,- ) as process,- ):+ with _export_termination_signals():try:- stdout, stderr = process.communicate()- except BaseException:- kill_subprocess(process, start_new_session=plan.start_new_session)- raise- if process.returncode != 0:+ environment = await sync_notebook_async(+ str(Path(notebook_path).resolve()), # noqa: ASYNC240+ backend=backend,+ )+ except MissingScriptMetadataError:+ plan = launch_fallback(args)+ else:+ plan = launch(+ environment, args, backend=backend, overlay=runtime_overlay()+ )+ completed = await run_command(+ plan.argv,+ env=plan.env,+ )+ if completed.returncode != 0:# Identify the real launcher without exposing requirement URLs,# credentials, notebook code, or the serialized request payload.launcher = Path(plan.argv[0]).name@@ -155,6 +110,6 @@ def run_python_subprocess(raise click.ClickException(f"Failed to {action} in sandbox.\n\n"f"Command:\n\n {command}\n\n"- f"Stderr:\n\n{stderr.strip()}"+ f"Stderr:\n\n{completed.stderr.strip()}")- return stdout+ return completed.stdoutdiff --git a/marimo/_cli/export/session.py b/marimo/_cli/export/session.pyindex 8a017324da..1c1eccf79f 100644--- a/marimo/_cli/export/session.py+++ b/marimo/_cli/export/session.py@@ -1,25 +1,20 @@# Copyright 2026 Marimo. All rights reserved.from __future__ import annotations-import asyncioimport json-import sysfrom pathlib import Pathfrom typing import TYPE_CHECKING, Any, castimport click-from marimo._cli.errors import MarimoCLIMissingDependencyErrorfrom marimo._cli.export._common import (- SandboxTarget,- SandboxVenvPool,collect_notebooks,- is_multi_target,run_python_subprocess,)+from marimo._cli.help_formatter import SandboxCommandfrom marimo._cli.parse_args import parse_argsfrom marimo._cli.print import echo, green, red, yellow-from marimo._dependencies.dependencies import DependencyManager+from marimo._cli.sandbox import resolve_sandboxfrom marimo._export._session_cache import (is_session_snapshot_stale,serialize_session_snapshot,@@ -37,37 +32,22 @@ from marimo._session.state.serialize import get_session_cache_filefrom marimo._utils.marimo_path import MarimoPathif TYPE_CHECKING:- from marimo._cli.sandbox import SandboxMode+ from marimo._environments.sandbox import Backend+_sandbox_message = (- "Run the command in an isolated virtual environment using "- "`uv run --isolated`. Requires `uv`."+ "Execute each notebook in an isolated environment with its inline "+ "dependencies. Use --sandbox (uv), --sandbox=uv, or --sandbox=pixi.")-def _resolve_session_sandbox_mode(- *,- sandbox: bool | None,- path_targets: list[Path],- first_target: str,-) -> SandboxMode | None:- from marimo._cli.sandbox import SandboxMode, resolve_sandbox_mode-- if is_multi_target(path_targets):- if sandbox is None:- return None- return SandboxMode.MULTI if sandbox else None-- return resolve_sandbox_mode(sandbox=sandbox, name=first_target)--async def _export_session_snapshot(marimo_path: MarimoPath,*,notebook_args: tuple[str, ...],- sandbox: SandboxTarget | None = None,+ sandbox: Backend | None = None,) -> tuple[NotebookSessionV1, bool]:- if sandbox is None:+ if not sandbox:cli_args = parse_args(notebook_args) if notebook_args else {}file_manager = load_notebook(marimo_path.absolute_name)@@ -94,15 +74,12 @@ async def _export_session_snapshot("path": marimo_path.absolute_name,"args": list(notebook_args),}- return await asyncio.to_thread(- _export_session_snapshot_in_subprocess,- sandbox,- payload,- )+ return await _export_session_snapshot_in_subprocess(payload, sandbox)-def _export_session_snapshot_in_subprocess(- sandbox: SandboxTarget, payload: dict[str, Any]+async def _export_session_snapshot_in_subprocess(+ payload: dict[str, Any],+ backend: Backend,) -> tuple[NotebookSessionV1, bool]:script = r"""import asyncio@@ -155,8 +132,9 @@ sys.stdout.write()"""- output = run_python_subprocess(- sandbox=sandbox,+ output = await run_python_subprocess(+ notebook_path=payload["path"],+ backend=backend,script=script,payload=payload,action="export session",@@ -185,18 +163,12 @@ async def _export_session_for_notebook(*,force_overwrite: bool,notebook_args: tuple[str, ...],- sandbox_pool: SandboxVenvPool | None,+ sandbox: Backend | None,) -> None:- output = get_session_cache_file(notebook.path)if _maybe_skip_fresh_snapshot(notebook, force_overwrite=force_overwrite):returnecho(f"Running {notebook.short_name}...")- sandbox = (- sandbox_pool.get_target(str(notebook.path))- if sandbox_pool is not None- else None- )session_snapshot, did_error = await _export_session_snapshot(notebook,@@ -239,41 +211,23 @@ async def _export_sessions(force_overwrite: bool,notebook_args: tuple[str, ...],continue_on_error: bool,- sandbox_mode: SandboxMode | None,+ sandbox: Backend | None,) -> None:- from marimo._cli.sandbox import SandboxMode-failures: list[tuple[MarimoPath, Exception]] = []- use_per_notebook_sandbox = sandbox_mode is SandboxMode.MULTI-- if use_per_notebook_sandbox and not DependencyManager.which("uv"):- raise MarimoCLIMissingDependencyError(- "uv is required for --sandbox session export.",- "uv",- additional_tip="Install uv from https://github.com/astral-sh/uv",- )- sandbox_pool: SandboxVenvPool | None = (- SandboxVenvPool() if use_per_notebook_sandbox else None- )-- try:- for notebook in notebooks:- try:- await _export_session_for_notebook(- notebook,- force_overwrite=force_overwrite,- notebook_args=notebook_args,- sandbox_pool=sandbox_pool,- )- except Exception as error:- failures.append((notebook, error))- echo(red("error") + f": {notebook.short_name}: {error}")- if not continue_on_error:- raise- finally:- if sandbox_pool is not None:- sandbox_pool.close()+ for notebook in notebooks:+ try:+ await _export_session_for_notebook(+ notebook,+ force_overwrite=force_overwrite,+ notebook_args=notebook_args,+ sandbox=sandbox,+ )+ except Exception as error:+ failures.append((notebook, error))+ echo(red("error") + f": {notebook.short_name}: {error}")+ if not continue_on_error:+ raiseif failures:raise click.ClickException(@@ -283,6 +237,7 @@ async def _export_sessions(@click.command("session",+ cls=SandboxCommand,help=("Execute a notebook or directory of notebooks and export session snapshots."),@@ -294,12 +249,17 @@ async def _export_sessions(),)@click.option(- "--sandbox/--no-sandbox",- is_flag=True,+ "--sandbox",default=None,- type=bool,+ type=click.Choice(["uv", "pixi"]),help=_sandbox_message,)+ "--no-sandbox",+ is_flag=True,+ default=False,+ help="Never run in a sandbox, and never prompt to.",+)@click.option("--force-overwrite/--no-force-overwrite",default=False,@@ -316,7 +276,8 @@ async def _export_sessions(@click.argument("args", nargs=-1, type=click.UNPROCESSED)def session(name: Path,- sandbox: bool | None,+ sandbox: str | None,+ no_sandbox: bool,force_overwrite: bool,continue_on_error: bool,args: tuple[str, ...],@@ -327,28 +288,12 @@ def session(if not notebooks:raise click.ClickException("No marimo notebooks found.")- sandbox_mode = _resolve_session_sandbox_mode(- sandbox=sandbox,- path_targets=path_targets,- first_target=str(name),- )-- from marimo._cli.sandbox import SandboxMode, run_in_sandbox-- if sandbox_mode is SandboxMode.SINGLE:- notebook = notebooks[0]- if _maybe_skip_fresh_snapshot(- notebook, force_overwrite=force_overwrite- ):- return- sys.exit(run_in_sandbox(sys.argv[1:], name=str(name)))-asyncio_run(_export_sessions(notebooks=notebooks,force_overwrite=force_overwrite,notebook_args=args,continue_on_error=continue_on_error,- sandbox_mode=sandbox_mode,+ sandbox=resolve_sandbox(sandbox, no_sandbox, str(name)),))diff --git a/marimo/_cli/export/thumbnail.py b/marimo/_cli/export/thumbnail.pyindex a33d349843..4eddeb6ccb 100644--- a/marimo/_cli/export/thumbnail.py+++ b/marimo/_cli/export/thumbnail.py@@ -1,7 +1,6 @@# Copyright 2026 Marimo. All rights reserved.from __future__ import annotations-import asyncioimport osimport sysfrom pathlib import Path@@ -11,17 +10,23 @@ import clickfrom marimo._cli.errors import MarimoCLIMissingDependencyErrorfrom marimo._cli.export._common import (- SandboxTarget,- SandboxVenvPool,collect_notebooks,- is_multi_target,run_python_subprocess,)from marimo._cli.export.output import STDERR+from marimo._cli.help_formatter import SandboxCommandfrom marimo._cli.install_hints import get_playwright_chromium_setup_commandsfrom marimo._cli.parse_args import parse_argsfrom marimo._cli.print import echo, green, red, yellow+from marimo._cli.sandbox import (+ _strip_sandbox_args,+ _wait_on_plan,+ require_sandbox_backend,+ resolve_sandbox,+)from marimo._dependencies.dependencies import DependencyManager+from marimo._environments.backends import launch_isolated+from marimo._environments.overlay import runtime_overlayfrom marimo._export._html_asset_server import HtmlAssetServerfrom marimo._export.file import export_htmlfrom marimo._export.requests import (@@ -34,88 +39,17 @@ from marimo._utils.marimo_path import MarimoPathfrom marimo._utils.paths import marimo_package_path, maybe_make_dirsif TYPE_CHECKING:- from marimo._cli.sandbox import SandboxMode+ from marimo._environments.sandbox import Backend_sandbox_message = ("Render notebooks in an isolated environment, with dependencies tracked ""via PEP 723 inline metadata. If already declared, dependencies will "- "install automatically. Requires uv. Only applies when --execute is used."+ "install automatically. Use --sandbox (uv), --sandbox=uv, or "+ "--sandbox=pixi. Only applies when --execute is used.")_READINESS_WAIT_TIMEOUT_MS = 30_000_sandbox_bootstrapped_env = "MARIMO_THUMBNAIL_SANDBOX_BOOTSTRAPPED"-_sandbox_mode_env = "MARIMO_THUMBNAIL_SANDBOX_MODE"-_thumbnail_sandbox_deps = ["playwright"]---def _split_paths_and_args(- name: str, args: tuple[str, ...]-) -> tuple[list[str], tuple[str, ...]]:- paths = [name]- for index, arg in enumerate(args):- if arg == "--":- return paths, args[index + 1 :]- paths.append(arg)- return paths, ()---def _sandbox_mode_from_env() -> SandboxMode | None:- from marimo._cli.sandbox import SandboxMode-- if os.environ.get(_sandbox_bootstrapped_env) != "1":- return None-- mode = os.environ.get(_sandbox_mode_env)- if mode == SandboxMode.SINGLE.value:- return SandboxMode.SINGLE- if mode == SandboxMode.MULTI.value:- return SandboxMode.MULTI- return None---def _resolve_thumbnail_sandbox_mode(- *,- execute: bool,- sandbox: bool | None,- path_targets: list[Path],- first_target: str,-) -> SandboxMode | None:- from marimo._cli.sandbox import SandboxMode, resolve_sandbox_mode-- if not execute:- return None-- env_mode = _sandbox_mode_from_env()- if env_mode is not None:- return env_mode-- if is_multi_target(path_targets):- if sandbox is None:- return None- return SandboxMode.MULTI if sandbox else None-- return resolve_sandbox_mode(sandbox=sandbox, name=first_target)---def _bootstrap_thumbnail_sandbox(- *,- args: list[str],- name: str,- sandbox_mode: SandboxMode,-) -> None:- from marimo._cli.sandbox import run_in_sandbox-- sys.exit(- run_in_sandbox(- args,- name=name,- command_deps=_thumbnail_sandbox_deps,- extra_env={- _sandbox_bootstrapped_env: "1",- _sandbox_mode_env: sandbox_mode.value,- },- )- )async def _render_html(@@ -125,7 +59,7 @@ async def _render_html(include_code: bool,args: tuple[str, ...],asset_url: str | None = None,- sandbox: SandboxTarget | None = None,+ sandbox: Backend | None = None,) -> str:if not execute:result = await export_html(@@ -140,7 +74,7 @@ async def _render_html()return result.text- if sandbox is None:+ if not sandbox:cli_args = parse_args(args) if args else {}result = await export_html(HTMLFileExportRequest(@@ -167,15 +101,11 @@ async def _render_html(}# Render in a separate process so we can use a sandboxed venv without polluting the current environment.- return await asyncio.to_thread(- _render_html_in_subprocess,- sandbox,- payload,- )+ return await _render_html_in_subprocess(payload, sandbox)-def _render_html_in_subprocess(- sandbox: SandboxTarget, payload: dict[str, Any]+async def _render_html_in_subprocess(+ payload: dict[str, Any], backend: Backend) -> str:"""Render a notebook to HTML in a separate Python process."""script = r"""@@ -218,8 +148,9 @@ result = asyncio.run(sys.stdout.write(result.text)"""- return run_python_subprocess(- sandbox=sandbox,+ return await run_python_subprocess(+ notebook_path=payload["path"],+ backend=backend,script=script,payload=payload,action="render notebook",@@ -239,9 +170,8 @@ async def _generate_thumbnails(execute: bool,notebook_args: tuple[str, ...],continue_on_error: bool,- sandbox_mode: SandboxMode | None,+ sandbox: Backend | None,) -> None:- from marimo._cli.sandbox import SandboxModefrom marimo._metadata.opengraph import default_opengraph_image_absfailures: list[tuple[MarimoPath, Exception]] = []@@ -260,81 +190,61 @@ async def _generate_thumbnails() from Noneraise- use_per_notebook_sandbox = sandbox_mode is SandboxMode.MULTI-- if use_per_notebook_sandbox and not DependencyManager.which("uv"):- raise MarimoCLIMissingDependencyError(- "uv is required for --sandbox thumbnail generation.",- "uv",- additional_tip="Install uv from https://github.com/astral-sh/uv",- )-static_dir = marimo_package_path() / "_static"- sandbox_pool: SandboxVenvPool | None = (- SandboxVenvPool() if use_per_notebook_sandbox else None- )- try:- with HtmlAssetServer(- directory=static_dir, route="/__marimo_thumbnail__.html"- ) as server:- async with async_playwright() as playwright:- browser = await playwright.chromium.launch()- context = await browser.new_context(- viewport={"width": width, "height": height},- device_scale_factor=scale,- )- page = await context.new_page()- await page.emulate_media(reduced_motion="reduce")-- for index, notebook in enumerate(notebooks):- try:- out_path = (- output- if output is not None- else default_opengraph_image_abs(- str(notebook.path)- )- )- if out_path.exists() and not overwrite:- echo(- red("skip")- + f": {notebook.short_name} (exists, use --overwrite)"- )- continue-- maybe_make_dirs(out_path)-- echo(f"Rendering {notebook.short_name}...")- sandbox = (- sandbox_pool.get_target(str(notebook.path))- if sandbox_pool is not None- else None- )- html = await _render_html(- notebook,- execute=execute,- include_code=include_code,- args=notebook_args,- asset_url=server.base_url,- sandbox=sandbox,+ with HtmlAssetServer(+ directory=static_dir, route="/__marimo_thumbnail__.html"+ ) as server:+ async with async_playwright() as playwright:+ browser = await playwright.chromium.launch()+ context = await browser.new_context(+ viewport={"width": width, "height": height},+ device_scale_factor=scale,+ )+ page = await context.new_page()+ await page.emulate_media(reduced_motion="reduce")++ for index, notebook in enumerate(notebooks):+ try:+ out_path = (+ output+ if output is not None+ else default_opengraph_image_abs(str(notebook.path))+ )+ if out_path.exists() and not overwrite:+ echo(+ red("skip")+ + f": {notebook.short_name} (exists, use --overwrite)")- server.set_html(html)-- echo(f"Screenshotting -> {out_path}...")- page_url = f"{server.page_url}?v={index}"- await page.goto(page_url, wait_until="load")- # Hide chrome and watermarks marked for print so thumbnails stay focused on notebook content.- await page.add_style_tag(- content=(- '.print\\:hidden,[data-testid="watermark"]{display:none !important;}'- )+ continue++ maybe_make_dirs(out_path)++ echo(f"Rendering {notebook.short_name}...")+ html = await _render_html(+ notebook,+ execute=execute,+ include_code=include_code,+ args=notebook_args,+ asset_url=server.base_url,+ sandbox=sandbox,+ )+ server.set_html(html)++ echo(f"Screenshotting -> {out_path}...")+ page_url = f"{server.page_url}?v={index}"+ await page.goto(page_url, wait_until="load")+ # Hide chrome and watermarks marked for print so thumbnails stay focused on notebook content.+ await page.add_style_tag(+ content=(+ '.print\\:hidden,[data-testid="watermark"]{display:none !important;}')- # Nb renderer starts cell contents as invisible for a short period to avoid flicker- # --> we wait for the first cell container to be visible before snapshotting.- try:- await page.wait_for_function(- r"""+ )+ # Nb renderer starts cell contents as invisible for a short period to avoid flicker+ # --> we wait for the first cell container to be visible before snapshotting.+ try:+ await page.wait_for_function(+ r"""() => {const root = document.getElementById("root");if (!root) return false;@@ -351,30 +261,25 @@ async def _generate_thumbnails(return root.childElementCount > 0;}""",- timeout=_READINESS_WAIT_TIMEOUT_MS,- )- except PlaywrightTimeoutError:- echo(- yellow("warning")- + ": readiness check timed out; capturing screenshot anyway."- )- await page.wait_for_timeout(timeout_ms)- await page.screenshot(- path=str(out_path), full_page=False+ timeout=_READINESS_WAIT_TIMEOUT_MS,+ )+ except PlaywrightTimeoutError:+ echo(+ yellow("warning")+ + ": readiness check timed out; capturing screenshot anyway.")+ await page.wait_for_timeout(timeout_ms)+ await page.screenshot(path=str(out_path), full_page=False)- echo(green("ok") + f": {out_path}")- except Exception as e:- failures.append((notebook, e))- echo(red("error") + f": {notebook.short_name}: {e}")- if not continue_on_error:- raise+ echo(green("ok") + f": {out_path}")+ except Exception as e:+ failures.append((notebook, e))+ echo(red("error") + f": {notebook.short_name}: {e}")+ if not continue_on_error:+ raise- await context.close()- await browser.close()- finally:- if sandbox_pool is not None:- sandbox_pool.close()+ await context.close()+ await browser.close()if failures:raise click.ClickException(@@ -383,7 +288,9 @@ async def _generate_thumbnails(@click.command(- "thumbnail", help="Generate OpenGraph thumbnails for notebooks."+ "thumbnail",+ cls=SandboxCommand,+ help="Generate OpenGraph thumbnails for notebooks.",)@click.argument("name",@@ -447,12 +354,17 @@ async def _generate_thumbnails(),)@click.option(- "--sandbox/--no-sandbox",- is_flag=True,+ "--sandbox",default=None,- type=bool,+ type=click.Choice(["uv", "pixi"]),help=_sandbox_message,)+ "--no-sandbox",+ is_flag=True,+ default=False,+ help="Never run in a sandbox, and never prompt to.",+)@click.option("--continue-on-error/--fail-fast",default=True,@@ -469,12 +381,17 @@ def thumbnail(overwrite: bool,include_code: bool,execute: bool,- sandbox: bool | None,+ sandbox: str | None,+ no_sandbox: bool,continue_on_error: bool,args: tuple[str, ...],) -> None:"""Generate thumbnails for one or more notebooks (or directories)."""- paths, notebook_args = _split_paths_and_args(str(name), args)+ notebook_args: tuple[str, ...] = click.get_current_context().meta.get(+ "marimo_run_args_after_separator", ()+ )+ targets = args[: -len(notebook_args)] if notebook_args else args+ paths = [str(name), *targets]path_targets = [Path(p) for p in paths]notebooks = collect_notebooks(path_targets)if not notebooks:@@ -484,27 +401,40 @@ def thumbnail("--output can only be used when generating thumbnail for a single notebook.")- if not execute and sandbox:+ if not execute and sandbox and not no_sandbox:raise click.UsageError("--sandbox requires --execute.")- sandbox_mode = _resolve_thumbnail_sandbox_mode(- execute=execute,- sandbox=sandbox,- path_targets=path_targets,- first_target=str(name),+ bootstrapped = os.environ.get(_sandbox_bootstrapped_env)+ backend = (+ resolve_sandbox(+ sandbox or bootstrapped,+ no_sandbox,+ str(name) if len(path_targets) == 1 else None,+ )+ if execute+ else None)- if (- execute- and sandbox_mode is not None- and _sandbox_mode_from_env() is None- ):- _bootstrap_thumbnail_sandbox(- args=sys.argv[1:],- name=str(name),- sandbox_mode=sandbox_mode,+ if backend and not bootstrapped:+ require_sandbox_backend(backend)+ # The renderer needs Playwright, not a notebook-bound environment+ # whose identity would be inherited by the export workers.+ sys.exit(+ _wait_on_plan(+ launch_isolated(+ ["-m", "marimo", *_strip_sandbox_args(sys.argv[1:])],+ requirements=runtime_overlay(+ command=["playwright"]+ ).requirements,+ python=sys.executable,+ backend=backend,+ base_env={+ **os.environ,+ _sandbox_bootstrapped_env: backend,+ },+ )+ ))- returntry:DependencyManager.playwright.require("for thumbnail generation")@@ -530,6 +460,6 @@ def thumbnail(execute=execute,notebook_args=notebook_args,continue_on_error=continue_on_error,- sandbox_mode=sandbox_mode,+ sandbox=backend,))diff --git a/marimo/_cli/help_formatter.py b/marimo/_cli/help_formatter.pyindex fe61b93c88..0f054ea5c1 100644--- a/marimo/_cli/help_formatter.py+++ b/marimo/_cli/help_formatter.py@@ -65,6 +65,33 @@ class RunCommand(ColoredCommand):return super().parse_args(ctx, args)+def _normalize_sandbox_args(args: list[str]) -> list[str]:+ """Give a bare `--sandbox` its backwards-compatible uv value.++ Click options cannot reliably accept both an optional value and a+ following positional argument. Normalize the bare spelling before Click+ parses it, leaving explicit uv/pixi values for Click to consume.+ """+ normalized = list(args)+ try:+ limit = normalized.index("--")+ except ValueError:+ limit = len(normalized)+ for index, token in enumerate(normalized[:limit]):+ if token == "--sandbox" and (+ index + 1 == limit or normalized[index + 1] not in ("uv", "pixi")+ ):+ normalized[index] = "--sandbox=uv"+ return normalized+++class SandboxCommand(RunCommand):+ """Accept `--sandbox` with an optional uv/pixi backend."""++ def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:+ return super().parse_args(ctx, _normalize_sandbox_args(args))++class ColoredGroup(click.Group):"""Click Group with colored help output (cargo-style)."""diff --git a/marimo/_cli/sandbox.py b/marimo/_cli/sandbox.pyindex 7e6ab05b89..a402969b93 100644--- a/marimo/_cli/sandbox.py+++ b/marimo/_cli/sandbox.py@@ -1,6 +1,7 @@# Copyright 2026 Marimo. All rights reserved.from __future__ import annotations+import asyncioimport atexitimport osimport platform@@ -8,13 +9,15 @@ import signalimport subprocessimport sysimport tempfile-from enum import Enumfrom pathlib import Pathimport clickfrom marimo import _loggers-from marimo._cli.errors import MarimoCLIMissingDependencyError+from marimo._cli.errors import (+ MarimoCLIMissingDependencyError,+ MarimoCLIRuntimeError,+)from marimo._cli.print import bold, echo, green, mutedfrom marimo._config.settings import GLOBAL_SETTINGSfrom marimo._environments import environment, script_metadata@@ -34,19 +37,6 @@ from marimo._utils.inline_script_metadata import (from marimo._utils.versions import is_editablefrom marimo._version import __version__--class SandboxMode(Enum):- """Sandbox mode for marimo notebooks.-- - SINGLE: Single-file sandbox (the server runs from the notebook's- script environment)- - MULTI: Multi-file sandbox (IPC kernels with per-notebook venvs)- """-- SINGLE = "single"- MULTI = "multi"--LOGGER = _loggers.marimo_logger()@@ -104,62 +94,19 @@ def maybe_prompt_run_in_sandbox(name: str | None) -> bool:return False-def resolve_sandbox_mode(- sandbox: bool | None, name: str | None-) -> SandboxMode | None:- """Determine sandbox mode for the given target.-- Returns:- - None: No sandboxing- - SandboxMode.SINGLE: Single-file sandbox (server in the script- environment)- - SandboxMode.MULTI: Multi-file sandbox (IPC kernels with per-notebook venvs)-- When sandbox is None, prompts the user if the notebook has sandbox metadata- (only for single notebooks, not directories).- """- # Determine if target is a directory (or None = current directory)- is_directory = name is None or os.path.isdir(name)-- # When the sandbox flag is omitted we infer whether to- # start in sandbox mode by examining the notebook file and- # prompting the user. Only prompt for single notebooks, not directories.- if sandbox is None:- # Don't prompt for directories - user must explicitly pass --sandbox- if not is_directory:- sandbox = maybe_prompt_run_in_sandbox(name)- else:- sandbox = False-- if not sandbox:- return None-- # Sandbox enabled - determine mode based on target type- # Directory or home page -> multi-file sandbox (IPC kernels)- # Single file -> single-file sandbox (server in the script environment)- return SandboxMode.MULTI if is_directory else SandboxMode.SINGLE--def resolve_sandbox(sandbox: str | None,no_sandbox: bool,name: str | None,-) -> tuple[SandboxMode | None, SandboxBackend]:- """Resolve the sandbox mode and backend from the CLI flags.-- `sandbox` is None (unset; the user may be prompted), "uv" (a bare- `--sandbox`), or a named backend (`--sandbox=pixi`). `no_sandbox`- disables sandboxing and the prompt.- """- enabled: bool | None+) -> SandboxBackend | None:+ """Select a backend, prompting only for a notebook with dependencies."""if no_sandbox:- enabled = False- elif sandbox is None:- enabled = None- else:- enabled = True- mode = resolve_sandbox_mode(sandbox=enabled, name=name)- return mode, backend_from_flag(sandbox)+ return None+ if sandbox is not None:+ return backend_from_flag(sandbox)+ if maybe_prompt_run_in_sandbox(name):+ return "uv"+ return Nonedef backend_from_flag(sandbox: str | None) -> SandboxBackend:@@ -167,6 +114,45 @@ def backend_from_flag(sandbox: str | None) -> SandboxBackend:return "pixi" if sandbox == "pixi" else "uv"+def ensure_server_environment(+ backend: SandboxBackend | None, *, stdin_notebook: str | None = None+) -> None:+ """Relaunch the editor with server tools, leaving kernels lazy."""+ if (+ backend is None+ or os.environ.pop("MARIMO_SERVER_OVERLAY", None) is not None+ ):+ return++ from marimo._environments.backends import launch_server+ from marimo._environments.errors import EnvironmentManagerError++ try:+ require_sandbox_backend(backend)+ except EnvironmentManagerError as error:+ raise MarimoCLIRuntimeError(str(error)) from error+ args = _strip_sandbox_args(sys.argv[1:])+ # Preserve a prompted choice and keep options before notebook arguments.+ index = args.index("--") if "--" in args else len(args)+ args[index:index] = [f"--sandbox={backend}"]+ if stdin_notebook is not None:+ # The outer process already consumed stdin and owns this temp file.+ args.insert(index, stdin_notebook)+ sys.exit(+ _wait_on_plan(+ launch_server(+ ["-m", "marimo", *args],+ backend=backend,+ base_env={+ **os.environ,+ "MARIMO_SERVER_OVERLAY": "1",+ "MARIMO_ANCESTOR_PID": str(os.getpid()),+ },+ )+ )+ )++def _is_versioned(dependency: str) -> bool:return any(c in dependency for c in ("==", ">=", "<=", ">", "<", "~"))@@ -411,6 +397,27 @@ def construct_uv_command(return uv_cmd + cmd+def require_sandbox_backend(backend: SandboxBackend) -> None:+ """Check the backend and report installation instructions if missing."""+ from marimo._environments import backends+ from marimo._environments.errors import EnvironmentManagerNotFoundError++ try:+ backends.ensure_available(backend)+ except EnvironmentManagerNotFoundError as e:+ option = "--sandbox=pixi" if backend == "pixi" else "--sandbox"+ install_url = (+ "https://pixi.prefix.dev/latest/installation/"+ if backend == "pixi"+ else "https://docs.astral.sh/uv/getting-started/installation/"+ )+ raise MarimoCLIMissingDependencyError(+ f"{backend} must be installed to use {option}.",+ backend,+ additional_tip=f"Install {backend} from {install_url}",+ ) from e++def run_in_sandbox(args: list[str],*,@@ -434,27 +441,11 @@ def run_in_sandbox(Used for "single" sandbox mode (marimo edit --sandbox notebook.py).For "multi" sandbox mode (directory), see IPCKernelManagerImpl."""- from marimo._environments import backends- from marimo._environments.errors import (- EnvironmentManagerError,- EnvironmentManagerNotFoundError,- )+ from marimo._environments.errors import EnvironmentManagerErrorfrom marimo._environments.sandbox import NotebookSandboxtry:- backends.ensure_available(backend)- except EnvironmentManagerNotFoundError as e:- option = "--sandbox=pixi" if backend == "pixi" else "--sandbox"- install_url = (- "https://pixi.prefix.dev/latest/installation/"- if backend == "pixi"- else "https://docs.astral.sh/uv/getting-started/installation/"- )- raise MarimoCLIMissingDependencyError(- f"{backend} must be installed to use {option}.",- backend,- additional_tip=f"Install {backend} from {install_url}",- ) from e+ require_sandbox_backend(backend)except EnvironmentManagerError as e:# e.g. an environment manager too old for script environments.echo(str(e), err=True)@@ -522,12 +513,16 @@ def run_in_sandbox(if not overridden and (name is None or os.path.isfile(name)):notebook_sandbox = NotebookSandbox(name, backend)try:- plan = notebook_sandbox.launch(- cmd,- overlay=overlay,- base_env=env,- python_override=python_request if backend == "uv" else None,- on_output=lambda _line: None,+ plan = asyncio.run(+ notebook_sandbox.launch_async(+ cmd,+ overlay=overlay,+ base_env=env,+ python_override=python_request+ if backend == "uv"+ else None,+ on_output=lambda _line: None,+ ))handle = notebook_sandbox.environmentassert handle is not None@@ -543,6 +538,9 @@ def run_in_sandbox(notebook_sandbox.close()echo(str(e), err=True)return getattr(e, "returncode", None) or 1+ except BaseException:+ notebook_sandbox.close()+ raiseif plan is None:if backend == "pixi":@@ -558,7 +556,7 @@ def run_in_sandbox(for line in _resolve_requirements_txt_lines(pyproject)if line.strip() and not is_marimo_dependency(line)] + requirements- from marimo._environments.environment import launch_isolated+ from marimo._environments.backends import launch_isolated# The one resolve the parent environment cannot serve: an# overridden interpreter under external constraints.@@ -590,6 +588,8 @@ def _strip_sandbox_args(cmd: list[str]) -> list[str]:continueif token == "--sandbox":index += 1+ if index < len(cmd) and cmd[index] in ("uv", "pixi"):+ index += 1continuestripped.append(token)index += 1diff --git a/marimo/_environments/backends.py b/marimo/_environments/backends.pyindex 31ce32837a..31c2689823 100644--- a/marimo/_environments/backends.py+++ b/marimo/_environments/backends.py@@ -13,9 +13,6 @@ Both managers honor the runtime overlay: uv layers it directly viaprefix's site-packages. Either way the manifest carries only a loose`marimo` (for standalone runs) and the overlay supplies the runningversion.--SINGLE and MULTI sandbox modes are topologies, not engines: they differ-in which process gets launched, not in how environments are made."""from __future__ import annotations@@ -110,6 +107,98 @@ def launch()+async def sync_notebook_async(+ path: str,+ *,+ backend: Backend,+ python_override: str | None = None,+ on_output: Callable[[str], None] | None = None,+) -> Environment:+ """Synchronize cancellably, keeping the carrier until the command exits."""+ from marimo._environments import script_metadata++ adapter = adapter_for(backend)+ await adapter.ensure_available_async()+ async with script_metadata.materialized_for_environment_async(+ path+ ) as target:+ return await adapter.sync_async(+ target, python_override=python_override, on_output=on_output+ )+++def _uv_launcher(backend: Backend) -> tuple[str, ...]:+ if backend == "pixi":+ from marimo._environments.pixi import UV_OVERLAY_SPEC, require_pixi_bin++ return (+ require_pixi_bin(),+ "exec",+ "--spec",+ UV_OVERLAY_SPEC,+ "uv",+ )+ from marimo._environments.uv import require_uv_bin++ return (require_uv_bin(),)+++def launch_server(+ args: Sequence[str],+ *,+ backend: Backend,+ base_env: Mapping[str, str] | None = None,+) -> ProcessPlan:+ """Layer editor tools over the host Python, independently of notebooks."""+ from marimo._environments import environment+ from marimo._environments.overlay import runtime_overlay++ return environment.launch(+ environment.Environment(sys.executable, sys.prefix, "unchanged"),+ args,+ overlay=runtime_overlay(["lsp"]),+ base_env=base_env,+ launcher=_uv_launcher(backend),+ )+++def launch_isolated(+ args: Sequence[str],+ *,+ requirements: Sequence[str],+ python: str,+ backend: Backend = "uv",+ base_env: Mapping[str, str] | None = None,+) -> ProcessPlan:+ """Plan an ephemeral Python environment using the selected backend.++ Used for command dependencies and constrained interpreter overrides,+ independently of any notebook's environment or metadata.+ """+ from marimo._environments.environment import ProcessPlan, _with_args++ env = dict(os.environ if base_env is None else base_env)+ env.pop("VIRTUAL_ENV", None)+ env.pop("UV_PROJECT_ENVIRONMENT", None)+ return ProcessPlan(+ argv=(+ *_uv_launcher(backend),+ "run",+ "--isolated",+ "--no-project",+ "--compile-bytecode",+ "--python",+ python,+ *_with_args(requirements),+ "--",+ "python",+ *args,+ ),+ env=env,+ start_new_session=True,+ )++def launch_fallback(args: Sequence[str],*,@@ -168,6 +257,24 @@ class UvBackendAdapter(_ReportingBackendAdapter):ensure_supported_uv()+ async def ensure_available_async(self) -> None:+ from marimo._environments.environment import ensure_supported_uv_async++ await ensure_supported_uv_async()++ async def prepare_source_async(self, source: str) -> None:+ from marimo._environments import script_metadata++ try:+ await script_metadata.ensure_marimo_async(+ source,+ on_command=lambda command: self._report("prepare", command),+ )+ except Exception as error:+ LOGGER.warning(+ "Failed to add marimo to script metadata: %s", error+ )+def prepare_source(self, source: str) -> None:import subprocess@@ -292,6 +399,25 @@ class UvBackendAdapter(_ReportingBackendAdapter):tree = parse_uv_tree(completed.stdout)return PackageState(packages=_flatten_tree(tree), tree=tree)+ async def sync_async(+ self,+ target: MaterializedScript,+ *,+ python_override: str | None,+ on_output: LogCallback | None,+ active_environment: Environment | None = None,+ ) -> Environment:+ from marimo._environments.environment import sync_async++ return await sync_async(+ target.path,+ cwd=target.directory,+ python_override=python_override,+ active_environment=active_environment,+ on_output=on_output,+ on_command=lambda argv: self._report("sync", argv),+ )+def launch(self,environment: Environment,@@ -321,6 +447,48 @@ class PixiBackendAdapter(_ReportingBackendAdapter):pixi.require_pixi_bin()pixi.ensure_supported_pixi()+ async def ensure_available_async(self) -> None:+ from marimo._environments import pixi++ await pixi.ensure_supported_pixi_async()++ async def prepare_source_async(self, source: str) -> None:+ from marimo._environments import pixi++ try:+ await pixi.ensure_marimo_async(+ source,+ on_command=lambda command: self._report("prepare", command),+ )+ except Exception as error:+ LOGGER.warning(+ "Failed to add marimo to script metadata: %s", error+ )++ async def sync_async(+ self,+ target: MaterializedScript,+ *,+ python_override: str | None,+ on_output: LogCallback | None,+ active_environment: Environment | None = None,+ ) -> Environment:+ from marimo._environments import pixi++ if python_override is not None:+ raise pixi.PixiError(+ "pixi sandboxes do not support a Python version override"+ )+ environment = await pixi.sync_async(+ target.path,+ cwd=target.directory,+ on_output=on_output,+ on_command=lambda command: self._report("sync", command),+ )++ self._check_active_environment(environment, active_environment)+ return environment+def prepare_source(self, source: str) -> None:import subprocess@@ -396,6 +564,13 @@ class PixiBackendAdapter(_ReportingBackendAdapter):on_output=on_output,on_command=lambda command: self._report("sync", command),)+ self._check_active_environment(environment, active_environment)+ return environment++ @staticmethod+ def _check_active_environment(+ environment: Environment, active_environment: Environment | None+ ) -> None:if active_environment is not None and os.path.realpath(environment.root) != os.path.realpath(active_environment.root):@@ -412,7 +587,6 @@ class PixiBackendAdapter(_ReportingBackendAdapter):"in a new environment. Restart the kernel to use the updated ""dependencies. Restarting clears in-memory variables.")- return environmentdef packages(self,diff --git a/marimo/_environments/environment.py b/marimo/_environments/environment.pyindex b031e966b4..5d1167c8ca 100644--- a/marimo/_environments/environment.py+++ b/marimo/_environments/environment.py@@ -24,6 +24,7 @@ from marimo._environments.uv import (require_uv_bin,script_command_env,uv,+ uv_async,uv_stream,)@@ -104,6 +105,7 @@ def launch(*,overlay: RuntimeOverlay,base_env: Mapping[str, str] | None = None,+ launcher: Sequence[str] | None = None,) -> ProcessPlan:"""Plans running `python <args...>` inside the environment.@@ -121,7 +123,7 @@ def launch(env = environment.process_env(base_env)return ProcessPlan(argv=(- require_uv_bin(),+ *(launcher if launcher is not None else (require_uv_bin(),)),"run",# The script environment is VIRTUAL_ENV in `env`; --active# makes uv layer on top of it instead of ignoring it.@@ -139,46 +141,6 @@ def launch()-def launch_isolated(- args: Sequence[str],- *,- requirements: Sequence[str],- python: str,- base_env: Mapping[str, str] | None = None,-) -> ProcessPlan:- """Plans `python <args...>` in an ephemeral environment.-- For resolves no existing environment can serve: an overridden- interpreter under external constraints (html-wasm pins the Pyodide- interpreter and resolution). Nothing is layered here, so unlike- `launch` the requirements are the whole environment -- the notebook's- dependencies as well as marimo's. uv resolves them into a cached- environment and runs the process in an ephemeral copy, so packages- installed during the session die with it and nothing persists per- invocation.- """- env = dict(os.environ if base_env is None else base_env)- env.pop("VIRTUAL_ENV", None)- env.pop("UV_PROJECT_ENVIRONMENT", None)- return ProcessPlan(- argv=(- require_uv_bin(),- "run",- "--isolated",- "--no-project",- "--compile-bytecode",- "--python",- python,- *_with_args(requirements),- "--",- "python",- *args,- ),- env=env,- start_new_session=True,- )--def _with_args(requirements: Sequence[str]) -> list[str]:"""`uv run` flags for layered requirements; `-e <path>` is editable."""with_args: list[str] = []@@ -211,6 +173,43 @@ def sync(Raises `UvCommandError` on failure and never mutates `script`."""ensure_supported_uv()+ args, env = _sync_command(script, python_override, active_environment)+ if on_output is not None:+ completed = uv_stream(+ args,+ on_output,+ env=env,+ cwd=cwd,+ on_command=on_command,+ )+ else:+ completed = uv(args, env=env, cwd=cwd, on_command=on_command)+ return _parse_report(completed.stdout)+++async def sync_async(+ script: str,+ *,+ cwd: str | None = None,+ python_override: str | None = None,+ active_environment: Environment | None = None,+ on_output: Callable[[str], None] | None = None,+ on_command: Callable[[Sequence[str]], None] | None = None,+) -> Environment:+ """Synchronize without blocking; cancellation stops uv before returning."""+ await ensure_supported_uv_async()+ args, env = _sync_command(script, python_override, active_environment)+ completed = await uv_async(+ args, env=env, cwd=cwd, on_output=on_output, on_command=on_command+ )+ return _parse_report(completed.stdout)+++def _sync_command(+ script: str,+ python_override: str | None,+ active_environment: Environment | None,+) -> tuple[list[str], dict[str, str]]:args = ["sync","--script",@@ -227,22 +226,22 @@ def sync(# Never inherit VIRTUAL_ENV: it may name the runtime overlay.env["VIRTUAL_ENV"] = active_environment.rootargs.append("--active")- if on_output is not None:- completed = uv_stream(- args,- on_output,- env=env,- cwd=cwd,- on_command=on_command,- )- else:- completed = uv(args, env=env, cwd=cwd, on_command=on_command)- return _parse_report(completed.stdout)+ return args, envdef ensure_supported_uv() -> None:"""Raise `UvUnsupportedVersionError` for a uv below the minimum."""version = _uv_version()+ _check_version(version)+++async def ensure_supported_uv_async() -> None:+ completed = await uv_async(["--version"])+ version = completed.stdout.strip().removeprefix("uv ").split(" ")[0]+ _check_version(version)+++def _check_version(version: str) -> None:parsed = _parse_version(version)if parsed is None:# An unparsable version is likely newer than anything we know;diff --git a/marimo/_environments/errors.py b/marimo/_environments/errors.pyindex f9f213b03f..57e3a9c44f 100644--- a/marimo/_environments/errors.py+++ b/marimo/_environments/errors.py@@ -22,8 +22,9 @@ class MissingScriptMetadataError(EnvironmentManagerError):class SandboxRestartRequired(EnvironmentManagerError):- """The manifest synchronized, but not into the live kernel's prefix.+ """Applying the manifest requires relaunching the kernel.- This is not a solver failure. Callers must not report the requested+ The active interpreter is incompatible, or synchronization selected a+ different prefix. Callers must not report the requestedpackages as importable until the kernel launches the new environment."""diff --git a/marimo/_environments/pixi.py b/marimo/_environments/pixi.pyindex 2de6a554d3..54fe16e365 100644--- a/marimo/_environments/pixi.py+++ b/marimo/_environments/pixi.py@@ -123,6 +123,16 @@ def ensure_supported_pixi() -> None:raise PixiUnsupportedVersionError()+async def ensure_supported_pixi_async() -> None:+ from marimo._environments.process import run_command++ completed = await run_command(+ [require_pixi_bin(), "install", "--help"], timeout=10+ )+ if completed.returncode != 0 or "--script" not in completed.stdout:+ raise PixiUnsupportedVersionError()++# `pixi install --script` reports the environment on stderr:# ✔ The script environment has been installed at '<prefix>'.# A `--json` report is the upstream ask that retires this parse.@@ -145,33 +155,43 @@ def sync(on interpreter identity. Raises `PixiCommandError` on failure andnever mutates `script`."""- from marimo._environments.environment import Environment+ completed = _run(+ _sync_command(script),+ cwd=cwd,+ on_output=on_output,+ on_command=on_command,+ )+ return _parse_sync_report(completed.stderr)- args = [- require_pixi_bin(),- "install",- "--script",- os.path.abspath(script),- ]++async def sync_async(+ script: str,+ *,+ cwd: str | None = None,+ on_output: Callable[[str], None] | None = None,+ on_command: Callable[[Sequence[str]], None] | None = None,+) -> Environment:+ from marimo._environments.process import run_command++ args = _sync_command(script)if on_command is not None:on_command(args)- completed = subprocess.run(- args,- capture_output=True,- text=True,- encoding="utf-8",- # pixi must never hang waiting for input.- stdin=subprocess.DEVNULL,- env=command_env(),- cwd=cwd,- start_new_session=os.name != "nt",+ completed = await run_command(+ args, env=command_env(), cwd=cwd, on_stderr=on_output)- if on_output is not None:- for line in (completed.stdout + completed.stderr).splitlines(True):- on_output(line)if completed.returncode != 0:raise _command_error(completed)- report = _ANSI.sub("", completed.stderr)+ return _parse_sync_report(completed.stderr)+++def _sync_command(script: str) -> list[str]:+ return [require_pixi_bin(), "install", "--script", os.path.abspath(script)]+++def _parse_sync_report(stderr: str) -> Environment:+ from marimo._environments.environment import Environment++ report = _ANSI.sub("", stderr)match = _INSTALLED_AT.search(report)if match is None:raise PixiError(@@ -288,7 +308,8 @@ def tree_script_packages(script: str, *, cwd: str) -> str:def _run(args: Sequence[str],*,- cwd: str,+ cwd: str | None,+ timeout: float | None = None,on_output: Callable[[str], None] | None = None,on_command: Callable[[Sequence[str]], None] | None = None,) -> subprocess.CompletedProcess[str]:@@ -303,6 +324,7 @@ def _run(stdin=subprocess.DEVNULL,env=command_env(),cwd=cwd,+ timeout=timeout,start_new_session=os.name != "nt",)if on_output is not None:@@ -345,22 +367,12 @@ def ensure_marimo("--pypi","marimo",]- if on_command is not None:- on_command(args)- completed = subprocess.run(+ _run(args,- capture_output=True,- text=True,- encoding="utf-8",- # pixi must never hang waiting for input.- stdin=subprocess.DEVNULL,- env=command_env(),cwd=os.path.dirname(os.path.abspath(path)),timeout=60,- start_new_session=os.name != "nt",+ on_command=on_command,)- if completed.returncode != 0:- raise _command_error(completed)# The uv that applies launch overlays, fetched through `pixi exec` so@@ -370,6 +382,41 @@ def ensure_marimo(UV_OVERLAY_SPEC = "uv>=0.12"+async def ensure_marimo_async(+ path: str,+ *,+ on_command: Callable[[Sequence[str]], None] | None = None,+) -> None:+ from marimo._environments.process import run_command+ from marimo._environments.script_metadata import (+ ensure_metadata_block,+ should_add_marimo,+ )++ if not should_add_marimo(path):+ return+ ensure_metadata_block(path)+ absolute = os.path.abspath(path) # noqa: ASYNC240+ args = [+ require_pixi_bin(),+ "add",+ "--script",+ absolute,+ "--pypi",+ "marimo",+ ]+ if on_command is not None:+ on_command(args)+ completed = await run_command(+ args,+ env=command_env(),+ cwd=os.path.dirname(absolute),+ timeout=60,+ )+ if completed.returncode != 0:+ raise _command_error(completed)++# Run before importing marimo: importing a module in this package would first# import marimo itself with pixi exec's *tool* environment still activated.# exec preserves Python's normal -m/-c/script argument handling and signal PID.diff --git a/marimo/_environments/process.py b/marimo/_environments/process.pynew file mode 100644index 0000000000..66d8ab3453--- /dev/null+++ b/marimo/_environments/process.py@@ -0,0 +1,84 @@+# Copyright 2026 Marimo. All rights reserved.+"""Awaitable sandbox commands with ownership of their subprocesses."""++from __future__ import annotations++import asyncio+import subprocess+from typing import TYPE_CHECKING++from marimo import _loggers+from marimo._utils.subprocess import stop_subprocess++if TYPE_CHECKING:+ from collections.abc import Callable, Mapping, Sequence++LOGGER = _loggers.marimo_logger()+++async def run_command(+ argv: Sequence[str],+ *,+ env: Mapping[str, str] | None = None,+ cwd: str | None = None,+ timeout: float | None = None,+ on_stderr: Callable[[str], None] | None = None,+) -> subprocess.CompletedProcess[str]:+ """Capture output and stream stderr without blocking the event loop.++ The callback runs on the caller's event loop. Cancellation and timeout+ stop the command's owned process group and finish reading its pipes before+ returning. Nonzero exits are returned for the backend to interpret.+ """+ loop = asyncio.get_running_loop()++ def report(line: str) -> None:+ if on_stderr is not None:+ try:+ on_stderr(line)+ except Exception:+ LOGGER.exception("Failed to report sandbox output")++ # Windows sessions use a selector loop, which has no asyncio subprocess+ # support. Own Popen here; only pipe reads and waiting run on threads.+ with subprocess.Popen( # noqa: ASYNC220+ list(argv),+ stdin=subprocess.DEVNULL,+ stdout=subprocess.PIPE,+ stderr=subprocess.PIPE,+ text=True,+ encoding="utf-8",+ errors="replace",+ env=env,+ cwd=cwd,+ start_new_session=True,+ ) as process:+ assert process.stdout is not None+ assert process.stderr is not None+ stderr_pipe = process.stderr++ def read_stderr() -> str:+ lines: list[str] = []+ for line in stderr_pipe:+ lines.append(line)+ if on_stderr is not None:+ loop.call_soon_threadsafe(report, line)+ process.wait()+ return "".join(lines)++ output = asyncio.gather(+ loop.run_in_executor(None, process.stdout.read),+ loop.run_in_executor(None, read_stderr),+ )+ try:+ stdout, stderr = await asyncio.wait_for(+ asyncio.shield(output), timeout=timeout+ )+ except BaseException:+ await stop_subprocess(+ process, start_new_session=True, drain=output+ )+ raise+ return subprocess.CompletedProcess(+ list(argv), process.returncode, stdout, stderr+ )diff --git a/marimo/_environments/sandbox.py b/marimo/_environments/sandbox.pyindex 7729cd3c76..d9fc74eeb4 100644--- a/marimo/_environments/sandbox.py+++ b/marimo/_environments/sandbox.py@@ -11,12 +11,19 @@ from __future__ import annotationsimport reimport shlex+import subprocessimport tempfilefrom collections.abc import Callablefrom dataclasses import dataclass+from pathlib import Pathfrom typing import TYPE_CHECKING, Literal, Protocolfrom marimo._environments import script_metadata+from marimo._environments.errors import (+ EnvironmentManagerError,+ SandboxRestartRequired,+)+from marimo._environments.process import run_commandif TYPE_CHECKING:from collections.abc import Mapping, Sequence@@ -99,8 +106,21 @@ class BackendAdapter(Protocol):def ensure_available(self) -> None: ...+ async def ensure_available_async(self) -> None: ...+def prepare_source(self, source: str) -> None: ...+ async def prepare_source_async(self, source: str) -> None: ...++ async def sync_async(+ self,+ target: MaterializedScript,+ *,+ python_override: str | None,+ on_output: LogCallback | None,+ active_environment: Environment | None = None,+ ) -> Environment: ...+def add(self,target: MaterializedScript,@@ -292,6 +312,60 @@ class NotebookSandbox:environment = self._sync(python_override=python_override, on_output=on_output)+ return self._launch_plan(environment, args, overlay, base_env)++ async def launch_async(+ self,+ args: Sequence[str],+ *,+ overlay: RuntimeOverlay,+ base_env: Mapping[str, str] | None = None,+ python_override: str | None = None,+ on_output: LogCallback | None = None,+ ) -> ProcessPlan:+ """Prepare cancellably; publish the environment only after success."""+ await self._adapter.ensure_available_async()+ script_metadata.ensure_metadata_block(self._source)+ await self._adapter.prepare_source_async(self._source)+ async with script_metadata.materialized_for_environment_async(+ self._source+ ) as target:+ environment = await self._adapter.sync_async(+ target, python_override=python_override, on_output=on_output+ )+ self._environment = environment+ self._environment_source = self._source+ return self._launch_plan(environment, args, overlay, base_env)++ async def sync_async(self) -> None:+ """Apply the saved manifest to the environment used by this kernel."""+ await self._adapter.ensure_available_async()+ async with script_metadata.materialized_for_environment_async(+ self._source+ ) as target:+ requirement = _python_requirement(target, self._environment)+ if requirement is not None:+ assert self._environment is not None+ completed = await run_command(+ [self._environment.python, "-I", "-S", "--version"]+ )+ _check_python_requirement(requirement, completed)+ environment = await self._adapter.sync_async(+ target,+ python_override=None,+ on_output=None,+ active_environment=self._environment,+ )+ self._environment = environment+ self._environment_source = self._source++ def _launch_plan(+ self,+ environment: Environment,+ args: Sequence[str],+ overlay: RuntimeOverlay,+ base_env: Mapping[str, str] | None,+ ) -> ProcessPlan:plan = self._adapter.launch(environment,args,@@ -426,20 +500,7 @@ class NotebookSandbox:with script_metadata.materialized_for_environment(self._source) as target:- state = self._adapter.packages(target, self._environment)- packages = tuple(- package- for package in state.packages- if _normalize_dependency_name(package.name) != "marimo"- )- tree = state.tree- if tree is not None:- tree.dependencies = [- dependency- for dependency in tree.dependencies- if _normalize_dependency_name(dependency.name) != "marimo"- ]- return PackageState(packages=packages, tree=tree)+ return self._adapter.packages(target, self._environment)def _reopened_requirement(self, bare: _BareRequirement@@ -553,6 +614,15 @@ class NotebookSandbox:with script_metadata.materialized_for_environment(self._source) as target:+ requirement = _python_requirement(target, active_environment)+ if requirement is not None:+ assert active_environment is not None+ completed = subprocess.run(+ [active_environment.python, "-I", "-S", "--version"],+ capture_output=True,+ text=True,+ )+ _check_python_requirement(requirement, completed)environment = self._adapter.sync(target,python_override=python_override,@@ -564,6 +634,47 @@ class NotebookSandbox:return environment+def _python_requirement(+ target: MaterializedScript, active_environment: Environment | None+) -> str | None:+ if active_environment is None:+ return None+ project = script_metadata.loads(Path(target.path).read_text("utf-8"))+ requirement = (+ project.get("requires-python") if project is not None else None+ )+ if requirement is not None and not isinstance(requirement, str):+ raise script_metadata.ScriptMetadataError(+ "requires-python must be a version specifier string"+ )+ return requirement+++def _check_python_requirement(+ requirement: str, completed: subprocess.CompletedProcess[str]+) -> None:+ from packaging.specifiers import InvalidSpecifier, SpecifierSet++ try:+ specifier = SpecifierSet(requirement)+ except InvalidSpecifier as error:+ raise script_metadata.ScriptMetadataError(+ f"Invalid requires-python: {requirement}"+ ) from error+ if completed.returncode != 0:+ raise EnvironmentManagerError(+ "Could not determine the active sandbox's Python version.\n"+ + completed.stderr+ )+ version = completed.stdout.strip().removeprefix("Python ")+ if not specifier.contains(version, prereleases=True):+ raise SandboxRestartRequired(+ f"The manifest requires Python {requirement}, but the running "+ f"kernel uses Python {version}. Restart the kernel to apply "+ "the new Python requirement."+ )++def _normalize_dependency_name(requirement: str) -> str:match = re.match(r"[A-Za-z0-9][A-Za-z0-9._-]*", requirement.strip())if match is None:diff --git a/marimo/_environments/script_metadata.py b/marimo/_environments/script_metadata.pyindex 05d9a79578..c5f32a5196 100644--- a/marimo/_environments/script_metadata.py+++ b/marimo/_environments/script_metadata.py@@ -16,8 +16,10 @@ so directory-scoped configuration applies.from __future__ import annotations+import asyncioimport contextlibimport errno+import hashlibimport osimport platformimport re@@ -39,18 +41,20 @@ from marimo._environments.uv import (UvError,script_command_env,uv,+ uv_async,uv_stream,)from marimo._utils.toml import toml_reader+from marimo._utils.xdg import marimo_state_dirif TYPE_CHECKING:- from collections.abc import Callable, Iterator, Sequence+ from collections.abc import AsyncIterator, Callable, Iterator, SequenceLOGGER = _loggers.marimo_logger()REGEX = (- r"(?m)^# /// (?P<type>[a-zA-Z0-9-]+)$\s"- r"(?P<content>(^#(?! ///$)(| .*)$\s)+)^# ///$"+ r"(?m)^# /// (?P<type>[a-zA-Z0-9-]+)\r?$\n"+ r"(?P<content>(^#(?! ///\r?$)(| .*)\r?$\n)+)^# ///(?=\r?$)")@@ -58,6 +62,66 @@ class ScriptMetadataError(EnvironmentManagerError):"""A script metadata edit could not be completed."""+class ManifestConflictError(ScriptMetadataError):+ """The manifest changed after it was opened for editing."""+++def _manifest_text(script: str) -> tuple[re.Match[str] | None, str]:+ matches = [+ match+ for match in re.finditer(REGEX, script)+ if match.group("type") == "script"+ ]+ if len(matches) > 1:+ raise ScriptMetadataError("Multiple script metadata blocks found")+ if not matches:+ return None, ""+ match = matches[0]+ contents = "".join(+ line[2:] if line.startswith("# ") else line[1:]+ for line in match.group("content").splitlines(keepends=True)+ )+ return match, contents.replace("\r\n", "\n")+++def read_manifest(path: str) -> str:+ """Read the original TOML, including malformed TOML that needs repair."""+ if path.endswith((".md", ".qmd")):+ return _manifest_text(_read_frontmatter(path).header)[1]+ with open(path, encoding="utf-8", newline="") as file:+ return _manifest_text(file.read())[1]+++def write_manifest(path: str, contents: str, *, previous: str) -> str:+ """Replace only metadata, rejecting stale edits and invalid TOML."""+ toml_reader.reads(contents)+ if any(line == "///" for line in contents.splitlines()):+ raise ScriptMetadataError("The manifest cannot contain script markers")+ with notebook_file_lock(path), materialized_for_edit(path) as target:+ file = Path(target.path)+ with file.open(encoding="utf-8", newline="") as source:+ script = source.read()+ match, current = _manifest_text(script)+ if current != previous:+ raise ManifestConflictError(+ "The manifest changed on disk. Reopen it before saving."+ )+ newline = "\r\n" if "\r\n" in script else "\n"+ block = wrap_block(contents.replace("\r\n", "\n")).replace(+ "\n", newline+ )+ if match is not None:+ updated = script[: match.start()] + block + script[match.end() :]+ elif script.startswith("#!"):+ shebang, _, rest = script.partition("\n")+ updated = f"{shebang}\n{block}{newline}{rest}"+ else:+ updated = f"{block}{newline}{script}"+ with file.open("w", encoding="utf-8", newline="") as destination:+ destination.write(updated)+ return read_manifest(path)++def loads(script: str) -> dict[str, Any] | None:"""Parse the `# /// script` block, or None if the script has none.@@ -121,7 +185,7 @@ def metadata_transaction(path: str) -> Iterator[None]:try:yieldexcept SandboxRestartRequired:- # Synchronization succeeded; the live kernel uses a different prefix.+ # Keep the requested manifest so the restart can apply it.raiseexcept (Exception, KeyboardInterrupt):if _metadata_block(path) == block:@@ -295,6 +359,24 @@ def ensure_marimo(_edit(path, edit)+async def ensure_marimo_async(+ path: str,+ *,+ on_command: Callable[[Sequence[str]], None] | None = None,+) -> None:+ if not should_add_marimo(path):+ return+ ensure_metadata_block(path)+ with materialized_for_edit(path) as target:+ await uv_async(+ ["add", "--script", target.path, "marimo"],+ env=script_command_env(),+ timeout=30,+ cwd=target.directory,+ on_command=on_command,+ )++def ensure_requires_python(path: str) -> None:"""Add `requires-python` to existing script metadata if not present.@@ -388,23 +470,54 @@ def _carrier_prefix(path: str) -> str:@contextlib.contextmanager-def _stable_carrier_lock(path: str) -> Iterator[None]:- """Hold an OS lock through creation, use, and removal of the carrier.+def notebook_file_lock(path: str) -> Iterator[None]:+ """Serialize notebook read-modify-write operations across processes.++ Keep this separate from the carrier lock: async environment operations+ hold that lock while yielding, but notebook saves can run on the event loop.+ """+ with _file_lock(_notebook_lock_path(path), blocking=True):+ yield+++def _notebook_lock_path(path: str) -> Path:+ # Processes may have different temporary directories for the same notebook.+ directory = marimo_state_dir() / "notebook-locks"+ directory.mkdir(mode=0o700, parents=True, exist_ok=True)+ key = hashlib.sha256(+ os.path.normcase(os.path.realpath(path)).encode()+ ).hexdigest()+ return directory / f"{key}.lock"+++def _stable_carrier_lock(+ path: str, *, blocking: bool = True+) -> Iterator[None]:+ # Carrier lifetimes can span async environment operations, so they must+ # use a different lock from notebook writes.+ target = _notebook_lock_path(path).with_suffix(".carrier.lock")+ with _file_lock(target, blocking=blocking):+ yield+++def _file_lock(target: Path, *, blocking: bool) -> Iterator[None]:+ """Hold an OS lock on a persistent file.The lock file stays in place: unlinking it would let a new caller locka different inode while existing callers still wait on the old one.Process exit releases the lock, including after a crash."""- target = Path(path).with_name(f"{_carrier_prefix(path)}.lock")# Never truncate or follow a pre-existing link, even for the lock file.if target.is_symlink():- raise OSError(f"Refusing to use symlink as carrier lock: {target}")+ raise OSError(f"Refusing to use symlink as lock file: {target}")descriptor = os.open(target, os.O_RDWR | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0), 0o600)with os.fdopen(descriptor, "r+b", buffering=0) as lock:if not stat.S_ISREG(os.fstat(lock.fileno()).st_mode):- raise OSError(f"Carrier lock is not a regular file: {target}")+ raise OSError(f"Lock file is not a regular file: {target}")if sys.platform == "win32":import msvcrt@@ -415,6 +528,8 @@ def _stable_carrier_lock(path: str) -> Iterator[None]:except OSError as error:if error.errno not in (errno.EACCES, errno.EDEADLK):raise+ if not blocking:+ raise BlockingIOError from errortime.sleep(0.05)try:yield@@ -423,7 +538,10 @@ def _stable_carrier_lock(path: str) -> Iterator[None]:else:import fcntl- fcntl.flock(lock.fileno(), fcntl.LOCK_EX)+ fcntl.flock(+ lock.fileno(),+ fcntl.LOCK_EX | (0 if blocking else fcntl.LOCK_NB),+ )try:yieldfinally:@@ -545,8 +663,34 @@ def materialized_for_environment(path: str) -> Iterator[MaterializedScript]:keys a script environment on the script's absolute path, so thestable name maps one notebook to one environment, reconciled inplace across sessions. An OS lock serializes carrier lifetimes across- threads and processes.+ threads and processes; its persistent file lives in marimo's state directory."""+ with _materialized_for_environment(path, blocking=True) as target:+ yield target+++async def materialized_for_environment_async(+ path: str,+) -> AsyncIterator[MaterializedScript]:+ """Wait cancellably for the same carrier lock used by synchronous callers."""+ with contextlib.ExitStack() as stack:+ while True:+ try:+ target = stack.enter_context(+ _materialized_for_environment(path, blocking=False)+ )+ break+ except BlockingIOError:+ # OS file locks have no portable readiness notification.+ await asyncio.sleep(0.05)+ yield target+++def _materialized_for_environment(+ path: str, *, blocking: bool+) -> Iterator[MaterializedScript]:absolute = os.path.abspath(path)directory = os.path.dirname(absolute)if not path.endswith((".md", ".qmd")):@@ -555,12 +699,15 @@ def materialized_for_environment(path: str) -> Iterator[MaterializedScript]:with contextlib.ExitStack() as stack:try:- stack.enter_context(_stable_carrier_lock(absolute))+ stack.enter_context(+ _stable_carrier_lock(absolute, blocking=blocking)+ )+ except BlockingIOError:+ raiseexcept OSError as error:raise ScriptMetadataError(- f"Cannot lock a metadata carrier beside {path}. "- "Make the notebook directory writable and remove any "- "conflicting carrier lock symlinks."+ f"Cannot lock a metadata carrier for {path}. "+ f"Check the lock directory's permissions and files: {error}") from errorcontent = ("# Generated by marimo; safe to delete.\n"diff --git a/marimo/_environments/uv.py b/marimo/_environments/uv.pyindex 424a4a9c1c..a6cd2194da 100644--- a/marimo/_environments/uv.py+++ b/marimo/_environments/uv.py@@ -189,6 +189,42 @@ def uv(return completed+async def uv_async(+ args: Sequence[str],+ *,+ env: Mapping[str, str] | None = None,+ cwd: str | None = None,+ timeout: float | None = None,+ on_output: Callable[[str], None] | None = None,+ on_command: Callable[[Sequence[str]], None] | None = None,+) -> subprocess.CompletedProcess[str]:+ """Await a uv command, retaining typed errors and cancellation cleanup."""+ from marimo._environments.process import run_command++ command = [find_uv_bin(), *args]+ if on_command is not None:+ on_command(command)+ try:+ completed = await run_command(+ command,+ env=env,+ cwd=cwd,+ timeout=timeout,+ on_stderr=(lambda line: _stream_output(line, on_output))+ if on_output is not None+ else None,+ )+ except OSError as error:+ if cwd is not None:+ os.stat(cwd) # noqa: ASYNC240+ if isinstance(error, FileNotFoundError):+ raise UvNotFoundError() from error+ raise+ if completed.returncode != 0:+ raise _refine(completed)+ return completed++def uv_stream(args: Sequence[str],on_output: Callable[[str], None],@@ -249,22 +285,7 @@ def uv_stream(for line in iter(process.stderr.readline, b""):stderr_lines.append(line)decoded = line.decode("utf-8", errors="replace")- # The terminal tee is best effort: a kernel replaces sys.stderr- # with a redirect whose `buffer` may be None, and nothing here- # may stop the stream or deadlock uv.- try:- buffer = getattr(sys.stderr, "buffer", None)- if buffer is not None:- buffer.write(line)- buffer.flush()- else:- sys.stderr.write(decoded)- except Exception:- pass- try:- on_output(decoded)- except Exception:- LOGGER.exception("Failed to stream uv output")+ _stream_output(decoded, on_output)returncode = process.wait()except BaseException:kill_subprocess(process, start_new_session=True)@@ -284,6 +305,23 @@ def uv_stream(return completed+def _stream_output(line: str, on_output: Callable[[str], None]) -> None:+ # Kernel stderr may be redirected; reporting must never stop pipe reads.+ try:+ buffer = getattr(sys.stderr, "buffer", None)+ if buffer is not None:+ buffer.write(line.encode("utf-8"))+ buffer.flush()+ else:+ sys.stderr.write(line)+ except Exception:+ pass+ try:+ on_output(line)+ except Exception:+ LOGGER.exception("Failed to stream uv output")++def script_command_env() -> dict[str, str]:"""Environment for uv script commands.diff --git a/marimo/_export/file.py b/marimo/_export/file.pyindex d2c03a43c9..18ce6ec5fc 100644--- a/marimo/_export/file.py+++ b/marimo/_export/file.py@@ -652,7 +652,7 @@ async def run_notebook(# Create a sessionsession_consumer = RunUntilCompletionSessionConsumer()- session = SessionImpl.create(+ session = await SessionImpl.create(# Any initialization ID will doinitialization_id="_any_",session_consumer=session_consumer,diff --git a/marimo/_messaging/notification.py b/marimo/_messaging/notification.pyindex fb0bcf2800..8a8f6ff46e 100644--- a/marimo/_messaging/notification.py+++ b/marimo/_messaging/notification.py@@ -37,6 +37,7 @@ from marimo._messaging.notebook.changes import Transactionfrom marimo._plugins.core.web_component import JSONTypefrom marimo._runtime.layout.layout import LayoutConfigfrom marimo._secrets.models import SecretKeysWithProvider+from marimo._session.model import StartupPhasefrom marimo._sql.parse import SqlCatalogCheckResult, SqlParseResultfrom marimo._types.ids import (CellId_t,@@ -565,6 +566,13 @@ class BannerNotification(Notification, tag="banner"):action: Literal["restart"] | None = None+class StartupProgressNotification(Notification, tag="startup-progress"):+ """Progress reported before a session's kernel is ready."""++ name: ClassVar[str] = "startup-progress"+ phase: StartupPhase++class KernelStartupErrorNotification(Notification, tag="kernel-startup-error"):"""Kernel failed to start.@@ -1018,6 +1026,7 @@ NotificationMessage = (| MissingPackageAlertNotification| InstallingPackageAlertNotification| StartupLogsNotification+ | StartupProgressNotification| KernelStartupErrorNotification# Variables| VariablesNotificationdiff --git a/marimo/_server/api/endpoints/assets.py b/marimo/_server/api/endpoints/assets.pyindex 448c1f89a0..3ed8bc653f 100644--- a/marimo/_server/api/endpoints/assets.py+++ b/marimo/_server/api/endpoints/assets.py@@ -19,7 +19,6 @@ from starlette.responses import (from starlette.staticfiles import StaticFilesfrom marimo import _loggers-from marimo._cli.sandbox import SandboxModefrom marimo._config.manager import get_default_config_managerfrom marimo._config.reader import find_nearest_pyproject_tomlfrom marimo._config.settings import GLOBAL_SETTINGS@@ -390,11 +389,11 @@ async def index(request: Request) -> Response:absolute_filepath = app_manager.filename# Pre-compute notebook snapshot for faster initial render- # Only in EDIT + SandboxMode.MULTI where each notebook gets its own IPC+ # Only in sandboxed edit mode where each notebook gets its own IPC# kernel.notebook_snapshot = Noneif (- app_state.session_manager.sandbox_mode is SandboxMode.MULTI+ app_state.session_manager.sandboxand app_state.mode == SessionMode.EDITand app_manager.filename):diff --git a/marimo/_server/api/endpoints/editing.py b/marimo/_server/api/endpoints/editing.pyindex 5bc53faa4d..038400b6af 100644--- a/marimo/_server/api/endpoints/editing.py+++ b/marimo/_server/api/endpoints/editing.py@@ -5,7 +5,6 @@ from typing import TYPE_CHECKINGfrom starlette.authentication import requires-from marimo._cli.sandbox import SandboxModefrom marimo._messaging.notification import FocusCellNotificationfrom marimo._server.api.deps import AppStatefrom marimo._server.api.utils import (@@ -149,15 +148,11 @@ async def format_cell(request: Request) -> FormatResponse:codes = await formatter.format(body.codes, filename)return FormatResponse(codes)except ModuleNotFoundError:- # In multi-sandbox mode each kernel has its own venv, so installing- # ruff into the server wouldn't help the kernel. Just surface the- # error without an install prompt.- if app_state.session_manager.sandbox_mode is SandboxMode.MULTI:+ # Sandboxed kernels cannot install the server's formatter.+ if app_state.session_manager.sandbox:raise ModuleNotFoundError("Server does not have a formatter. Please install ruff") from None- # For single-sandbox and non-sandbox modes the server *is* the- # formatting environment, so offer to install ruff there.notify_server_missing_packages(app_state.get_current_session(),app_state.get_current_session_id(),diff --git a/marimo/_server/api/endpoints/execution.py b/marimo/_server/api/endpoints/execution.pyindex fa8e418f96..b6d68a9f67 100644--- a/marimo/_server/api/endpoints/execution.py+++ b/marimo/_server/api/endpoints/execution.py@@ -557,8 +557,8 @@ async def shutdown(session_manager = app_state.session_managerworkspace = session_manager.workspace- def shutdown_server() -> None:- app_state.session_manager.shutdown()+ async def shutdown_server() -> None:+ await app_state.session_manager.shutdown()close_uvicorn(app_state.server)# If we are only operating on a single file (new or explicit file),@@ -566,18 +566,18 @@ async def shutdown(# from the file explorer) then we should shutdown the whole serverkey = workspace.get_unique_file_key()if key and len(session_manager.sessions) <= 1:- shutdown_server()+ await shutdown_server()return SuccessResponse()# Otherwise, get the sessionsession_id = app_state.get_current_session_id()if not session_id:- shutdown_server()+ await shutdown_server()return SuccessResponse()was_shutdown = session_manager.close_session(session_id)if not was_shutdown:- shutdown_server()+ await shutdown_server()return SuccessResponse()diff --git a/marimo/_server/api/endpoints/packages.py b/marimo/_server/api/endpoints/packages.pyindex 567e9da2db..5a22b2cf6b 100644--- a/marimo/_server/api/endpoints/packages.py+++ b/marimo/_server/api/endpoints/packages.py@@ -7,6 +7,13 @@ from typing import TYPE_CHECKINGfrom starlette.authentication import requiresfrom marimo._config.settings import GLOBAL_SETTINGS+from marimo._environments import script_metadata+from marimo._environments.backends import current_backend+from marimo._environments.errors import (+ EnvironmentManagerError,+ SandboxRestartRequired,+)+from marimo._environments.sandbox import Backend, NotebookSandboxfrom marimo._runtime.packages.package_manager import PackageManagerfrom marimo._runtime.packages.package_managers import create_package_managerfrom marimo._runtime.packages.sandbox_package_manager import (@@ -24,8 +31,13 @@ from marimo._server.models.packages import (PackageOperationResponse,RemovePackageRequest,SandboxPackageContext,+ SandboxRequest,+ SandboxResponse,+ SyncSandboxResponse,+ UpdateManifestRequest,)from marimo._server.router import APIRouter+from marimo._utils.http import HTTPExceptionif TYPE_CHECKING:from starlette.requests import Request@@ -217,14 +229,10 @@ def _get_package_manager(request: Request) -> PackageManager:# Check if IPC mode - use kernel's venv Pythonpython_exe: str | None = None- script_path: str | None = None- sandbox_environment = Nonefrom marimo._session.managers.ipc import IPCKernelManagerImplfrom marimo._session.session import SessionImplif isinstance(session, SessionImpl):- from marimo._environments.sandbox import NotebookSandbox-sandbox = session.notebook_sandboxif isinstance(sandbox, NotebookSandbox):return SandboxPackageManager(sandbox)@@ -232,19 +240,10 @@ def _get_package_manager(request: Request) -> PackageManager:kernel_manager = session._kernel_managerif isinstance(kernel_manager, IPCKernelManagerImpl):python_exe = kernel_manager.venv_python- if kernel_manager.script_environment is not None:- # The kernel runs in the notebook's script environment;- # package changes edit the manifest and synchronize it.- script_path = session.app_file_manager.filename- sandbox_environment = kernel_manager.script_environment- elif GLOBAL_SETTINGS.SANDBOX_MODE == "single":- script_path = session.app_file_manager.filenamereturn create_package_manager(config_manager.package_manager,python_exe=python_exe,- script_path=script_path,- sandbox_environment=sandbox_environment,)@@ -261,3 +260,148 @@ def _get_filename(request: Request) -> str | None:if session is None:return Nonereturn session.app_file_manager.filename+++def _sandbox_source(+ request: Request, file_key: str | None, *, mutation: bool = False+) -> tuple[NotebookSandbox | None, str | None, Backend | None]:+ state = AppState(request)+ manager = state.session_manager+ if mutation and manager.is_session_starting(+ state.require_current_session_id()+ ):+ raise HTTPException(409, "Wait for sandbox preparation to finish.")+ session = state.get_current_session()+ if session is not None:+ sandbox = getattr(session, "notebook_sandbox", None)+ if isinstance(sandbox, NotebookSandbox):+ return sandbox, sandbox.source, sandbox.backend+ return None, None, None+ if not manager.sandbox:+ return None, None, None+ key = file_key or manager.workspace.get_unique_file_key()+ path = manager.workspace.resolve(key) if key else None+ return None, path, current_backend()++[email protected]("/sandbox")+@requires("edit")+async def get_sandbox(request: Request) -> SandboxResponse:+ """+ parameters:+ - in: header+ name: Marimo-Session-Id+ schema:+ type: string+ required: true+ requestBody:+ required: true+ content:+ application/json:+ schema:+ $ref: "#/components/schemas/SandboxRequest"+ responses:+ 200:+ description: Sandbox manifest, available before kernel startup+ content:+ application/json:+ schema:+ $ref: "#/components/schemas/SandboxResponse"+ """+ body = await parse_request(request, cls=SandboxRequest)+ _, path, backend = _sandbox_source(request, body.file_key)+ try:+ manifest = (+ await asyncio.to_thread(script_metadata.read_manifest, path)+ if path is not None+ else None+ )+ except (OSError, ValueError, EnvironmentManagerError) as error:+ raise HTTPException(400, str(error)) from error+ return SandboxResponse(backend=backend, manifest=manifest, filename=path)++[email protected]("/manifest")+@requires("edit")+async def update_manifest(request: Request) -> SandboxResponse:+ """+ parameters:+ - in: header+ name: Marimo-Session-Id+ schema:+ type: string+ required: true+ requestBody:+ required: true+ content:+ application/json:+ schema:+ $ref: "#/components/schemas/UpdateManifestRequest"+ responses:+ 200:+ description: Save notebook metadata without changing its cells+ content:+ application/json:+ schema:+ $ref: "#/components/schemas/SandboxResponse"+ """+ body = await parse_request(request, cls=UpdateManifestRequest)+ _, path, backend = _sandbox_source(request, body.file_key, mutation=True)+ if path is None or backend is None:+ raise HTTPException(400, "No notebook manifest is available to edit.")+ try:+ manifest = await asyncio.to_thread(+ script_metadata.write_manifest,+ path,+ body.contents,+ previous=body.previous,+ )+ except script_metadata.ManifestConflictError as error:+ raise HTTPException(409, str(error)) from error+ except (OSError, ValueError, EnvironmentManagerError) as error:+ raise HTTPException(400, str(error)) from error+ return SandboxResponse(backend=backend, manifest=manifest, filename=path)++[email protected]("/sync")+@requires("edit")+async def sync_sandbox(request: Request) -> SyncSandboxResponse:+ """+ parameters:+ - in: header+ name: Marimo-Session-Id+ schema:+ type: string+ required: true+ requestBody:+ required: true+ content:+ application/json:+ schema:+ $ref: "#/components/schemas/SandboxRequest"+ responses:+ 200:+ description: Apply the saved manifest, or reconnect to retry startup+ content:+ application/json:+ schema:+ $ref: "#/components/schemas/SyncSandboxResponse"+ """+ body = await parse_request(request, cls=SandboxRequest)+ sandbox, _, backend = _sandbox_source(+ request, body.file_key, mutation=True+ )+ if backend is None:+ raise HTTPException(400, "This notebook does not use a sandbox.")+ if sandbox is None:+ # Connection creation owns provisioning and streams its progress.+ return SyncSandboxResponse(success=True, reconnect=True)+ try:+ await sandbox.sync_async()+ except SandboxRestartRequired as error:+ return SyncSandboxResponse(+ success=False, error=str(error), restart_required=True+ )+ except (EnvironmentManagerError, OSError) as error:+ return SyncSandboxResponse(success=False, error=str(error))+ return SyncSandboxResponse(success=True)diff --git a/marimo/_server/api/endpoints/ws/session_handler.py b/marimo/_server/api/endpoints/ws/session_handler.pyindex 400645b4c8..5989001c81 100644--- a/marimo/_server/api/endpoints/ws/session_handler.py+++ b/marimo/_server/api/endpoints/ws/session_handler.py@@ -5,6 +5,7 @@ from __future__ import annotationsimport abcimport asyncio+from contextlib import asynccontextmanagerfrom typing import TYPE_CHECKINGfrom marimo import _loggers@@ -15,12 +16,19 @@ from marimo._messaging.notification import (BannerNotification,NotificationMessage,ReconnectedNotification,+ StartupProgressNotification,+)+from marimo._messaging.serde import (+ deserialize_kernel_notification_name,+ serialize_kernel_message,)-from marimo._messaging.serde import serialize_kernel_messagefrom marimo._server.api.endpoints.ws.ws_kernel_ready import (build_kernel_ready,is_rtc_available,)+from marimo._server.api.endpoints.ws.ws_message_loop import (+ prepare_wire_message,+)from marimo._server.api.endpoints.ws.ws_session_connector import (SessionConnector,is_viewer_connection,@@ -29,10 +37,10 @@ from marimo._server.codes import WebSocketCloseReason, WebSocketCodesfrom marimo._session.consumer import SessionConsumerfrom marimo._session.model import ConnectionState, SessionModefrom marimo._types.ids import ConsumerId+from marimo._utils.asyncio_utils import cancel_and_waitif TYPE_CHECKING:- from collections.abc import Callable- from typing import Any+ from collections.abc import AsyncGenerator, AsyncIteratorfrom starlette.requests import HTTPConnection@@ -77,11 +85,16 @@ class SessionHandler(SessionConsumer, abc.ABC):self.params = paramsself.mode = modeself.doc_manager = doc_manager- self.status: ConnectionState+ self.status = ConnectionState.CONNECTING+ self._session: Session | None = Noneself.cancel_close_handle: asyncio.TimerHandle | None = None# Messages from the kernel are put in this queue# to be sent to the frontendself.message_queue: asyncio.Queue[KernelMessage] = asyncio.Queue()+ # Startup precedes session attachment and its viewer filtering.+ self._startup_queue: asyncio.Queue[KernelMessage | None] | None = (+ asyncio.Queue()+ )self._consumer_id = ConsumerId(params.session_id)@property@@ -107,7 +120,21 @@ class SessionHandler(SessionConsumer, abc.ABC):# Shared session lifecycle- def _connect_session(+ @asynccontextmanager+ async def _connection_lifetime(+ self, connection: HTTPConnection+ ) -> AsyncIterator[asyncio.Task[tuple[Session, ConnectionType]]]:+ """Own attachment through startup, progress delivery, and streaming."""+ startup = asyncio.create_task(self._connect_session(connection))+ try:+ yield startup+ finally:+ try:+ await cancel_and_wait(startup)+ finally:+ self._on_disconnect()++ async def _connect_session(self, connection: HTTPConnection) -> tuple[Session, ConnectionType]:"""Connect this handler to a session (new, resume, reconnect, ...).@@ -117,12 +144,53 @@ class SessionHandler(SessionConsumer, abc.ABC):WebSocketDisconnect: If the connection is rejected; carries theclose code and reason."""- return SessionConnector(- manager=self.manager,- handler=self,- params=self.params,- connection=connection,- ).connect()+ startup = asyncio.create_task(+ SessionConnector(+ manager=self.manager,+ handler=self,+ params=self.params,+ connection=connection,+ ).connect()+ )+ disconnected = asyncio.create_task(self._wait_for_disconnect())+ try:+ done, _ = await asyncio.wait(+ (startup, disconnected), return_when=asyncio.FIRST_COMPLETED+ )+ if disconnected in done:+ await disconnected+ await cancel_and_wait(startup)+ raise asyncio.CancelledError+ return await startup+ finally:+ await cancel_and_wait(disconnected)+ await cancel_and_wait(startup)++ @abc.abstractmethod+ async def _wait_for_disconnect(self) -> None:+ """Notice a closed transport even while a session is starting."""++ async def _startup_messages(+ self, startup: asyncio.Task[tuple[Session, ConnectionType]]+ ) -> AsyncGenerator[str, None]:+ """Send progress before session messages, including before failure."""+ queue = self._startup_queue+ assert queue is not None++ def finished(+ _task: asyncio.Task[tuple[Session, ConnectionType]],+ ) -> None:+ queue.put_nowait(None)++ startup.add_done_callback(finished)+ try:+ while (data := await queue.get()) is not None:+ text = prepare_wire_message(data, is_kiosk=self.params.kiosk)+ if text is not None:+ yield text+ finally:+ startup.remove_done_callback(finished)+ self._startup_queue = Nonedef _is_viewer(self, session: Session, connection_type: ConnectionType@@ -134,7 +202,14 @@ class SessionHandler(SessionConsumer, abc.ABC):)def notify(self, notification: KernelMessage) -> None:- self.message_queue.put_nowait(notification)+ if (+ self._startup_queue is not None+ and deserialize_kernel_notification_name(notification)+ == StartupProgressNotification.name+ ):+ self._startup_queue.put_nowait(notification)+ else:+ self.message_queue.put_nowait(notification)def _serialize_and_notify(self, notification: NotificationMessage) -> None:self.notify(serialize_kernel_message(notification))@@ -281,24 +356,19 @@ class SessionHandler(SessionConsumer, abc.ABC):LOGGER.debug("Replaying notification %s", notif)self._serialize_and_notify(notif)- def _on_disconnect(- self,- e: Exception,- cleanup_fn: Callable[[], Any],- ) -> None:+ def _on_disconnect(self) -> None:+ session = self._session+ if session is None:+ returnLOGGER.debug(- "Connection closed for session %s with exception %s, type %s",+ "Connection closed for session %s",self.params.session_id,- str(e),- type(e),)# Change the statusself.status = ConnectionState.CLOSED# Disconnect the consumer- session = self.manager.get_session(self.params.session_id)- if session:- session.disconnect_consumer(self)+ session.disconnect_consumer(self)# When the connection is closed, we wait session.ttl_seconds before# closing the session. This prevents the session from being closed@@ -330,27 +400,18 @@ class SessionHandler(SessionConsumer, abc.ABC):"Closing session %s (TTL EXPIRED)",self.params.session_id,)- # wait until TTL is expired before calling the cleanup- # function- cleanup_fn()self.manager.close_session(self.params.session_id)- if session is not None:- cancellation_handle = asyncio.get_running_loop().call_later(- session.ttl_seconds, _close- )- self.cancel_close_handle = cancellation_handle- else:- _close()- else:- cleanup_fn()+ self.cancel_close_handle = asyncio.get_running_loop().call_later(+ session.ttl_seconds, _close+ )def on_attach(self, session: Session, event_bus: SessionEventBus) -> None:- del sessiondel event_bus- return+ self._session = sessiondef on_detach(self) -> None:+ self._session = None# If the transport is open, send a close messageis_connected = (self.status == ConnectionState.OPENdiff --git a/marimo/_server/api/endpoints/ws/sse_handler.py b/marimo/_server/api/endpoints/ws/sse_handler.pyindex eb4e923ccb..3aa2c8c3a0 100644--- a/marimo/_server/api/endpoints/ws/sse_handler.py+++ b/marimo/_server/api/endpoints/ws/sse_handler.py@@ -23,6 +23,7 @@ from __future__ import annotationsimport asyncioimport enum+from contextlib import aclosingfrom typing import TYPE_CHECKING, Union, castfrom starlette.websockets import WebSocketDisconnect@@ -126,66 +127,76 @@ class SSESessionHandler(SessionHandler):(shutdown, takeover); ends without one on client disconnect."""try:- session, connection_type = self._connect_session(self.request)- except KernelStartupError as e:- LOGGER.error("Kernel startup failed: %s", e)- yield format_sse_event(- serialize_notification_for_wire(- KernelStartupErrorNotification(error=str(e))- )- )- yield format_close_event(- WebSocketCodes.UNEXPECTED_ERROR,- WebSocketCloseReason.KERNEL_STARTUP_ERROR,- )- return- except WebSocketDisconnect as e:- # SessionConnector signals connection rejections (e.g. kiosk- # not allowed) with WebSocketDisconnect regardless of- # transport.- yield format_close_event(e.code, e.reason or "")- return-- LOGGER.debug(- "Connected to session %s with type %s",- session.initialization_id,- connection_type,- )-- disconnect_task = asyncio.create_task(self._signal_on_disconnect())- heartbeat_task = asyncio.create_task(self._heartbeat_loop())- self._check_status_update()- try:- while True:- item = await self._queue.get()- if item is _Signal.DISCONNECT:+ async with self._connection_lifetime(self.request) as startup:+ try:+ async with aclosing(+ self._startup_messages(startup)+ ) as messages:+ async for progress in messages:+ yield format_sse_event(progress)+ session, connection_type = await startup+ except asyncio.CancelledError:return- if item is _Signal.CLOSE:- if self._close_code is not None:- yield format_close_event(- self._close_code, self._close_reason or ""+ except KernelStartupError as e:+ LOGGER.error("Kernel startup failed: %s", e)+ yield format_sse_event(+ serialize_notification_for_wire(+ KernelStartupErrorNotification(error=str(e)))+ )+ yield format_close_event(+ WebSocketCodes.UNEXPECTED_ERROR,+ WebSocketCloseReason.KERNEL_STARTUP_ERROR,+ )return- if item is _Signal.HEARTBEAT:- yield HEARTBEAT_EVENT- continue- text = prepare_wire_message(- item,- is_kiosk=self._is_viewer(session, connection_type),+ except WebSocketDisconnect as e:+ # SessionConnector signals connection rejections (e.g. kiosk+ # not allowed) with WebSocketDisconnect regardless of+ # transport.+ yield format_close_event(e.code, e.reason or "")+ return++ LOGGER.debug(+ "Connected to session %s with type %s",+ session.initialization_id,+ connection_type,)- if text is not None:- yield format_sse_event(text)++ disconnect_task = asyncio.create_task(+ self._signal_on_disconnect()+ )+ heartbeat_task = asyncio.create_task(self._heartbeat_loop())+ self._check_status_update()+ try:+ while True:+ item = await self._queue.get()+ if item is _Signal.DISCONNECT:+ return+ if item is _Signal.CLOSE:+ if self._close_code is not None:+ yield format_close_event(+ self._close_code, self._close_reason or ""+ )+ return+ if item is _Signal.HEARTBEAT:+ yield HEARTBEAT_EVENT+ continue+ text = prepare_wire_message(+ item,+ is_kiosk=self._is_viewer(session, connection_type),+ )+ if text is not None:+ yield format_sse_event(text)+ finally:+ # Also runs when the client disconnects and StreamingResponse+ # cancels the generator; don't await anything cancellable here.+ disconnect_task.cancel()+ heartbeat_task.cancel()finally:- # Also runs when the client disconnects and StreamingResponse- # cancels the generator; don't await anything cancellable here.self._stream_finished = True- disconnect_task.cancel()- heartbeat_task.cancel()- if not self._close_requested:- self._on_disconnect(- ConnectionError("SSE client disconnected"),- lambda: None,- )++ async def _wait_for_disconnect(self) -> None:+ await wait_for_http_disconnect(self.request)async def _signal_on_disconnect(self) -> None:"""Signal the stream loop when the client disconnects.@@ -195,7 +206,7 @@ class SSESessionHandler(SessionHandler):to the disconnect first, the generator is cancelled and its`finally` performs the same teardown."""- await wait_for_http_disconnect(self.request)+ await self._wait_for_disconnect()self._queue.put_nowait(_Signal.DISCONNECT)async def _heartbeat_loop(self) -> None:diff --git a/marimo/_server/api/endpoints/ws/ws_message_loop.py b/marimo/_server/api/endpoints/ws/ws_message_loop.pyindex 77cc266253..e03d8b2d7b 100644--- a/marimo/_server/api/endpoints/ws/ws_message_loop.py+++ b/marimo/_server/api/endpoints/ws/ws_message_loop.py@@ -2,7 +2,7 @@from __future__ import annotationsimport asyncio-from typing import TYPE_CHECKING, Any+from typing import TYPE_CHECKINGfrom starlette.websockets import WebSocketDisconnect, WebSocketState@@ -90,16 +90,12 @@ class WebSocketMessageLoop:websocket: WebSocket,message_queue: asyncio.Queue[KernelMessage],is_kiosk: Callable[[], bool],- on_disconnect: Callable[[Exception, Callable[[], Any]], None],on_check_status_update: Callable[[], None],):self.websocket = websocketself.message_queue = message_queueself.is_kiosk = is_kiosk- self.on_disconnect = on_disconnectself.on_check_status_update = on_check_status_update- self._listen_messages_task: asyncio.Task[None] | None = None- self._listen_disconnect_task: asyncio.Task[None] | None = Noneasync def start(self) -> None:"""Start the message loops.@@ -108,17 +104,22 @@ class WebSocketMessageLoop:- listen_for_messages: Sends messages from kernel to frontend- listen_for_disconnect: Detects when WebSocket disconnects"""- self._listen_messages_task = asyncio.create_task(- self._listen_for_messages()- )- self._listen_disconnect_task = asyncio.create_task(- self._listen_for_disconnect()- )-- await asyncio.gather(- self._listen_messages_task,- self._listen_disconnect_task,+ tasks = (+ asyncio.create_task(self._listen_for_messages()),+ asyncio.create_task(self._listen_for_disconnect()),)+ try:+ done, _ = await asyncio.wait(+ tasks, return_when=asyncio.FIRST_COMPLETED+ )+ for task in done:+ task.result()+ except WebSocketDisconnect:+ pass+ finally:+ for task in tasks:+ task.cancel()+ await asyncio.gather(*tasks, return_exceptions=True)async def _listen_for_messages(self) -> None:"""Listen for messages from kernel and send to frontend."""@@ -131,9 +132,7 @@ class WebSocketMessageLoop:# Send to WebSockettry:await self.websocket.send_text(text)- except WebSocketDisconnect as e:- self.on_disconnect(e, self._cancel_disconnect_task)- except RuntimeError as e:+ except RuntimeError:# Starlette can raise a runtime error if a message is sent# when the socket is closed. In case the disconnection# error hasn't made its way to listen_for_disconnect, do@@ -142,40 +141,11 @@ class WebSocketMessageLoop:self.websocket.application_state== WebSocketState.DISCONNECTED):- self.on_disconnect(e, self._cancel_disconnect_task)- else:- LOGGER.error(- "Error sending message to frontend: %s", str(e)- )- except Exception as e:- LOGGER.error("Error sending message to frontend: %s", str(e))+ returnraiseasync def _listen_for_disconnect(self) -> None:"""Listen for WebSocket disconnect."""- try:- # Check for marimo updates when connection starts- self.on_check_status_update()- # Wait for disconnection+ self.on_check_status_update()+ while True:await self.websocket.receive_text()- except WebSocketDisconnect as e:- self.on_disconnect(e, self._cancel_messages_task)- except Exception as e:- LOGGER.error("Error listening for disconnect: %s", str(e))- raise-- def _cancel_messages_task(self) -> None:- """Cancel the messages task."""- if (- self._listen_messages_task- and not self._listen_messages_task.done()- ):- self._listen_messages_task.cancel()-- def _cancel_disconnect_task(self) -> None:- """Cancel the disconnect task."""- if (- self._listen_disconnect_task- and not self._listen_disconnect_task.done()- ):- self._listen_disconnect_task.cancel()diff --git a/marimo/_server/api/endpoints/ws/ws_session_connector.py b/marimo/_server/api/endpoints/ws/ws_session_connector.pyindex b88555b051..1774a4252c 100644--- a/marimo/_server/api/endpoints/ws/ws_session_connector.py+++ b/marimo/_server/api/endpoints/ws/ws_session_connector.py@@ -68,7 +68,7 @@ class SessionConnector:self.params = paramsself.connection = connection- def connect(self) -> tuple[Session, ConnectionType]:+ async def connect(self) -> tuple[Session, ConnectionType]:"""Determine connection type and establish session connection.Returns:@@ -78,6 +78,12 @@ class SessionConnector:Raises:WebSocketDisconnect: If the connection cannot be established."""+ async with self.manager.connection_lock(+ self.params.session_id, self.params.file_key+ ):+ return await self._connect()++ async def _connect(self) -> tuple[Session, ConnectionType]:# 1. Kiosk modeif self.params.kiosk:return self._connect_kiosk()@@ -118,7 +124,7 @@ class SessionConnector:return self._resume_session(resumable)# 5. Create new session- return self._create_new_session()+ return await self._create_new_session()def _connect_kiosk(self) -> tuple[Session, ConnectionType]:"""Connect to kiosk session.@@ -196,7 +202,7 @@ class SessionConnector:"""Check if we're in run mode (read-only app mode)."""return self.manager.mode == SessionMode.RUN- def _create_new_session(self) -> tuple[Session, ConnectionType]:+ async def _create_new_session(self) -> tuple[Session, ConnectionType]:"""Create a new session.Grabs query params from the connection and creates a new session@@ -208,7 +214,7 @@ class SessionConnector:# session was created.query_params = self._extract_query_params()- new_session = self.manager.create_session(+ new_session = await self.manager.create_session(query_params=query_params.to_dict(),session_id=self.params.session_id,session_consumer=self.handler,diff --git a/marimo/_server/api/endpoints/ws_endpoint.py b/marimo/_server/api/endpoints/ws_endpoint.pyindex e1b091a65f..85b9750c5a 100644--- a/marimo/_server/api/endpoints/ws_endpoint.py+++ b/marimo/_server/api/endpoints/ws_endpoint.py@@ -3,10 +3,11 @@ from __future__ import annotationsimport asyncioimport sys+from contextlib import aclosingfrom typing import TYPE_CHECKINGfrom starlette.responses import StreamingResponse-from starlette.websockets import WebSocket, WebSocketState+from starlette.websockets import WebSocket, WebSocketDisconnect, WebSocketStatefrom marimo import _loggersfrom marimo._dependencies.dependencies import DependencyManager@@ -245,32 +246,49 @@ class WebSocketHandler(SessionHandler):)LOGGER.debug("Existing sessions: %s", self.manager.sessions)- try:- session, connection_type = self._connect_session(self.websocket)- except KernelStartupError as e:- LOGGER.error("Kernel startup failed: %s", e)- await self._close_kernel_startup_error(str(e))- return- LOGGER.debug(- "Connected to session %s with type %s",- session.initialization_id,- connection_type,- )+ async with self._connection_lifetime(self.websocket) as startup:+ try:+ async with aclosing(+ self._startup_messages(startup)+ ) as messages:+ async for text in messages:+ await self.websocket.send_text(text)+ session, connection_type = await startup+ except asyncio.CancelledError:+ await self._safe_close(WebSocketCodes.NORMAL_CLOSE, "")+ return+ except KernelStartupError as e:+ LOGGER.error("Kernel startup failed: %s", e)+ await self._close_kernel_startup_error(str(e))+ return+ except WebSocketDisconnect as e:+ await self._safe_close(e.code, e.reason or "")+ return+ LOGGER.debug(+ "Connected to session %s with type %s",+ session.initialization_id,+ connection_type,+ )- # Start message loops- message_loop = WebSocketMessageLoop(- websocket=self.websocket,- message_queue=self.message_queue,- is_kiosk=lambda: self._is_viewer(session, connection_type),- on_disconnect=self._on_disconnect,- on_check_status_update=self._check_status_update,- )+ # Start message loops+ message_loop = WebSocketMessageLoop(+ websocket=self.websocket,+ message_queue=self.message_queue,+ is_kiosk=lambda: self._is_viewer(session, connection_type),+ on_check_status_update=self._check_status_update,+ )- try:- self.ws_future = asyncio.create_task(message_loop.start())- await self.ws_future- except asyncio.CancelledError:- LOGGER.debug("Websocket terminated with CancelledError")+ try:+ self.ws_future = asyncio.create_task(message_loop.start())+ await self.ws_future+ except asyncio.CancelledError:+ LOGGER.debug("Websocket terminated with CancelledError")++ async def _wait_for_disconnect(self) -> None:+ while True:+ message = await self.websocket.receive()+ if message["type"] == "websocket.disconnect":+ returnasync def _safe_close(self, code: int, reason: str) -> None:"""Close the WebSocket, ignoring errors from uninitialized state.@@ -282,6 +300,8 @@ class WebSocketHandler(SessionHandler):"""try:await self.websocket.close(code, reason)+ except WebSocketDisconnect:+ passexcept AttributeError as e:if "transfer_data_task" not in str(e):raisediff --git a/marimo/_server/api/lifespans.py b/marimo/_server/api/lifespans.pyindex 5468a8c83d..f118aae05e 100644--- a/marimo/_server/api/lifespans.py+++ b/marimo/_server/api/lifespans.py@@ -214,16 +214,24 @@ async def signal_handler(app: Starlette) -> AsyncIterator[None]:manager = state.session_manager# Interrupt handler- def shutdown() -> None:- manager.shutdown()+ async def shutdown() -> None:+ await manager.shutdown()if state.server:close_uvicorn(state.server)+ def request_shutdown() -> None:+ supervised_task(+ shutdown(), name="server.shutdown", registry=background_tasks+ )+InterruptHandler(quiet=state.quiet,- shutdown=shutdown,+ shutdown=request_shutdown,).register()- yield+ try:+ yield+ finally:+ await manager.shutdown()@contextlib.asynccontextmanagerdiff --git a/marimo/_server/api/middleware.py b/marimo/_server/api/middleware.pyindex 1788c82321..26f38566fb 100644--- a/marimo/_server/api/middleware.py+++ b/marimo/_server/api/middleware.py@@ -719,15 +719,15 @@ class TimeoutMiddleware(BaseHTTPMiddleware):now = time.time()if now >= timeout_at:print_tabbed("Timeout due to inactivity")- self.shutdown()+ await self.shutdown()break# Sleep until 1s after the next potential activity timeoutawait asyncio.sleep(timeout_at - now + 1)- def shutdown(self) -> None:+ async def shutdown(self) -> None:manager = self.app_state.session_manager- manager.shutdown()+ await manager.shutdown()if self.app_state.server:close_uvicorn(self.app_state.server)diff --git a/marimo/_server/models/packages.py b/marimo/_server/models/packages.pyindex e95c853144..453005f74a 100644--- a/marimo/_server/models/packages.py+++ b/marimo/_server/models/packages.py@@ -33,6 +33,22 @@ class RemovePackageRequest(msgspec.Struct, rename="camel"):group: str | None = None+class SandboxRequest(msgspec.Struct, rename="camel"):+ file_key: str | None = None+++class UpdateManifestRequest(msgspec.Struct, rename="camel"):+ contents: str+ previous: str+ file_key: str | None = None+++class SandboxResponse(msgspec.Struct, rename="camel"):+ backend: Literal["uv", "pixi"] | None+ manifest: str | None+ filename: str | None++class SandboxPackageContext(msgspec.Struct,frozen=True,@@ -77,3 +93,7 @@ class PackageOperationResponse(msgspec.Struct, rename="camel"):@staticmethoddef of_failure(error: str) -> PackageOperationResponse:return PackageOperationResponse(success=False, error=error)+++class SyncSandboxResponse(PackageOperationResponse, rename="camel"):+ reconnect: bool = Falsediff --git a/marimo/_server/session_manager.py b/marimo/_server/session_manager.pyindex 70cb80b66c..c89d09e7f1 100644--- a/marimo/_server/session_manager.py+++ b/marimo/_server/session_manager.py@@ -8,11 +8,13 @@ file watching, and LSP server management.from __future__ import annotations+import asyncio+from dataclasses import dataclassfrom pathlib import Pathfrom typing import TYPE_CHECKING+from weakref import WeakValueDictionaryfrom marimo import _loggers-from marimo._cli.sandbox import SandboxModefrom marimo._config.manager import MarimoConfigManagerfrom marimo._runtime.commands import (SerializedCLIArgs,@@ -42,6 +44,7 @@ from marimo._session.file_change_handler import (from marimo._session.file_watcher_integration import (SessionFileWatcherExtension,)+from marimo._session.managers.ipc import KernelStartupErrorfrom marimo._session.model import ConnectionState, SessionModefrom marimo._session.session import Session, SessionImplfrom marimo._session.session_repository import SessionRepository@@ -58,6 +61,12 @@ if TYPE_CHECKING:LOGGER = _loggers.marimo_logger()+@dataclass+class _PendingSession:+ task: asyncio.Task[Session]+ waiters: int = 0++class SessionManager:"""Orchestrates session management@@ -83,7 +92,7 @@ class SessionManager:redirect_console_to_browser: bool,ttl_seconds: int | None,watch: bool = False,- sandbox_mode: SandboxMode | None = None,+ sandbox: bool = False,isolate_apps: bool = False,execute_opengraph_generators: bool = False,) -> None:@@ -98,7 +107,7 @@ class SessionManager:self.argv = argvself.redirect_console_to_browser = redirect_console_to_browserself._config_manager = config_manager- self.sandbox_mode = sandbox_mode+ self.sandbox = sandboxself.execute_opengraph_generators = execute_opengraph_generators# When running multiple apps, each app runs in an isolated host@@ -107,10 +116,15 @@ class SessionManager:self._app_host_pool: AppHostPool | None = Noneif isolate_apps and mode == SessionMode.RUN:self._app_host_pool = AppHostPool(- sandbox=sandbox_mode is SandboxMode.MULTI,+ sandbox=sandbox,)self._repository = SessionRepository()+ self._pending: dict[SessionId, _PendingSession] = {}+ self._connection_locks: WeakValueDictionary[str, asyncio.Lock] = (+ WeakValueDictionary()+ )+ self._closed = Falsedef _get_code() -> str:defaults = AppDefaults.from_config_manager(config_manager)@@ -170,7 +184,24 @@ class SessionManager:self.workspace.register_allowed_path(key)return self.workspace.load(key, defaults)- def create_session(+ def connection_lock(+ self, session_id: SessionId, file_key: MarimoFileKey+ ) -> asyncio.Lock:+ """Serialize reconnect decisions while a notebook is starting."""+ if self._closed:+ raise KernelStartupError("Session manager is shut down")+ key = (+ self._resolve_file_key(file_key) or file_key+ if self.mode == SessionMode.EDIT+ else session_id+ )+ lock = self._connection_locks.get(key)+ if lock is None:+ lock = asyncio.Lock()+ self._connection_locks[key] = lock+ return lock++ async def create_session(self,session_id: SessionId,session_consumer: SessionConsumer,@@ -178,13 +209,58 @@ class SessionManager:file_key: MarimoFileKey,auto_instantiate: bool,) -> Session:- """Create a new session."""- LOGGER.debug("Creating new session for id %s", session_id)-- # Check if session already exists+ """Return a ready session, retaining ownership during startup."""+ if self._closed:+ raise KernelStartupError("Session manager is shut down")existing = self._repository.get_sync(session_id)- if existing:+ if existing is not None:return existing+ pending = self._pending.get(session_id)+ if pending is None:+ task = asyncio.create_task(+ self._create_session(+ session_id,+ session_consumer,+ query_params,+ file_key,+ auto_instantiate,+ ),+ name=f"session.start.{session_id}",+ )+ pending = _PendingSession(task)+ self._pending[session_id] = pending++ def finished(task: asyncio.Task[Session]) -> None:+ self._pending.pop(session_id, None)+ # A disconnected caller may no longer be awaiting the error.+ if not task.cancelled():+ task.exception()++ task.add_done_callback(finished)+ pending.waiters += 1+ try:+ return await asyncio.shield(pending.task)+ finally:+ pending.waiters -= 1+ if pending.waiters == 0 and not pending.task.done():+ # The last disconnected caller releases its connection lock+ # only after the abandoned launch has cleaned up.+ pending.task.cancel()+ await asyncio.gather(pending.task, return_exceptions=True)++ def is_session_starting(self, session_id: SessionId) -> bool:+ return session_id in self._pending++ async def _create_session(+ self,+ session_id: SessionId,+ session_consumer: SessionConsumer,+ query_params: SerializedQueryParams,+ file_key: MarimoFileKey,+ auto_instantiate: bool,+ ) -> Session:+ """Create a new session."""+ LOGGER.debug("Creating new session for id %s", session_id)# Get app file managerdefaults = AppDefaults.from_config_manager(self._config_manager)@@ -205,7 +281,7 @@ class SessionManager:))- session = SessionImpl.create(+ session = await SessionImpl.create(initialization_id=file_key,session_consumer=session_consumer,mode=self.mode,@@ -233,7 +309,7 @@ class SessionManager:ttl_seconds=self.ttl_seconds,auto_instantiate=auto_instantiate,extensions=extensions,- sandbox_mode=self.sandbox_mode,+ sandbox=self.sandbox,app_host_context=AppHostContext(pool=self._app_host_pool, session_id=session_id)@@ -435,9 +511,14 @@ class SessionManager:self.close_session(session_id)LOGGER.debug("Closed all sessions.")- def shutdown(self) -> None:+ async def shutdown(self) -> None:"""Shutdown the session manager and stop all file watchers."""LOGGER.debug("Shutting down")+ self._closed = True+ pending = [entry.task for entry in self._pending.values()]+ for task in pending:+ task.cancel()+ await asyncio.gather(*pending, return_exceptions=True)self.close_all_sessions()if self._app_host_pool is not None:self._app_host_pool.shutdown()diff --git a/marimo/_server/start.py b/marimo/_server/start.pyindex 5cca29565b..4e49ad0270 100644--- a/marimo/_server/start.py+++ b/marimo/_server/start.py@@ -10,10 +10,10 @@ from urllib.parse import urlparseimport uvicornfrom marimo._cli.print import echo-from marimo._cli.sandbox import SandboxModefrom marimo._config.config import PartialMarimoConfigfrom marimo._config.manager import get_default_config_managerfrom marimo._config.settings import GLOBAL_SETTINGS+from marimo._environments.sandbox import Backendfrom marimo._mcp.setup import McpType, setup_mcp_serverfrom marimo._messaging.notification import StartupLogsNotificationfrom marimo._runtime.commands import SerializedCLIArgs@@ -211,7 +211,7 @@ def start(server_startup_command: str | None = None,asset_url: str | None = None,timeout: float | None = None,- sandbox_mode: SandboxMode | None = None,+ sandbox: Backend | None = None,startup_tip: CliTip | None = None,show_tracebacks: bool | None = None,execute_opengraph_generators: bool = False,@@ -221,8 +221,8 @@ def start("""import packaging.version- # In single-file sandbox mode, uv becomes our direct parent. So we- # watch the outer CLI's PID, terminating if the CLI terminates.+ # Sandboxed run commands put a launcher between the CLI and server.+ # Watch the outer CLI's PID, terminating if the CLI terminates.ancestor_pid_env = os.environ.get("MARIMO_ANCESTOR_PID")if ancestor_pid_env:try:@@ -282,6 +282,15 @@ def start("trusted directories and authentication controls.")+ if sandbox is not None:+ os.environ["MARIMO_SANDBOX_BACKEND"] = sandbox+ GLOBAL_SETTINGS.SANDBOX_BACKEND = sandbox+ if mode == SessionMode.EDIT:+ os.environ["MARIMO_MANAGE_SCRIPT_METADATA"] = "true"+ GLOBAL_SETTINGS.MANAGE_SCRIPT_METADATA = True+ os.environ["MARIMO_SANDBOX_MODE"] = "multi"+ GLOBAL_SETTINGS.SANDBOX_MODE = "multi"+if GLOBAL_SETTINGS.MANAGE_SCRIPT_METADATA:config_reader = config_reader.with_overrides({@@ -321,7 +330,7 @@ def start(auth_token=auth_token,redirect_console_to_browser=redirect_console_to_browser,watch=watch,- sandbox_mode=sandbox_mode,+ sandbox=sandbox is not None,isolate_apps=isolate_apps,execute_opengraph_generators=execute_opengraph_generators,)diff --git a/marimo/_session/_venv.py b/marimo/_session/_venv.pyindex 01c8076490..56e3413a0d 100644--- a/marimo/_session/_venv.py+++ b/marimo/_session/_venv.py@@ -12,14 +12,14 @@ in marimo's sandbox mode. It handles:from __future__ import annotationsimport os-import subprocessimport sysfrom pathlib import Pathfrom typing import TYPE_CHECKINGfrom marimo import _loggersfrom marimo._cli.print import echo-from marimo._environments.uv import UvCommandError, uv+from marimo._environments.process import run_command+from marimo._environments.uv import UvCommandError, uv_asyncfrom marimo._version import __version__if TYPE_CHECKING:@@ -123,7 +123,7 @@ def get_kernel_pythonpath() -> str:return os.pathsep.join(paths)-def has_marimo_installed(venv_python: str) -> bool:+async def has_marimo_installed(venv_python: str) -> bool:"""Check if marimo and its IPC deps are installed in the venv.Args:@@ -132,14 +132,12 @@ def has_marimo_installed(venv_python: str) -> bool:Returns:True if marimo, msgspec, and zmq can all be imported."""- result = subprocess.run(+ result = await run_command([venv_python,"-c","import marimo, msgspec, zmq; print(marimo.__version__)",],- capture_output=True,- text=True,)if result.returncode != 0:return False@@ -157,7 +155,7 @@ def has_marimo_installed(venv_python: str) -> bool:return True-def check_python_version_compatibility(venv_python: str) -> bool:+async def check_python_version_compatibility(venv_python: str) -> bool:"""Check if venv Python version matches current Python.Binary dependencies (pyzmq, msgspec) aren't cross-version compatible,@@ -169,14 +167,12 @@ def check_python_version_compatibility(venv_python: str) -> bool:Returns:True if versions match, False otherwise."""- result = subprocess.run(+ result = await run_command([venv_python,"-c","import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')",],- capture_output=True,- text=True,)venv_version = result.stdout.strip()current_version = f"{sys.version_info.major}.{sys.version_info.minor}"@@ -184,7 +180,7 @@ def check_python_version_compatibility(venv_python: str) -> bool:return venv_version == current_version-def install_marimo_into_venv(venv_python: str) -> None:+async def install_marimo_into_venv(venv_python: str) -> None:"""Install marimo into a venv.Args:@@ -195,7 +191,7 @@ def install_marimo_into_venv(venv_python: str) -> None:echo("Installing marimo into configured venv...", err=True)try:- uv(["pip", "install", "--python", venv_python] + packages)+ await uv_async(["pip", "install", "--python", venv_python] + packages)except UvCommandError as e:LOGGER.warning(f"Failed to install marimo into configured venv: {e.stderr}"diff --git a/marimo/_session/consumer.py b/marimo/_session/consumer.pyindex 02d103059a..6f5209d43a 100644--- a/marimo/_session/consumer.py+++ b/marimo/_session/consumer.py@@ -25,7 +25,9 @@ class SessionConsumer(ABC, SessionExtension):def consumer_id(self) -> ConsumerId: ...@abstractmethod- def notify(self, notification: KernelMessage) -> None: ...+ def notify(self, notification: KernelMessage) -> None:+ """Enqueue a notification, including startup progress before attach."""+ ...@abstractmethoddef connection_state(self) -> ConnectionState: ...diff --git a/marimo/_session/managers/app_host.py b/marimo/_session/managers/app_host.pyindex 84a1b21280..2a4f89b8cb 100644--- a/marimo/_session/managers/app_host.py+++ b/marimo/_session/managers/app_host.py@@ -175,7 +175,7 @@ class AppHostKernelManager(KernelManager):self.kernel_task: ProcessLike | threading.Thread | None = None- def start_kernel(self) -> None:+ async def start_kernel(self) -> None:response = self._app_host.create_kernel(session_id=self._session_id,configs=self._configs,diff --git a/marimo/_session/managers/ipc.py b/marimo/_session/managers/ipc.pyindex 09688c150a..f970edfef2 100644--- a/marimo/_session/managers/ipc.py+++ b/marimo/_session/managers/ipc.py@@ -7,24 +7,21 @@ via ZeroMQ channels. Each notebook gets its own sandboxed virtual environment.from __future__ import annotations+import asyncioimport os-import queueimport signalimport subprocessimport sysimport threading-import timefrom collections import dequefrom pathlib import Pathfrom typing import TYPE_CHECKING, castfrom uuid import uuid4from marimo import _loggers-from marimo._cli.sandbox import SandboxModefrom marimo._config.config import VenvConfigfrom marimo._config.manager import MarimoConfigReaderfrom marimo._config.settings import GLOBAL_SETTINGS-from marimo._environments.environment import Environmentfrom marimo._environments.overlay import runtime_overlayfrom marimo._messaging.types import KernelMessagefrom marimo._runtime import commands@@ -40,17 +37,22 @@ from marimo._session.queue import ProcessLike, QueueType, route_control_requestfrom marimo._session.types import KernelManager, QueueManagerfrom marimo._utils.subprocess import (interrupt_kernel_process,+ stop_subprocess,try_kill_process_and_group,)from marimo._utils.typed_connection import TypedConnectionif TYPE_CHECKING:+ from collections.abc import Callable+ from typing import Literal+from marimo._ast.cell import CellConfigfrom marimo._environments.sandbox import NotebookSandboxfrom marimo._ipc.queue_manager import QueueManager as IPCQueueManagerTypefrom marimo._ipc.types import ConnectionInfofrom marimo._runtime.commands import AppMetadatafrom marimo._runtime.virtual_file.storage import VirtualFileStorageType+ from marimo._session.model import StartupPhasefrom marimo._types.ids import CellId_tLOGGER = _loggers.marimo_logger()@@ -276,7 +278,7 @@ class IPCKernelManagerImpl(KernelManager):app_metadata: AppMetadata,config_manager: MarimoConfigReader,redirect_console_to_browser: bool = True,- sandbox_mode: SandboxMode = SandboxMode.MULTI,+ on_progress: Callable[[StartupPhase], None] | None = None,) -> None:self.queue_manager = queue_managerself.connection_info = connection_info@@ -285,31 +287,24 @@ class IPCKernelManagerImpl(KernelManager):self.app_metadata = app_metadataself.config_manager = config_managerself.redirect_console_to_browser = redirect_console_to_browser- self.sandbox_mode = sandbox_mode+ self._on_progress = on_progressself._process: subprocess.Popen[bytes] | None = None+ self._start_new_session = Falseself.kernel_task: ProcessLike | None = Noneself._venv_python: str | None = Noneself._profile_path = _profile_path_for(app_metadata.filename)- self._script_environment: Environment | None = Noneself._notebook_sandbox: NotebookSandbox | None = None# The kernel's own pid: a launcher such as uv may sit between the# manager and the kernel, so _process.pid is not the kernel.self._kernel_pid: int | None = None- @property- def script_environment(self) -> Environment | None:- """The synchronized script environment the kernel runs in, if any."""- if self._notebook_sandbox is not None:- return self._notebook_sandbox.environment- return self._script_environment-@propertydef notebook_sandbox(self) -> NotebookSandbox | None:"""The session-owned notebook sandbox, if this kernel uses one."""return self._notebook_sandbox- def start_kernel(self) -> None:+ async def start_kernel(self) -> None:from marimo._cli.print import echo, mutedfrom marimo._ipc.types import KernelArgs@@ -326,16 +321,12 @@ class IPCKernelManagerImpl(KernelManager):virtual_file_storage=_virtual_file_storage(),)+ if self._on_progress is not None:+ self._on_progress("preparing-environment")venv_config = _get_venv_config(self.config_manager)try:- # SINGLE already selected its script environment at the CLI.- # Preserve that precedence when changing its kernel transport.- configured_python = (- get_configured_venv_python(- venv_config, base_path=self.app_metadata.filename- )- if self.sandbox_mode is SandboxMode.MULTI- else None+ configured_python = get_configured_venv_python(+ venv_config, base_path=self.app_metadata.filename)except ValueError as e:raise KernelStartupError(str(e)) from e@@ -361,14 +352,14 @@ class IPCKernelManagerImpl(KernelManager):# environment can spawn a marimo kernel.if writable:try:- install_marimo_into_venv(venv_python)+ await install_marimo_into_venv(venv_python)except Exception as e:raise KernelStartupError(f"Failed to install marimo into configured venv.\n\n{e}") from e- elif not has_marimo_installed(venv_python):+ elif not await has_marimo_installed(venv_python):# Check Python version compatibility for binary deps- if not check_python_version_compatibility(venv_python):+ if not await check_python_version_compatibility(venv_python):# If we have gotten to this point# - We have a prescribed venv# - The venv is not writable@@ -410,13 +401,9 @@ class IPCKernelManagerImpl(KernelManager):kernel_args_list = ["-m", "marimo._ipc.launch_kernel"]overlay = runtime_overlay()filename = self.app_metadata.filename- sandbox = (- NotebookSandbox.from_running_process(None, backend)- if filename is None and self.sandbox_mode is SandboxMode.SINGLE- else NotebookSandbox(filename, backend)- )+ sandbox = NotebookSandbox(filename, backend)try:- plan = sandbox.launch(+ plan = await sandbox.launch_async(kernel_args_list,overlay=overlay,base_env=os.environ.copy(),@@ -427,6 +414,9 @@ class IPCKernelManagerImpl(KernelManager):raise KernelStartupError(f"Failed to build sandbox environment.\n\n{e}") from e+ except BaseException:+ sandbox.close()+ raisehandle = sandbox.environmentif handle is None:sandbox.close()@@ -436,7 +426,6 @@ class IPCKernelManagerImpl(KernelManager):self._notebook_sandbox = sandboxself._venv_python = handle.python- self._script_environment = handleecho(f"Running kernel in script environment: {muted(handle.root)}",err=True,@@ -445,22 +434,26 @@ class IPCKernelManagerImpl(KernelManager):plan_launched = Trueenv = plan.envenv["MARIMO_MANAGE_SCRIPT_METADATA"] = "true"- env["MARIMO_SANDBOX_MODE"] = self.sandbox_mode.value+ env["MARIMO_SANDBOX_MODE"] = "multi"env["MARIMO_SANDBOX_BACKEND"] = backendcmd = list(plan.argv)+ self._start_new_session = (+ plan.start_new_session if plan_launched else False+ )LOGGER.debug(f"Launching kernel: {' '.join(cmd)}")+ handshake: asyncio.Future[list[str]] | None = Nonetry:- self._process = subprocess.Popen(+ if self._on_progress is not None:+ self._on_progress("starting-kernel")+ self._process = subprocess.Popen( # noqa: ASYNC220 — owns the child before yieldingcmd,stdin=subprocess.PIPE,stdout=subprocess.PIPE,stderr=subprocess.PIPE,env=env,- start_new_session=(- plan.start_new_session if plan_launched else False- ),+ start_new_session=self._start_new_session,)# Drain the kernel's stderr from the very start: uv resolves@@ -468,52 +461,100 @@ class IPCKernelManagerImpl(KernelManager):# pipe before the kernel ever prints KERNEL_READY,# deadlocking startup. Tee to the server's stderr as the# kernel's console, keeping a tail for startup diagnostics.- stderr_pipe = self._process.stderr+ process = self._processstderr_tail: deque[bytes] = deque(maxlen=64)- def drain_stderr() -> None:- assert stderr_pipe is not None- for line in iter(stderr_pipe.readline, b""):- stderr_tail.append(line)- try:- sys.stderr.buffer.write(line)- sys.stderr.buffer.flush()- except Exception:- pass- stderr_pipe.close()-- threading.Thread(target=drain_stderr, daemon=True).start()-- # Send connection info via stdin- assert self._process.stdin is not None- self._process.stdin.write(kernel_args.encode_json())- self._process.stdin.flush()- self._process.stdin.close()-- # Read the handshake on a thread so the wait can be bounded- # and can notice a child that dies without printing it.- # Plan-launched kernels run the overlay-pinned marimo, so- # the KERNEL_INFO line is guaranteed; a configured venv may- # run an older marimo that never prints it, and reading a- # second line would hang its startup.- stdout_pipe = self._process.stdout- assert stdout_pipe is not None+ def drain_output(stream: Literal["stdout", "stderr"]) -> None:+ pipe = process.stderr if stream == "stderr" else process.stdout+ assert pipe is not None+ with pipe:+ for line in iter(pipe.readline, b""):+ if stream == "stderr":+ stderr_tail.append(line)+ try:+ output = getattr(sys, stream).buffer+ output.write(line)+ output.flush()+ except Exception:+ pass++ threading.Thread(+ target=drain_output, args=("stderr",), daemon=True+ ).start()++ # Pipe I/O stays on a thread for Windows selector loops. EOF+ # wakes the awaiter just like a handshake; no liveness polling.expected_lines = 2 if plan_launched else 1- handshake: queue.Queue[str] = queue.Queue()-- def read_handshake() -> None:- for _ in range(expected_lines):- line = stdout_pipe.readline()- if not line:- return- handshake.put(line.decode().strip())- threading.Thread(target=read_handshake, daemon=True).start()-- deadline = time.monotonic() + _startup_timeout()- ready = self._await_handshake_line(- handshake, deadline, stderr_tail, cmd- )+ def exchange_handshake() -> list[str]:+ assert process.stdin is not None+ assert process.stdout is not None+ with process.stdin:+ process.stdin.write(kernel_args.encode_json())+ process.stdin.flush()+ try:+ lines = [+ process.stdout.readline().decode().strip()+ for _ in range(expected_lines)+ ]+ finally:+ # Notebook subprocesses can inherit this pipe for stdout.+ # Keep draining it without occupying an executor worker+ # for the kernel's lifetime.+ threading.Thread(+ target=drain_output, args=("stdout",), daemon=True+ ).start()+ if not all(lines):+ process.wait()+ return lines++ loop = asyncio.get_running_loop()+ handshake = loop.run_in_executor(None, exchange_handshake)+ exited: asyncio.Future[int] = loop.create_future()++ def report_exit(code: int) -> None:+ if not exited.done():+ exited.set_result(code)++ def watch_exit() -> None:+ code = process.wait()+ try:+ loop.call_soon_threadsafe(report_exit, code)+ except RuntimeError:+ pass # The server's event loop has already closed.++ # A descendant can retain the launcher's pipes after it exits.+ # Watch exit separately so that case fails promptly too. This+ # daemon must not occupy an executor worker for the kernel's life.+ threading.Thread(target=watch_exit, daemon=True).start()+ try:+ done, _ = await asyncio.wait(+ (handshake, exited),+ timeout=_startup_timeout(),+ return_when=asyncio.FIRST_COMPLETED,+ )+ if not done:+ raise asyncio.TimeoutError+ if handshake not in done:+ # Let the reader finish lines printed immediately before+ # exit, but don't wait on pipes inherited by descendants.+ try:+ await asyncio.wait_for(asyncio.shield(handshake), 0.5)+ except asyncio.TimeoutError:+ raise KernelStartupError(+ f"Kernel exited during startup (exit code {exited.result()})."+ ) from None+ lines = handshake.result()+ finally:+ exited.cancel()+ if not all(lines):+ raise KernelStartupError(+ f"Kernel exited during startup "+ f"(exit code {process.returncode}).\n\n"+ f"Command: {' '.join(cmd)}\n\n"+ f"Stderr:\n{_decode_tail(stderr_tail)}"+ )+ ready = lines[0]if ready != "KERNEL_READY":raise KernelStartupError(f"Kernel failed to start.\n\n"@@ -522,9 +563,7 @@ class IPCKernelManagerImpl(KernelManager):)if plan_launched:- info = self._await_handshake_line(- handshake, deadline, stderr_tail, cmd- )+ info = lines[1]kernel_pid, kernel_executable = _parse_kernel_info(info)self._kernel_pid = kernel_pidif self._venv_python is None and kernel_executable is not None:@@ -537,74 +576,39 @@ class IPCKernelManagerImpl(KernelManager):# Create a ProcessLike wrapper for the subprocessself.kernel_task = _SubprocessWrapper(self._process)+ except asyncio.TimeoutError as e:+ raise KernelStartupError(+ f"Kernel did not become ready within {_startup_timeout():.0f}s "+ f"(override with MARIMO_KERNEL_STARTUP_TIMEOUT).\n\n"+ f"Command: {' '.join(cmd)}\n\n"+ f"Stderr:\n{_decode_tail(stderr_tail)}"+ ) from eexcept KernelStartupError:- self._cleanup_failed_start()raiseexcept Exception as e:- self._cleanup_failed_start()# Wrap other exceptions as KernelStartupErrorraise KernelStartupError(f"Failed to start kernel subprocess.\n\n{e}") from e+ finally:+ if self.kernel_task is None:+ await self._cleanup_failed_start(handshake)- def _cleanup_failed_start(self) -> None:+ async def _cleanup_failed_start(+ self, handshake: asyncio.Future[list[str]] | None = None+ ) -> None:"""Release resources retained before the startup handshake."""- if self._process is not None and self._process.poll() is None:- try:- try_kill_process_and_group(_SubprocessWrapper(self._process))- except (ProcessLookupError, PermissionError):- pass- except Exception as error:- LOGGER.warning(error)- if self._notebook_sandbox is not None:- self._notebook_sandbox.close()- self._notebook_sandbox = None-- def _await_handshake_line(- self,- handshake: queue.Queue[str],- deadline: float,- stderr_tail: deque[bytes],- cmd: list[str],- ) -> str:- """The next handshake line, bounded by exit and deadline.-- Raises `KernelStartupError` when the child exits without- producing it or the deadline passes; a hung child is killed so- an unresponsive launch cannot leak a process tree.- """- assert self._process is not None- while True:- try:- return handshake.get(timeout=0.1)- except queue.Empty:- pass- if self._process.poll() is not None:- # The reader thread may still be flushing lines the- # child printed just before exiting.- try:- return handshake.get(timeout=0.5)- except queue.Empty:- raise KernelStartupError(- f"Kernel exited during startup "- f"(exit code {self._process.returncode}).\n\n"- f"Command: {' '.join(cmd)}\n\n"- f"Stderr:\n{_decode_tail(stderr_tail)}"- ) from None- if time.monotonic() > deadline:- try:- try_kill_process_and_group(- _SubprocessWrapper(self._process)- )- except Exception as e:- LOGGER.warning(e)- raise KernelStartupError(- f"Kernel did not become ready within "- f"{_startup_timeout():.0f}s (override with "- f"MARIMO_KERNEL_STARTUP_TIMEOUT).\n\n"- f"Command: {' '.join(cmd)}\n\n"- f"Stderr:\n{_decode_tail(stderr_tail)}"+ try:+ if self._process is not None:+ await stop_subprocess(+ self._process,+ start_new_session=self._start_new_session,+ drain=handshake,)+ finally:+ if self._notebook_sandbox is not None:+ self._notebook_sandbox.close()+ self._notebook_sandbox = None@propertydef pid(self) -> int | None:diff --git a/marimo/_session/managers/kernel.py b/marimo/_session/managers/kernel.pyindex 9a556453e2..ee039bcdad 100644--- a/marimo/_session/managers/kernel.py+++ b/marimo/_session/managers/kernel.py@@ -65,7 +65,7 @@ class KernelManagerImpl(KernelManager):self._read_conn: TypedConnection[KernelMessage] | None = Noneself._virtual_file_storage = virtual_file_storage- def start_kernel(self) -> None:+ async def start_kernel(self) -> None:# We use a process in edit mode so that we can interrupt the app# with a SIGINT; we don't mind the additional memory consumption,# since there's only one client sessiondiff --git a/marimo/_session/model.py b/marimo/_session/model.pyindex 36f2328d91..b6e603498a 100644--- a/marimo/_session/model.py+++ b/marimo/_session/model.py@@ -2,6 +2,9 @@from __future__ import annotationsfrom enum import Enum+from typing import Literal++StartupPhase = Literal["preparing-environment", "starting-kernel"]class ConnectionState(Enum):diff --git a/marimo/_session/notebook/file_manager.py b/marimo/_session/notebook/file_manager.pyindex e6be930e72..14728b0a11 100644--- a/marimo/_session/notebook/file_manager.py+++ b/marimo/_session/notebook/file_manager.py@@ -3,6 +3,7 @@ from __future__ import annotationsimport osimport threading+from contextlib import nullcontextfrom pathlib import Pathfrom typing import TYPE_CHECKING, Any@@ -12,6 +13,7 @@ from marimo._ast.app import App, InternalAppfrom marimo._ast.app_config import overloads_from_envfrom marimo._ast.cell import CellConfigfrom marimo._environments.script_metadata import (+ notebook_file_lock,with_python_version_requirement,)from marimo._messaging.notebook.changes import (@@ -220,7 +222,10 @@ class AppFileManager:"""LOGGER.debug("Saving app to %s", path)- with self._save_lock:+ # Read the header and write the cells under the same lock as manifest+ # edits, so neither writer can restore the other's stale contents.+ file_lock = notebook_file_lock(str(path)) if persist else nullcontext()+ with self._save_lock, file_lock:# Get the header in case it was modified by the user (e.g. package installation)handler = get_notebook_serializer(path)header: str | None = Nonediff --git a/marimo/_session/session.py b/marimo/_session/session.pyindex 0eac4cf904..deb45f6a29 100644--- a/marimo/_session/session.py+++ b/marimo/_session/session.py@@ -13,10 +13,12 @@ from typing import TYPE_CHECKINGfrom uuid import uuid4from marimo import _loggers-from marimo._cli.sandbox import SandboxModefrom marimo._config.manager import MarimoConfigManager, ScriptConfigManagerfrom marimo._messaging.notebook.document import NotebookDocument-from marimo._messaging.notification import NotificationMessage+from marimo._messaging.notification import (+ NotificationMessage,+ StartupProgressNotification,+)from marimo._messaging.serde import serialize_kernel_messagefrom marimo._messaging.types import KernelMessagefrom marimo._runtime import commands@@ -86,7 +88,7 @@ class SessionImpl(Session):"""@classmethod- def create(+ async def create(cls,*,initialization_id: str,@@ -100,7 +102,7 @@ class SessionImpl(Session):auto_instantiate: bool,ttl_seconds: int | None,extensions: list[SessionExtension] | None = None,- sandbox_mode: SandboxMode | None = None,+ sandbox: bool = False,app_host_context: AppHostContext | None = None,) -> Session:"""@@ -114,21 +116,9 @@ class SessionImpl(Session):configs = app_file_manager.app.cell_manager.config_map()- from marimo._config.settings import GLOBAL_SETTINGS-- # The single-file launcher strips --sandbox before starting the- # server. Edit kernels must still relaunch from the current manifest,- # not inherit the server's original interpreter after a rename.- if (- mode == SessionMode.EDIT- and sandbox_mode is None- and GLOBAL_SETTINGS.SANDBOX_MODE == "single"- ):- sandbox_mode = SandboxMode.SINGLE-# Create kernel manager# AppHost path handles multi-app run mode (both sandbox and non-sandbox).- # SandboxMode.MULTI falls through to IPC kernels only in edit mode.+ # Sandboxed edit sessions use IPC kernels.queue_manager: QueueManagerkernel_manager: KernelManagerif app_host_context is not None and mode == SessionMode.RUN:@@ -156,9 +146,7 @@ class SessionImpl(Session):config_manager=config_manager,redirect_console_to_browser=redirect_console_to_browser,)- elif sandbox_mode is SandboxMode.MULTI or (- sandbox_mode is SandboxMode.SINGLE and mode == SessionMode.EDIT- ):+ elif sandbox:# IPC kernel path — edit mode with sandbox# (AppHostPool is never created in edit mode)from marimo._ipc import QueueManager as IPCQueueManager@@ -177,7 +165,11 @@ class SessionImpl(Session):app_metadata=app_metadata,config_manager=config_manager,redirect_console_to_browser=redirect_console_to_browser,- sandbox_mode=sandbox_mode,+ on_progress=lambda phase: session_consumer.notify(+ serialize_kernel_message(+ StartupProgressNotification(phase=phase)+ )+ ),)else:# Original kernel: Process for edit, Thread for run@@ -220,6 +212,12 @@ class SessionImpl(Session):SessionViewExtension(),]+ try:+ await kernel_manager.start_kernel()+ except BaseException:+ queue_manager.close_queues()+ raise+return cls(initialization_id=initialization_id,session_consumer=session_consumer,@@ -258,7 +256,6 @@ class SessionImpl(Session):self.scratchpad_lock = asyncio.Lock()self._notebook_sandbox: NotebookSandbox | None = None- self._kernel_manager.start_kernel()self._bind_notebook_sandbox()self._event_bus = SessionEventBus()diff --git a/marimo/_session/types.py b/marimo/_session/types.pyindex 7bfb1ae862..8edc134282 100644--- a/marimo/_session/types.py+++ b/marimo/_session/types.py@@ -67,7 +67,7 @@ class KernelManager(Protocol):kernel_task: ProcessLike | threading.Thread | Nonemode: SessionMode- def start_kernel(self) -> None:+ async def start_kernel(self) -> None:"""Start the kernel process or thread."""...diff --git a/marimo/_utils/inline_script_metadata.py b/marimo/_utils/inline_script_metadata.pyindex f2bd6a81d1..a5ea8c458a 100644--- a/marimo/_utils/inline_script_metadata.py+++ b/marimo/_utils/inline_script_metadata.py@@ -408,7 +408,7 @@ def get_headers_from_frontmatter(pyproject = frontmatter.get("pyproject", "")if pyproject:- if not pyproject.startswith("#"):+ if pyproject.splitlines()[0] != "# /// script":# Wrap raw TOML content in PEP 723 formatpyproject = script_metadata.wrap_block(pyproject)headers["pyproject"] = pyprojectdiff --git a/marimo/_utils/subprocess.py b/marimo/_utils/subprocess.pyindex d9cdd5628a..da5d41f5ef 100644--- a/marimo/_utils/subprocess.py+++ b/marimo/_utils/subprocess.py@@ -6,6 +6,8 @@ import osimport signalimport subprocessfrom collections.abc import Callable, Mapping, Sequence+from concurrent.futures import ThreadPoolExecutor+from functools import partialfrom typing import (IO,Any,@@ -434,7 +436,8 @@ def kill_subprocess(Use SIGKILL for an isolated group so a descendant ignoring SIGTERMcannot keep captured pipes open after the launcher exits."""- if process.poll() is not None:+ # A launcher may have exited while its descendants still hold the pipes.+ if process.poll() is not None and (is_windows() or not start_new_session):returnif is_windows():try:@@ -448,10 +451,46 @@ def kill_subprocess(process.kill()else:try:- if start_new_session:+ if start_new_session or os.getpgid(process.pid) == process.pid:os.killpg(process.pid, signal.SIGKILL)else:process.kill()except ProcessLookupError:passprocess.wait()+++async def stop_subprocess(+ process: subprocess.Popen[Any],+ *,+ start_new_session: bool,+ drain: asyncio.Future[Any] | None = None,+) -> None:+ """Finish failed-command cleanup before the caller re-raises its error.++ Killing and reaping run off the event loop. Further cancellation cannot+ abandon the process or the pipe readers supplied by its owner.+ """++ async def cleanup() -> None:+ # Pipe readers can fill the default executor while waiting for this+ # kill. Cleanup must be able to run independently of those readers.+ with ThreadPoolExecutor(max_workers=1) as executor:+ await asyncio.get_running_loop().run_in_executor(+ executor,+ partial(+ kill_subprocess,+ process,+ start_new_session=start_new_session,+ ),+ )+ if drain is not None:+ await asyncio.gather(drain, return_exceptions=True)++ task = asyncio.create_task(cleanup())+ while not task.done():+ try:+ await asyncio.shield(task)+ except asyncio.CancelledError:+ continue+ task.result()diff --git a/packages/openapi/api.yaml b/packages/openapi/api.yamlindex 6d8d1bde41..1e040cb4fc 100644--- a/packages/openapi/api.yaml+++ b/packages/openapi/api.yaml@@ -3171,6 +3171,7 @@ components:- $ref: '#/components/schemas/MissingPackageAlertNotification'- $ref: '#/components/schemas/InstallingPackageAlertNotification'- $ref: '#/components/schemas/StartupLogsNotification'+ - $ref: '#/components/schemas/StartupProgressNotification'- $ref: '#/components/schemas/KernelStartupErrorNotification'- $ref: '#/components/schemas/VariablesNotification'- $ref: '#/components/schemas/VariableValuesNotification'@@ -3233,6 +3234,7 @@ components:sql-table-list-preview: '#/components/schemas/SQLTableListPreviewNotification'sql-table-preview: '#/components/schemas/SQLTablePreviewNotification'startup-logs: '#/components/schemas/StartupLogsNotification'+ startup-progress: '#/components/schemas/StartupProgressNotification'storage-download-ready: '#/components/schemas/StorageDownloadReadyNotification'storage-entries: '#/components/schemas/StorageEntriesNotification'storage-namespaces: '#/components/schemas/StorageNamespacesNotification'@@ -4976,6 +4978,38 @@ components:- backendtitle: SandboxPackageContexttype: object+ SandboxRequest:+ properties:+ fileKey:+ anyOf:+ - type: string+ - type: 'null'+ default: null+ required: []+ title: SandboxRequest+ type: object+ SandboxResponse:+ properties:+ backend:+ anyOf:+ - enum:+ - pixi+ - uv+ - type: 'null'+ filename:+ anyOf:+ - type: string+ - type: 'null'+ manifest:+ anyOf:+ - type: string+ - type: 'null'+ required:+ - backend+ - manifest+ - filename+ title: SandboxResponse+ type: objectSaveAppConfigurationRequest:properties:config:@@ -5474,6 +5508,21 @@ components:- statustitle: StartupLogsNotificationtype: object+ StartupProgressNotification:+ description: Progress reported before a session's kernel is ready.+ properties:+ op:+ enum:+ - startup-progress+ phase:+ enum:+ - preparing-environment+ - starting-kernel+ required:+ - op+ - phase+ title: StartupProgressNotification+ type: objectStdinRequest:properties:text:@@ -5840,6 +5889,25 @@ components:- deleteIdstitle: SyncGraphCommandtype: object+ SyncSandboxResponse:+ properties:+ error:+ anyOf:+ - type: string+ - type: 'null'+ default: null+ reconnect:+ default: false+ type: boolean+ restartRequired:+ default: false+ type: boolean+ success:+ type: boolean+ required:+ - success+ title: SyncSandboxResponse+ type: objectToolDefinition:description: Tool definition compatible with ai-sdk-ui format.properties:@@ -6039,6 +6107,22 @@ components:- cellIdsToOutputtitle: UpdateCellOutputsRequesttype: object+ UpdateManifestRequest:+ properties:+ contents:+ type: string+ fileKey:+ anyOf:+ - type: string+ - type: 'null'+ default: null+ previous:+ type: string+ required:+ - contents+ - previous+ title: UpdateManifestRequest+ type: objectUpdateUIElementCommand:description: "Update UI element values.\n\n Triggered when users interact\\ with UI elements (sliders, inputs, dropdowns, etc.).\n Updates element\@@ -7769,6 +7853,27 @@ paths:schema:$ref: '#/components/schemas/ListPackagesResponse'description: List installed packages+ /api/packages/manifest:+ post:+ parameters:+ - in: header+ name: Marimo-Session-Id+ required: true+ schema:+ type: string+ requestBody:+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/UpdateManifestRequest'+ required: true+ responses:+ 200:+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/SandboxResponse'+ description: Save notebook metadata without changing its cells/api/packages/remove:post:requestBody:@@ -7783,6 +7888,48 @@ paths:schema:$ref: '#/components/schemas/PackageOperationResponse'description: Uninstall package+ /api/packages/sandbox:+ post:+ parameters:+ - in: header+ name: Marimo-Session-Id+ required: true+ schema:+ type: string+ requestBody:+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/SandboxRequest'+ required: true+ responses:+ 200:+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/SandboxResponse'+ description: Sandbox manifest, available before kernel startup+ /api/packages/sync:+ post:+ parameters:+ - in: header+ name: Marimo-Session-Id+ required: true+ schema:+ type: string+ requestBody:+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/SandboxRequest'+ required: true+ responses:+ 200:+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/SyncSandboxResponse'+ description: Apply the saved manifest, or reconnect to retry startup/api/packages/tree:get:responses:diff --git a/packages/openapi/src/api.ts b/packages/openapi/src/api.tsindex 5901adafc3..13c456f348 100644--- a/packages/openapi/src/api.ts+++ b/packages/openapi/src/api.ts@@ -3097,6 +3097,47 @@ export interface paths {patch?: never;trace?: never;};+ "/api/packages/manifest": {+ parameters: {+ query?: never;+ header?: never;+ path?: never;+ cookie?: never;+ };+ get?: never;+ put?: never;+ post: {+ parameters: {+ query?: never;+ header: {+ "Marimo-Session-Id": string;+ };+ path?: never;+ cookie?: never;+ };+ requestBody: {+ content: {+ "application/json": components["schemas"]["UpdateManifestRequest"];+ };+ };+ responses: {+ /** @description Save notebook metadata without changing its cells */+ 200: {+ headers: {+ [name: string]: unknown;+ };+ content: {+ "application/json": components["schemas"]["SandboxResponse"];+ };+ };+ };+ };+ delete?: never;+ options?: never;+ head?: never;+ patch?: never;+ trace?: never;+ };"/api/packages/remove": {parameters: {query?: never;@@ -3136,6 +3177,88 @@ export interface paths {patch?: never;trace?: never;};+ "/api/packages/sandbox": {+ parameters: {+ query?: never;+ header?: never;+ path?: never;+ cookie?: never;+ };+ get?: never;+ put?: never;+ post: {+ parameters: {+ query?: never;+ header: {+ "Marimo-Session-Id": string;+ };+ path?: never;+ cookie?: never;+ };+ requestBody: {+ content: {+ "application/json": components["schemas"]["SandboxRequest"];+ };+ };+ responses: {+ /** @description Sandbox manifest, available before kernel startup */+ 200: {+ headers: {+ [name: string]: unknown;+ };+ content: {+ "application/json": components["schemas"]["SandboxResponse"];+ };+ };+ };+ };+ delete?: never;+ options?: never;+ head?: never;+ patch?: never;+ trace?: never;+ };+ "/api/packages/sync": {+ parameters: {+ query?: never;+ header?: never;+ path?: never;+ cookie?: never;+ };+ get?: never;+ put?: never;+ post: {+ parameters: {+ query?: never;+ header: {+ "Marimo-Session-Id": string;+ };+ path?: never;+ cookie?: never;+ };+ requestBody: {+ content: {+ "application/json": components["schemas"]["SandboxRequest"];+ };+ };+ responses: {+ /** @description Apply the saved manifest, or reconnect to retry startup */+ 200: {+ headers: {+ [name: string]: unknown;+ };+ content: {+ "application/json": components["schemas"]["SyncSandboxResponse"];+ };+ };+ };+ };+ delete?: never;+ options?: never;+ head?: never;+ patch?: never;+ trace?: never;+ };"/api/packages/tree": {parameters: {query?: never;@@ -5636,6 +5759,7 @@ export interface components {| components["schemas"]["MissingPackageAlertNotification"]| components["schemas"]["InstallingPackageAlertNotification"]| components["schemas"]["StartupLogsNotification"]+ | components["schemas"]["StartupProgressNotification"]| components["schemas"]["KernelStartupErrorNotification"]| components["schemas"]["VariablesNotification"]| components["schemas"]["VariableValuesNotification"]@@ -6750,6 +6874,17 @@ export interface components {/** @enum {unknown} */kind: "sandbox";};+ /** SandboxRequest */+ SandboxRequest: {+ /** @default null */+ fileKey?: string | null;+ };+ /** SandboxResponse */+ SandboxResponse: {+ backend: ("pixi" | "uv") | null;+ filename: string | null;+ manifest: string | null;+ };/** SaveAppConfigurationRequest */SaveAppConfigurationRequest: {config: Record<string, any>;@@ -7057,6 +7192,16 @@ export interface components {/** @enum {unknown} */status: "append" | "done" | "start";};+ /**+ * StartupProgressNotification+ * @description Progress reported before a session's kernel is ready.+ */+ StartupProgressNotification: {+ /** @enum {unknown} */+ op: "startup-progress";+ /** @enum {unknown} */+ phase: "preparing-environment" | "starting-kernel";+ };/** StdinRequest */StdinRequest: {text: string;@@ -7293,6 +7438,16 @@ export interface components {/** @enum {unknown} */type: "sync-graph";};+ /** SyncSandboxResponse */+ SyncSandboxResponse: {+ /** @default null */+ error?: string | null;+ /** @default false */+ reconnect?: boolean;+ /** @default false */+ restartRequired?: boolean;+ success: boolean;+ };/*** ToolDefinition* @description Tool definition compatible with ai-sdk-ui format.@@ -7427,6 +7582,13 @@ export interface components {];};};+ /** UpdateManifestRequest */+ UpdateManifestRequest: {+ contents: string;+ /** @default null */+ fileKey?: string | null;+ previous: string;+ };/*** UpdateUIElementCommand* @description Update UI element values.diff --git a/tests/_cli/test_cli.py b/tests/_cli/test_cli.pyindex 8e9b301a04..0d7b231e04 100644--- a/tests/_cli/test_cli.py+++ b/tests/_cli/test_cli.py@@ -9,7 +9,9 @@ from __future__ import annotationsimport contextlibimport inspect+import jsonimport os+import shutilimport signalimport socketimport subprocess@@ -1388,24 +1390,24 @@ def test_cli_sandbox_edit_no_prompt(temp_marimo_file: str) -> None:@pytest.mark.parametrize("command", ["edit", "run"])@pytest.mark.parametrize(- ("option", "backend"), [("--sandbox=pixi", "pixi"), ("--sandbox", "uv")]+ ("options", "backend"),+ [+ (["--sandbox"], "uv"),+ (["--sandbox=uv"], "uv"),+ (["--sandbox=pixi"], "pixi"),+ (["--sandbox", "uv"], "uv"),+ (["--sandbox", "pixi"], "pixi"),+ ],)[email protected]("directory", ["pixi", "uv"])-def test_cli_sandbox_records_backend_and_preserves_paths(+def test_cli_sandbox_selects_backend(tmp_path: Path,monkeypatch: pytest.MonkeyPatch,command: str,- option: str,+ options: list[str],backend: str,- directory: str,) -> None:- """Kernel launches read the backend from GLOBAL_SETTINGS; `run` must- record it or `run --sandbox=pixi` launches uv kernels."""- from marimo._cli.sandbox import SandboxMode- from marimo._config.settings import GLOBAL_SETTINGS-monkeypatch.chdir(tmp_path)- notebook_dir = tmp_path / directory+ notebook_dir = tmp_path / "notebooks"notebook_dir.mkdir()(notebook_dir / "nb.py").write_text(codegen.generate_filecontents(@@ -1415,48 +1417,148 @@ def test_cli_sandbox_records_backend_and_preserves_paths(),encoding="utf-8",)- runner = CliRunner()- captured: dict[str, object] = {}+ monkeypatch.setenv("MARIMO_SERVER_OVERLAY", "1")+ with patch("marimo._cli.cli.start") as start_server:+ result = CliRunner().invoke(+ cli_main, [command, *options, "notebooks", "--headless"]+ )+ assert result.exit_code == 0, result.output+ assert start_server.call_args.kwargs["sandbox"] == backend+ assert start_server.call_args.kwargs["workspace"].directory == str(+ notebook_dir+ )- def _capture_start(**kwargs: object) -> None:- captured["backend"] = GLOBAL_SETTINGS.SANDBOX_BACKEND- captured["sandbox_mode"] = kwargs["sandbox_mode"]- with (- patch.dict(os.environ),- patch.object(GLOBAL_SETTINGS, "SANDBOX_BACKEND", None),- patch.object(GLOBAL_SETTINGS, "SANDBOX_MODE", None),- patch.object(GLOBAL_SETTINGS, "MANAGE_SCRIPT_METADATA", False),- patch("marimo._cli.cli.start", side_effect=_capture_start),- ):- result = runner.invoke(- cli_main,- [command, option, directory, "--headless"],- )[email protected](scope="module")+def bare_marimo_python(tmp_path_factory: pytest.TempPathFactory) -> str:+ """A real marimo installation without server tools or test dependencies."""+ root = tmp_path_factory.mktemp("bare-marimo")+ python = root / ("Scripts/python.exe" if _is_win32() else "bin/python")+ subprocess.run(+ ["uv", "venv", "--python", sys.executable, str(root)], check=True+ )+ subprocess.run(+ ["uv", "pip", "install", "--python", str(python), "-e", "."],+ check=True,+ )+ return str(python)- assert result.exit_code == 0, result.output- assert captured["sandbox_mode"] is SandboxMode.MULTI- assert captured["backend"] == backend[email protected](not HAS_UV, reason="uv is required to install the fixture")[email protected]("entry", ["file", "folder", "stdin", "new"])[email protected]("backend", ["uv", "pixi"])+def test_editor_sandbox_supplies_server_tools(+ tmp_path: Path, bare_marimo_python: str, entry: str, backend: str+) -> None:+ """Formatting works without adding Ruff to the notebook or host."""+ from websockets.sync.client import connect[email protected](not HAS_UV, reason="uv is required for sandbox tests")-def test_cli_sandbox_edit_new_file() -> None:- with tempfile.TemporaryDirectory() as d:- path = os.path.join(d, "new_sandbox_file.py")- runner = CliRunner()- with patch(- "marimo._cli.sandbox.run_in_sandbox"- ) as mock_run_in_sandbox:- mock_run_in_sandbox.return_value = 0- result = runner.invoke(- cli_main,- ["edit", "--sandbox", path, "--headless", "--no-token"],+ from marimo._environments.uv import find_uv_bin++ if entry == "stdin" and _is_win32():+ pytest.skip("Piped notebooks are not supported on Windows")++ backend_bin = shutil.which(backend)+ if backend_bin is None:+ pytest.skip(f"{backend} is required")+ source = (+ '# /// script\n# dependencies = ["marimo"]\n# ///\n'+ "import marimo\napp = marimo.App()\n"+ )+ notebook = tmp_path / "notebook.py"+ notebook.write_text(+ source.replace('["marimo"]', '["does-not-exist-marimo-test"]')+ )+ targets = {"file": [str(notebook)], "folder": [str(tmp_path)]}+ port = _get_port()+ # A formatter on the test runner's PATH would hide this regression.+ env = {+ **os.environ,+ "UV": str(find_uv_bin()),+ "PATH": os.pathsep.join([str(Path(backend_bin).parent), os.defpath]),+ }+ env.pop("PYTHONPATH", None)+ env.pop("MARIMO_SERVER_OVERLAY", None)+ probe = [+ bare_marimo_python,+ "-c",+ (+ "import importlib.util, shutil; "+ "assert shutil.which('ruff') is None; "+ "assert all(importlib.util.find_spec(p) is None "+ "for p in ('ruff', 'pylsp', 'pylsp_ruff'))"+ ),+ ]+ subprocess.run(probe, env=env, check=True)+ with subprocess.Popen(+ [+ bare_marimo_python,+ "-m",+ "marimo",+ "new" if entry == "new" else "edit",+ *targets.get(entry, []),+ f"--sandbox={backend}",+ "--headless",+ "--no-token",+ "--no-skew-protection",+ "--port",+ str(port),+ ],+ cwd=tmp_path,+ env=env,+ stdin=subprocess.PIPE,+ stdout=subprocess.PIPE,+ stderr=subprocess.STDOUT,+ ) as process:+ try:+ assert process.stdin is not None+ if entry == "stdin":+ process.stdin.write(source.encode())+ process.stdin.close()+ assert process.stdout is not None+ output = []+ for line in process.stdout:+ output.append(line.decode())+ if b"URL:" in line:+ break+ else:+ pytest.fail("Server did not start: " + "".join(output))+ assert _try_fetch(port) is not None+ # An unresolvable manifest must not prevent server startup.+ notebook.write_text(source)+ query = urllib.parse.urlencode(+ {+ "session_id": "formatting",+ **({"file": str(notebook)} if entry == "folder" else {}),+ })- assert result.exit_code == 0, result.output- mock_run_in_sandbox.assert_called_once()- call_kwargs = mock_run_in_sandbox.call_args- assert call_kwargs.kwargs["name"] == path- assert call_kwargs.kwargs["extras"] == ["lsp"]+ with connect(f"ws://localhost:{port}/ws?{query}") as websocket:+ while True:+ message = json.loads(websocket.recv(timeout=60))+ assert message["op"] != "kernel-startup-error", message+ if message["op"] == "kernel-ready":+ break+ request = urllib.request.Request(+ f"http://localhost:{port}/api/kernel/format",+ data=json.dumps(+ {+ "codes": {"cell": "x= 1"},+ "lineLength": 80,+ }+ ).encode(),+ headers={+ "Content-Type": "application/json",+ "Marimo-Session-Id": "formatting",+ },+ )+ with urllib.request.urlopen(request, timeout=10) as response:+ assert json.load(response) == {"codes": {"cell": "x = 1"}}+ finally:+ process.terminate()+ process.wait(timeout=15)+ assert notebook.read_text() == source+ subprocess.run(probe, env=env, check=True)@pytest.mark.skipif(@@ -1973,25 +2075,25 @@ def test_cli_with_custom_pyproject_config_no_file(tmp_path: Path) -> None:finally:p.kill()- # marimo new --sandbox, in the directory with pyproject.toml- runner = CliRunner()- original_dir = os.getcwd()+ # The unnamed editor reads the same project configuration.+ port = _get_port()+ p = subprocess.Popen(+ [+ "marimo",+ "new",+ "--sandbox",+ "-p",+ str(port),+ "--headless",+ "--no-token",+ ],+ cwd=tmp_path,+ )try:- os.chdir(tmp_path)- with patch(- "marimo._cli.sandbox.run_in_sandbox"- ) as mock_run_in_sandbox:- mock_run_in_sandbox.return_value = 0- result = runner.invoke(- cli_main,- ["new", "--sandbox", "--headless", "--no-token"],- )+ assert_custom_config(_try_fetch(port))finally:- os.chdir(original_dir)- assert result.exit_code == 0, result.output- mock_run_in_sandbox.assert_called_once()- call_kwargs = mock_run_in_sandbox.call_args- assert call_kwargs.kwargs["extras"] == ["lsp"]+ p.kill()+ p.wait()# shell-completion has 1 input (value of $SHELL) & 3 outputs (return code, stdout, & stderr)diff --git a/tests/_cli/test_cli_export_sandbox.py b/tests/_cli/test_cli_export_sandbox.pynew file mode 100644index 0000000000..b962a10ed6--- /dev/null+++ b/tests/_cli/test_cli_export_sandbox.py@@ -0,0 +1,321 @@+# Copyright 2026 Marimo. All rights reserved.+from __future__ import annotations++import json+import os+import sys+from functools import partial+from pathlib import Path+from types import ModuleType+from typing import TYPE_CHECKING+from unittest.mock import AsyncMock, MagicMock++import click+import pytest+from click.testing import CliRunner++from marimo._cli.export import session, thumbnail+from marimo._environments import backends, environment, pixi, uv+from marimo._environments.environment import Environment, ProcessPlan+from marimo._session.state.serialize import get_session_cache_file++if TYPE_CHECKING:+ from collections.abc import Mapping, Sequence++ from marimo._environments.overlay import RuntimeOverlay+ from marimo._environments.sandbox import Backend+++def local_environments(monkeypatch: pytest.MonkeyPatch) -> None:+ # Substitute dependency installation, but run the real export workers.+ async def sync(path: str, *, backend: Backend) -> Environment:+ source = Path(path)+ root = source.with_suffix("")+ root.mkdir(exist_ok=True)+ (root / "sandbox_dependency.py").write_text(+ f"NAME = {source.stem!r}\nBACKEND = {backend!r}\n",+ encoding="utf-8",+ )+ return Environment(sys.executable, str(root), "unchanged")++ def launch(+ env: Environment,+ args: Sequence[str],+ *,+ overlay: RuntimeOverlay,+ backend: Backend,+ base_env: Mapping[str, str] | None = None,+ ) -> ProcessPlan:+ del overlay+ process_env = dict(os.environ if base_env is None else base_env)+ process_env["TEST_EXPORT_BACKEND"] = backend+ process_env["PYTHONPATH"] = os.pathsep.join(+ [env.root, process_env.get("PYTHONPATH", "")]+ )+ return ProcessPlan((env.python, *args), process_env, True)++ monkeypatch.setattr(backends, "sync_notebook_async", sync)+ monkeypatch.setattr(environment, "launch", partial(launch, backend="uv"))+ monkeypatch.setattr(pixi, "launch", partial(launch, backend="pixi"))+ monkeypatch.setattr(backends, "ensure_available", lambda _: None)+ monkeypatch.setattr(environment, "require_uv_bin", lambda: "uv")+ monkeypatch.setattr(uv, "require_uv_bin", lambda: "uv")+ monkeypatch.setattr(pixi, "require_pixi_bin", lambda: "pixi")+++def browser(monkeypatch: pytest.MonkeyPatch) -> None:+ page = AsyncMock()+ context = AsyncMock()+ context.new_page.return_value = page+ browser = AsyncMock()+ browser.new_context.return_value = context+ playwright = MagicMock()+ playwright.chromium.launch = AsyncMock(return_value=browser)+ manager = AsyncMock()+ manager.__aenter__.return_value = playwright+ module = ModuleType("playwright.async_api")+ module.async_playwright = lambda: manager+ module.TimeoutError = TimeoutError+ monkeypatch.setitem(sys.modules, "playwright.async_api", module)+ monkeypatch.setattr(+ thumbnail.DependencyManager.playwright, "require", lambda _: None+ )+++def write_notebook(path: Path) -> None:+ path.write_text(+ """# /// script+# dependencies = ["marimo", "sandbox-dependency"]+# ///+import marimo++app = marimo.App()++def _():+ import json+ import os+ from pathlib import Path+ import marimo as mo+ import sandbox_dependency++ result = Path(mo.cli_args()["output-dir"]) / (sandbox_dependency.NAME + ".json")+ result.write_text(json.dumps({"value": mo.cli_args()["value"], "pid": os.getpid(), "backend": sandbox_dependency.BACKEND, "launcher": os.environ["TEST_EXPORT_BACKEND"], "sandbox_arg": mo.cli_args().get("sandbox")}))+ return++if __name__ == "__main__":+ app.run()+""",+ encoding="utf-8",+ )++[email protected]("export_format", ["session", "thumbnail"])[email protected]("directory", [False, True])+ ("option", "backend"),+ [("--sandbox", "uv"), ("--sandbox=uv", "uv"), ("--sandbox=pixi", "pixi")],+)[email protected]("local_environments", "browser")+def test_sandbox_exports_execute_in_each_notebook_environment(+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+ export_format: str,+ directory: bool,+ option: str,+ backend: Backend,+) -> None:+ notebooks = tmp_path / "notebooks"+ notebooks.mkdir()+ paths = [notebooks / "first.py", notebooks / "second.py"]+ for path in paths:+ write_notebook(path)+ sources = [path.read_text() for path in paths]+ target = notebooks if directory else paths[0]+ command = (+ session.session if export_format == "session" else thumbnail.thumbnail+ )+ args = [str(target), option]+ if export_format == "thumbnail":+ args.append("--execute")+ args.extend(+ [+ "--",+ "--value",+ "forwarded",+ "--sandbox=pixi",+ "--output-dir",+ str(tmp_path),+ ]+ )++ if backend == "pixi":++ def unavailable_uv() -> str:+ raise AssertionError("Pixi exports must not require a host uv")++ monkeypatch.setattr(uv, "require_uv_bin", unavailable_uv)+ monkeypatch.setattr(environment, "require_uv_bin", unavailable_uv)++ # Re-enter as the Playwright bootstrap would, preserving notebook args.+ def bootstrap(plan: ProcessPlan) -> int:+ assert plan.argv[0] == backend+ assert "playwright" in plan.argv+ argv = list(plan.argv[plan.argv.index("marimo") + 3 :])+ with monkeypatch.context() as child:+ for key, value in plan.env.items():+ child.setenv(key, value)+ result = CliRunner().invoke(command, argv)+ assert result.exit_code == 0, result.output+ return result.exit_code++ monkeypatch.setattr(thumbnail, "_wait_on_plan", bootstrap)+ monkeypatch.setattr(+ sys, "argv", ["marimo", "export", export_format, *args]+ )+ result = CliRunner().invoke(command, args)+ assert result.exit_code == 0, result.output++ executed = paths if directory else paths[:1]+ results = {+ path.stem: json.loads(path.read_text())+ for path in tmp_path.glob("*.json")+ }+ assert set(results) == {path.stem for path in executed}+ pids = {data["pid"] for data in results.values()}+ assert os.getpid() not in pids+ assert len(pids) == len(executed)+ assert {data["value"] for data in results.values()} == {"forwarded"}+ assert {+ (data["backend"], data["launcher"]) for data in results.values()+ } == {(backend, backend)}+ assert {data["sandbox_arg"] for data in results.values()} == {"pixi"}+ assert [path.read_text() for path in paths] == sources++ if export_format == "session":+ # Fresh snapshots skip environment preparation as well as execution.+ def unavailable(*_args: object, **_kwargs: object) -> None:+ raise AssertionError(+ "A fresh snapshot must not provision dependencies"+ )++ monkeypatch.setattr(backends, "sync_notebook_async", unavailable)+ monkeypatch.setattr(backends, "ensure_available", unavailable)+ result = CliRunner().invoke(command, args)+ assert result.exit_code == 0, result.output+ assert "skip:" in result.output+ assert {+ path.stem: json.loads(path.read_text())+ for path in tmp_path.glob("*.json")+ } == results++[email protected]("continue_on_error", [False, True])[email protected]("local_environments")+def test_session_export_handles_dependency_failure(+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+ continue_on_error: bool,+) -> None:+ paths = [tmp_path / f"{name}.py" for name in ("first", "second", "third")]+ for path in paths:+ write_notebook(path)+ sync = backends.sync_notebook_async++ async def fail_second(path: str, *, backend: Backend) -> Environment:+ if Path(path).stem == "second":+ raise click.ClickException("Dependency resolution failed")+ return await sync(path, backend=backend)++ monkeypatch.setattr(backends, "sync_notebook_async", fail_second)+ result = CliRunner().invoke(+ session.session,+ [+ str(tmp_path),+ "--sandbox",+ "--continue-on-error"+ if continue_on_error+ else "--no-continue-on-error",+ "--",+ "--value=forwarded",+ "--output-dir",+ str(tmp_path),+ ],+ )+ assert result.exit_code == 1+ assert "Dependency resolution failed" in result.output+ assert {path.stem for path in tmp_path.glob("*.json")} == (+ {"first", "third"} if continue_on_error else {"first"}+ )+ assert [get_session_cache_file(path).exists() for path in paths] == [+ True,+ False,+ continue_on_error,+ ]+++ "options", [["--no-sandbox"], ["--sandbox=pixi", "--no-sandbox"]]+)+def test_session_export_does_not_require_a_backend(+ temp_marimo_file: str,+ monkeypatch: pytest.MonkeyPatch,+ options: list[str],+) -> None:+ def unavailable(_: Backend) -> None:+ raise AssertionError(+ "Non-sandboxed exports must not require a backend"+ )++ monkeypatch.setattr(backends, "ensure_available", unavailable)+ result = CliRunner().invoke(session.session, [temp_marimo_file, *options])+ assert result.exit_code == 0, result.output+ assert get_session_cache_file(Path(temp_marimo_file)).exists()+++def test_thumbnail_sandbox_requires_execution(tmp_path: Path) -> None:+ path = tmp_path / "notebook.py"+ write_notebook(path)+ result = CliRunner().invoke(thumbnail.thumbnail, [str(path), "--sandbox"])+ assert result.exit_code != 0+ assert "--sandbox requires --execute" in result.output+++def test_session_export_reports_invalid_worker_output(+ temp_marimo_file: str,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ monkeypatch.setattr(+ session, "run_python_subprocess", AsyncMock(return_value="not json")+ )+ result = CliRunner().invoke(+ session.session, [temp_marimo_file, "--sandbox"]+ )+ assert result.exit_code == 1+ assert "Failed to parse sandbox session export output" in result.output+ assert not get_session_cache_file(Path(temp_marimo_file)).exists()++[email protected]("export_format", ["session", "thumbnail"])[email protected]("backend", ["uv", "pixi"])+def test_export_reports_missing_selected_backend(+ export_format: str,+ backend: Backend,+ temp_marimo_file: str,+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ monkeypatch.delenv("UV", raising=False)+ monkeypatch.setenv("PATH", str(tmp_path))+ monkeypatch.chdir(tmp_path)+ command = (+ session.session if export_format == "session" else thumbnail.thumbnail+ )+ args = [temp_marimo_file, f"--sandbox={backend}"]+ if export_format == "thumbnail":+ args.append("--execute")+ result = CliRunner().invoke(command, args)+ assert result.exit_code == 1+ assert f"{backend} must be installed" in result.outputdiff --git a/tests/_cli/test_cli_export_session.py b/tests/_cli/test_cli_export_session.pydeleted file mode 100644index 38aeb5b99a..0000000000--- a/tests/_cli/test_cli_export_session.py+++ /dev/null@@ -1,272 +0,0 @@-# Copyright 2026 Marimo. All rights reserved.-from __future__ import annotations--from typing import TYPE_CHECKING-from unittest.mock import AsyncMock, patch--import click-import pytest-from click.testing import CliRunner--import marimo._cli.export.session as session_module-from marimo._cli.sandbox import SandboxMode-from marimo._server.utils import asyncio_run-from marimo._session.state.serialize import get_session_cache_file--if TYPE_CHECKING:- from pathlib import Path---def _write_notebook(path: Path) -> None:- path.write_text(- """-import marimo--app = marimo.App()--def _():- return--if __name__ == "__main__":- app.run()-""",- encoding="utf-8",- )---def test_session_sandbox_single_runs_in_sandbox(tmp_path: Path) -> None:- notebook = tmp_path / "notebook.py"- _write_notebook(notebook)- runner = CliRunner()- export_sessions = AsyncMock()-- with (- patch(- "marimo._cli.sandbox.run_in_sandbox",- return_value=0,- ) as run_in_sandbox,- patch(- "marimo._cli.sandbox.resolve_sandbox_mode",- return_value=SandboxMode.SINGLE,- ) as resolve_sandbox_mode,- patch.object(session_module, "_export_sessions", new=export_sessions),- ):- result = runner.invoke(- session_module.session,- [str(notebook), "--sandbox"],- )-- assert result.exit_code == 0, result.output- run_in_sandbox.assert_called_once()- resolve_sandbox_mode.assert_called_once()- assert run_in_sandbox.call_args.kwargs["name"] == str(notebook)- export_sessions.assert_not_called()---def test_session_sandbox_single_skips_before_sandbox_when_fresh(- tmp_path: Path,-) -> None:- notebook = tmp_path / "notebook.py"- _write_notebook(notebook)- session_file = get_session_cache_file(notebook)- session_file.parent.mkdir(parents=True, exist_ok=True)- session_file.write_text("{}", encoding="utf-8")- runner = CliRunner()-- with (- patch(- "marimo._cli.sandbox.resolve_sandbox_mode",- return_value=SandboxMode.SINGLE,- ),- patch.object(- session_module,- "is_session_snapshot_stale",- return_value=False,- ) as is_stale,- patch("marimo._cli.sandbox.run_in_sandbox") as run_in_sandbox,- ):- result = runner.invoke(- session_module.session,- [str(notebook), "--sandbox"],- )-- assert result.exit_code == 0, result.output- is_stale.assert_called_once()- run_in_sandbox.assert_not_called()- assert "skip:" in result.output---def test_session_sandbox_multi_uses_in_process_export(tmp_path: Path) -> None:- notebook_dir = tmp_path / "notebooks"- notebook_dir.mkdir()- first = notebook_dir / "first.py"- second = notebook_dir / "second.py"- _write_notebook(first)- _write_notebook(second)- runner = CliRunner()- export_sessions = AsyncMock()-- with (- patch("marimo._cli.sandbox.run_in_sandbox") as run_in_sandbox,- patch("marimo._cli.sandbox.resolve_sandbox_mode") as resolve_mode,- patch.object(session_module, "_export_sessions", new=export_sessions),- ):- result = runner.invoke(- session_module.session,- [str(notebook_dir), "--sandbox"],- )-- assert result.exit_code == 0, result.output- run_in_sandbox.assert_not_called()- resolve_mode.assert_not_called()- export_sessions.assert_called_once()- assert (- export_sessions.call_args.kwargs["sandbox_mode"] is SandboxMode.MULTI- )---def test_session_no_sandbox_uses_in_process_export(tmp_path: Path) -> None:- notebook = tmp_path / "notebook.py"- _write_notebook(notebook)- runner = CliRunner()- export_sessions = AsyncMock()-- with (- patch("marimo._cli.sandbox.run_in_sandbox") as run_in_sandbox,- patch(- "marimo._cli.sandbox.resolve_sandbox_mode", return_value=None- ) as resolve_mode,- patch.object(session_module, "_export_sessions", new=export_sessions),- ):- result = runner.invoke(- session_module.session,- [str(notebook), "--no-sandbox"],- )-- assert result.exit_code == 0, result.output- run_in_sandbox.assert_not_called()- resolve_mode.assert_called_once()- export_sessions.assert_called_once()- assert export_sessions.call_args.kwargs["sandbox_mode"] is None---def test_export_sessions_continue_on_error_processes_remaining(- tmp_path: Path,-) -> None:- first = tmp_path / "first.py"- second = tmp_path / "second.py"- third = tmp_path / "third.py"- _write_notebook(first)- _write_notebook(second)- _write_notebook(third)- notebooks = [- session_module.MarimoPath(str(p)) for p in [first, second, third]- ]-- called: list[str] = []-- async def fake_export(- marimo_path: session_module.MarimoPath,- *,- notebook_args: tuple[str, ...],- sandbox: object | None = None,- ) -> tuple[dict[str, str], bool]:- del notebook_args, sandbox- called.append(marimo_path.short_name)- if marimo_path.short_name == "second.py":- raise click.ClickException("boom")- return {"name": marimo_path.short_name}, False-- with (- patch.object(- session_module,- "_export_session_snapshot",- new=AsyncMock(side_effect=fake_export),- ),- pytest.raises(- click.ClickException,- match="Failed to export sessions for 1 notebooks",- ),- ):- asyncio_run(- session_module._export_sessions(- notebooks=notebooks,- force_overwrite=True,- notebook_args=(),- continue_on_error=True,- sandbox_mode=None,- )- )-- assert called == ["first.py", "second.py", "third.py"]- assert get_session_cache_file(first).exists()- assert not get_session_cache_file(second).exists()- assert get_session_cache_file(third).exists()---def test_export_sessions_no_continue_on_error_stops_at_first_error(- tmp_path: Path,-) -> None:- first = tmp_path / "first.py"- second = tmp_path / "second.py"- third = tmp_path / "third.py"- _write_notebook(first)- _write_notebook(second)- _write_notebook(third)- notebooks = [- session_module.MarimoPath(str(p)) for p in [first, second, third]- ]-- called: list[str] = []-- async def fake_export(- marimo_path: session_module.MarimoPath,- *,- notebook_args: tuple[str, ...],- sandbox: object | None = None,- ) -> tuple[dict[str, str], bool]:- del notebook_args, sandbox- called.append(marimo_path.short_name)- if marimo_path.short_name == "first.py":- raise click.ClickException("first failed")- return {"name": marimo_path.short_name}, False-- with (- patch.object(- session_module,- "_export_session_snapshot",- new=AsyncMock(side_effect=fake_export),- ),- pytest.raises(click.ClickException, match="first failed"),- ):- asyncio_run(- session_module._export_sessions(- notebooks=notebooks,- force_overwrite=True,- notebook_args=(),- continue_on_error=False,- sandbox_mode=None,- )- )-- assert called == ["first.py"]- assert not get_session_cache_file(first).exists()- assert not get_session_cache_file(second).exists()- assert not get_session_cache_file(third).exists()---def test_export_session_snapshot_subprocess_invalid_json() -> None:- with (- patch.object(- session_module, "run_python_subprocess", return_value="not json"- ),- pytest.raises(- click.ClickException,- match="Failed to parse sandbox session export output",- ),- ):- session_module._export_session_snapshot_in_subprocess(- "python",- {"path": "notebook.py", "args": []},- )diff --git a/tests/_cli/test_cli_export_thumbnail.py b/tests/_cli/test_cli_export_thumbnail.pydeleted file mode 100644index f8a0840678..0000000000--- a/tests/_cli/test_cli_export_thumbnail.py+++ /dev/null@@ -1,230 +0,0 @@-# Copyright 2026 Marimo. All rights reserved.-from __future__ import annotations--import os-from typing import TYPE_CHECKING-from unittest.mock import AsyncMock, patch--from click.testing import CliRunner--import marimo._cli.export.thumbnail as thumbnail_module-from marimo._cli.sandbox import SandboxMode--if TYPE_CHECKING:- from pathlib import Path---def _write_notebook(path: Path) -> None:- path.write_text(- """-import marimo--app = marimo.App()--def _():- return--if __name__ == "__main__":- app.run()-""",- encoding="utf-8",- )---def test_thumbnail_sandbox_single_bootstrap_adds_playwright(- tmp_path: Path,-) -> None:- notebook = tmp_path / "notebook.py"- _write_notebook(notebook)- runner = CliRunner()-- captured: dict[str, str | list[str] | None] = {}-- def _fake_run_in_sandbox(- args: list[str],- *,- name: str | None = None,- extras: list[str] | None = None,- command_deps: list[str] | None = None,- extra_env: dict[str, str] | None = None,- ) -> int:- del args- del extras- captured["name"] = name- captured["deps"] = command_deps- captured["mode"] = (extra_env or {}).get(- thumbnail_module._sandbox_mode_env- )- captured["bootstrapped"] = (extra_env or {}).get(- thumbnail_module._sandbox_bootstrapped_env- )- return 0-- with (- patch(- "marimo._cli.sandbox.run_in_sandbox",- side_effect=_fake_run_in_sandbox,- ) as run_in_sandbox,- patch(- "marimo._cli.sandbox.resolve_sandbox_mode",- return_value=SandboxMode.SINGLE,- ),- patch.object(- thumbnail_module.DependencyManager.playwright, "require"- ) as playwright_require,- ):- result = runner.invoke(- thumbnail_module.thumbnail,- [str(notebook), "--execute", "--sandbox"],- )-- assert result.exit_code == 0, result.output- run_in_sandbox.assert_called_once()- playwright_require.assert_not_called()- assert captured["name"] == str(notebook)- assert captured["deps"] == ["playwright"]- assert captured["mode"] == SandboxMode.SINGLE.value- assert captured["bootstrapped"] == "1"- assert thumbnail_module._sandbox_bootstrapped_env not in os.environ- assert thumbnail_module._sandbox_mode_env not in os.environ---def test_thumbnail_sandbox_multi_bootstrap_sets_multi_mode(- tmp_path: Path,-) -> None:- first = tmp_path / "first.py"- second = tmp_path / "second.py"- _write_notebook(first)- _write_notebook(second)- runner = CliRunner()-- captured: dict[str, str | list[str] | None] = {}-- def _fake_run_in_sandbox(- args: list[str],- *,- name: str | None = None,- extras: list[str] | None = None,- command_deps: list[str] | None = None,- extra_env: dict[str, str] | None = None,- ) -> int:- del args- del extras- captured["name"] = name- captured["deps"] = command_deps- captured["mode"] = (extra_env or {}).get(- thumbnail_module._sandbox_mode_env- )- return 0-- with (- patch(- "marimo._cli.sandbox.run_in_sandbox",- side_effect=_fake_run_in_sandbox,- ) as run_in_sandbox,- patch("marimo._cli.sandbox.resolve_sandbox_mode") as resolve_mode,- patch.object(- thumbnail_module.DependencyManager.playwright, "require"- ) as playwright_require,- ):- result = runner.invoke(- thumbnail_module.thumbnail,- [str(first), str(second), "--execute", "--sandbox"],- )-- assert result.exit_code == 0, result.output- run_in_sandbox.assert_called_once()- resolve_mode.assert_not_called()- playwright_require.assert_not_called()- assert captured["name"] == str(first)- assert captured["deps"] == ["playwright"]- assert captured["mode"] == SandboxMode.MULTI.value---def test_thumbnail_sandbox_requires_execute(tmp_path: Path) -> None:- notebook = tmp_path / "notebook.py"- _write_notebook(notebook)- runner = CliRunner()-- result = runner.invoke(- thumbnail_module.thumbnail,- [str(notebook), "--sandbox"],- )-- assert result.exit_code != 0- assert "--sandbox requires --execute" in result.output---def test_thumbnail_reentry_single_skips_bootstrap(- tmp_path: Path,- monkeypatch,-) -> None:- notebook = tmp_path / "notebook.py"- _write_notebook(notebook)- runner = CliRunner()- generate = AsyncMock()-- monkeypatch.setenv(thumbnail_module._sandbox_bootstrapped_env, "1")- monkeypatch.setenv(- thumbnail_module._sandbox_mode_env,- SandboxMode.SINGLE.value,- )-- with (- patch("marimo._cli.sandbox.run_in_sandbox") as run_in_sandbox,- patch("marimo._cli.sandbox.resolve_sandbox_mode") as resolve_mode,- patch.object(- thumbnail_module.DependencyManager.playwright, "require"- ) as playwright_require,- patch.object(thumbnail_module, "_generate_thumbnails", new=generate),- ):- result = runner.invoke(- thumbnail_module.thumbnail,- [str(notebook), "--execute"],- )-- assert result.exit_code == 0, result.output- run_in_sandbox.assert_not_called()- resolve_mode.assert_not_called()- playwright_require.assert_called_once_with("for thumbnail generation")- generate.assert_called_once()- assert generate.call_args.kwargs["sandbox_mode"] is SandboxMode.SINGLE---def test_thumbnail_reentry_multi_skips_bootstrap(- tmp_path: Path,- monkeypatch,-) -> None:- first = tmp_path / "first.py"- second = tmp_path / "second.py"- _write_notebook(first)- _write_notebook(second)- runner = CliRunner()- generate = AsyncMock()-- monkeypatch.setenv(thumbnail_module._sandbox_bootstrapped_env, "1")- monkeypatch.setenv(- thumbnail_module._sandbox_mode_env,- SandboxMode.MULTI.value,- )-- with (- patch("marimo._cli.sandbox.run_in_sandbox") as run_in_sandbox,- patch("marimo._cli.sandbox.resolve_sandbox_mode") as resolve_mode,- patch.object(- thumbnail_module.DependencyManager.playwright, "require"- ) as playwright_require,- patch.object(thumbnail_module, "_generate_thumbnails", new=generate),- ):- result = runner.invoke(- thumbnail_module.thumbnail,- [str(first), str(second), "--execute"],- )-- assert result.exit_code == 0, result.output- run_in_sandbox.assert_not_called()- resolve_mode.assert_not_called()- playwright_require.assert_called_once_with("for thumbnail generation")- generate.assert_called_once()- assert generate.call_args.kwargs["sandbox_mode"] is SandboxMode.MULTIdiff --git a/tests/_cli/test_export_subprocess.py b/tests/_cli/test_export_subprocess.pyindex 78e9f10994..d8a35aa441 100644--- a/tests/_cli/test_export_subprocess.py+++ b/tests/_cli/test_export_subprocess.py@@ -1,57 +1,155 @@# Copyright 2026 Marimo. All rights reserved.from __future__ import annotations+import asyncio+import jsonimport os+import select+import signalimport subprocessimport sys-from typing import Any+from typing import TYPE_CHECKING, Anyfrom unittest.mock import patchimport clickimport pytest-from marimo._cli.export._common import SandboxTarget, run_python_subprocess+from marimo._cli.export._common import run_python_subprocessfrom marimo._environments.environment import Environment, ProcessPlan+from marimo._environments.pixi import PixiMissingScriptMetadataError+from marimo._environments.sandbox import Backend+from marimo._environments.uv import UvMissingScriptMetadataError+if TYPE_CHECKING:+ from pathlib import Path[email protected]("isolated", [False, True])-def test_export_runs_the_planned_command(isolated: bool) -> None:- handle = (- None- if isolated- else Environment(sys.executable, sys.prefix, "unchanged")- )- module = "marimo._environments.environment"- target = (- "marimo._environments.backends.launch_fallback"- if isolated- else f"{module}.launch"++def notebook_without_metadata(monkeypatch: pytest.MonkeyPatch) -> str:+ async def missing_metadata(*_args: Any, **_kwargs: Any) -> None:+ raise UvMissingScriptMetadataError(+ ["uv", "sync"], 1, "", "No script metadata"+ )++ monkeypatch.setattr(+ "marimo._environments.backends.sync_notebook_async", missing_metadata)+ return "notebook.py"+++async def test_export_runs_the_planned_command() -> None:code = ("import json,os,sys; print(json.dumps([os.getpid(), os.getsid(0)]))"if os.name != "nt"else "print('done')")plan = ProcessPlan((sys.executable, "-c", code), dict(os.environ), True)- with patch(target, return_value=plan):- output = run_python_subprocess(- sandbox=SandboxTarget(handle),+ with (+ patch(+ "marimo._environments.backends.sync_notebook_async",+ return_value=Environment(sys.executable, sys.prefix, "unchanged"),+ ),+ patch("marimo._environments.environment.launch", return_value=plan),+ ):+ output = await run_python_subprocess(+ notebook_path="notebook.py",+ backend="uv",script="ignored",payload={},action="export",)if os.name != "nt":- import json-pid, session = json.loads(output)assert pid == sessionelse:assert output.strip() == "done"-def test_export_failure_identifies_launcher_without_payload_or_credentials() -> (- None-):[email protected]("backend", ["uv", "pixi"])+async def test_export_without_metadata_uses_current_interpreter(+ notebook_without_metadata: str,+ backend: Backend,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ if backend == "pixi":++ async def missing_metadata(*_args: Any, **_kwargs: Any) -> None:+ raise PixiMissingScriptMetadataError(+ ["pixi", "install"], 1, "No script metadata"+ )++ monkeypatch.setattr(+ "marimo._environments.backends.sync_notebook_async",+ missing_metadata,+ )++ payload = {"args": ["value with spaces", "--flag"], "unicode": "🎲"}+ output = await run_python_subprocess(+ notebook_path=notebook_without_metadata,+ backend=backend,+ script="import json,sys; print(json.dumps([sys.executable, json.loads(sys.argv[1])]))",+ payload=payload,+ action="export",+ )+ assert json.loads(output) == [sys.executable, payload]++[email protected](os.name == "nt", reason="POSIX process groups")+async def test_export_fallback_cancellation_stops_descendants(+ notebook_without_metadata: str, tmp_path: Path+) -> None:+ import psutil++ ready = tmp_path / "child.pid"+ child_code = (+ "import os, signal; from pathlib import Path; "+ f"Path({str(ready)!r}).write_text(str(os.getpid())); "+ "signal.pause()"+ )+ script = (+ "import subprocess, sys; "+ f"subprocess.Popen([sys.executable, '-c', {child_code!r}])"+ )+ task = asyncio.create_task(+ run_python_subprocess(+ notebook_path=notebook_without_metadata,+ backend="uv",+ script=script,+ payload={},+ action="export",+ )+ )+ child = None+ try:++ async def wait_for_child() -> int:+ while True:+ try:+ return int(await asyncio.to_thread(ready.read_text))+ except (FileNotFoundError, ValueError):+ await asyncio.sleep(0.01)++ child = psutil.Process(await asyncio.wait_for(wait_for_child(), 5))+ task.cancel()+ with pytest.raises(asyncio.CancelledError):+ await asyncio.wait_for(task, timeout=5)+ _, alive = await asyncio.to_thread(+ psutil.wait_procs, [child], timeout=5+ )+ assert not alive, "Cancelled export left its descendant running"+ finally:+ if child is not None:+ try:+ child.kill()+ except psutil.NoSuchProcess:+ pass+ task.cancel()+ await asyncio.gather(task, return_exceptions=True)+++async def test_export_failure_identifies_launcher_without_payload_or_credentials(+ notebook_without_metadata: str,+) -> None:plan = ProcessPlan((sys.executable,@@ -67,8 +165,9 @@ def test_export_failure_identifies_launcher_without_payload_or_credentials() ->"marimo._environments.backends.launch_fallback", return_value=plan):with pytest.raises(click.ClickException) as error:- run_python_subprocess(- sandbox=SandboxTarget(None),+ await run_python_subprocess(+ notebook_path=notebook_without_metadata,+ backend="uv",script="private notebook",payload={"token": "secret"},action="export",@@ -80,87 +179,103 @@ def test_export_failure_identifies_launcher_without_payload_or_credentials() ->assert "private notebook" not in message[email protected]("new_session", [False, True])-def test_export_interrupt_reaps_the_child(new_session: bool) -> None:- children = []- popen = subprocess.Popen[email protected](os.name == "nt", reason="POSIX termination signals")[email protected]("signal_name", ["SIGINT", "SIGTERM"])[email protected]("phase", ["preparation", "execution"])+def test_session_cli_cancellation_stops_active_subprocesses(+ tmp_path: Path, signal_name: str, phase: str+) -> None:+ import psutil- class InterruptedProcess(subprocess.Popen):- def communicate(self, *_args: Any, **_kwargs: Any):- assert self.stdout.readline().strip() == "ready"- raise KeyboardInterrupt+ ready = tmp_path / "ready"+ os.mkfifo(ready)+ notebook = tmp_path / "notebook.py"+ notebook.write_text(+ "import marimo\napp = marimo.App()\[email protected]\ndef _():\n"+ " import os, time\n from pathlib import Path\n"+ f" Path({str(ready)!r}).write_text(str(os.getpid()))\n"+ " time.sleep(30)\n return\n",+ encoding="utf-8",+ )+ # Skip dependency installation, but exercise the CLI, worker, and kernel.+ code = """+from marimo._cli.cli import main+from marimo._environments import backends+from marimo._environments.uv import UvMissingScriptMetadataError- def launch(*args: Any, **kwargs: Any):- # `patch` mutates the shared subprocess module, so Windows taskkill- # launched by `kill_subprocess` must keep using the real Popen.- if args[0][0] == "taskkill":- return popen(*args, **kwargs)- child = InterruptedProcess(*args, **kwargs)- children.append(child)- return child+async def missing_metadata(*args, **kwargs):+ raise UvMissingScriptMetadataError(["uv", "sync"], 1, "", "No script metadata")- plan = ProcessPlan(- (- sys.executable,- "-c",- "import time; print('ready', flush=True); time.sleep(30)",- ),- dict(os.environ),- new_session,- )+backends.sync_notebook_async = missing_metadata+main(prog_name="marimo")+"""++ env = dict(os.environ)+ if phase == "preparation":+ # Stop in the real preparation path before an export worker exists.+ command = tmp_path / "uv"+ command.write_text(+ f"#!{sys.executable}\n"+ "import os, signal, sys\nfrom pathlib import Path\n"+ "if '--version' in sys.argv:\n"+ " print('uv 0.12.0')\n"+ "elif 'sync' in sys.argv:\n"+ f" Path({str(ready)!r}).write_text(str(os.getpid()))\n"+ " signal.pause()\n",+ encoding="utf-8",+ )+ command.chmod(0o755)+ env["UV"] = str(command)+ code = "from marimo._cli.cli import main; main(prog_name='marimo')"++ children: list[psutil.Process] = []with (- patch(- "marimo._environments.backends.launch_fallback",- return_value=plan,- ),- patch(- "marimo._cli.export._common.subprocess.Popen", side_effect=launch- ),+ (tmp_path / "stderr").open("w+") as stderr,+ os.fdopen(+ os.open(ready, os.O_RDONLY | os.O_NONBLOCK), "rb"+ ) as readiness,):- with pytest.raises(KeyboardInterrupt):- run_python_subprocess(- sandbox=SandboxTarget(None),- script="",- payload={},- action="export",+ parent = subprocess.Popen(+ [+ sys.executable,+ "-c",+ code,+ "export",+ "session",+ str(tmp_path),+ "--sandbox",+ ],+ cwd=tmp_path,+ env=env,+ stdout=subprocess.DEVNULL,+ stderr=stderr,+ start_new_session=True,+ )+ try:+ assert select.select([readiness], [], [], 15)[0], (+ "Sandbox subprocess did not start")- child = children[0]- assert child.poll() is not None- assert child.stdout.closed- assert child.stderr.closed--[email protected](os.name == "nt", reason="POSIX termination signals")-def test_export_sigterm_reaps_isolated_child(tmp_path) -> None:- import signal- import time-- ready = tmp_path / "ready"- code = f"""-import os, sys-from marimo._cli.export._common import SandboxTarget, run_python_subprocess-from marimo._environments import environment, backends-child = "import os,time; from pathlib import Path; Path({str(ready)!r}).write_text(str(os.getpid())); time.sleep(30)"-backends.launch_fallback = lambda *a, **kw: environment.ProcessPlan((sys.executable, '-c', child), dict(os.environ), True)-run_python_subprocess(sandbox=SandboxTarget(None), script='', payload={{}}, action='export')-"""- parent = subprocess.Popen([sys.executable, "-c", code])- child_pid = None- try:- deadline = time.monotonic() + 10- while not ready.exists() and time.monotonic() < deadline:- assert parent.poll() is None- time.sleep(0.02)- child_pid = int(ready.read_text())- parent.send_signal(signal.SIGTERM)- assert parent.wait(timeout=10) == 128 + signal.SIGTERM- with pytest.raises(ProcessLookupError):- os.kill(child_pid, 0)- finally:- parent.kill()- parent.wait(timeout=5)- if child_pid is not None:- try:- os.kill(child_pid, signal.SIGKILL)- except ProcessLookupError:- pass+ active_pid = int(readiness.read())+ children = psutil.Process(parent.pid).children(recursive=True)+ assert active_pid in {child.pid for child in children}+ signum = getattr(signal, signal_name)+ parent.send_signal(signum)+ exit_code = parent.wait(timeout=5)+ _, alive = psutil.wait_procs(children, timeout=5)+ assert not alive, "Export left children running"+ # Click reports KeyboardInterrupt as an aborted command (exit 1).+ assert exit_code == (+ 1 if signal_name == "SIGINT" else 128 + signum+ )+ finally:+ if parent.poll() is None:+ children += psutil.Process(parent.pid).children(recursive=True)+ for child in reversed(children):+ try:+ child.kill()+ except psutil.NoSuchProcess:+ pass+ parent.kill()+ parent.wait(timeout=5)+ stderr.seek(0)+ print(stderr.read())diff --git a/tests/_cli/test_sandbox.py b/tests/_cli/test_sandbox.pyindex 0494e4d6aa..d8a2eaf4e1 100644--- a/tests/_cli/test_sandbox.py+++ b/tests/_cli/test_sandbox.py@@ -8,11 +8,10 @@ from unittest.mock import patchimport pytestfrom marimo._cli.sandbox import (- SandboxMode,_normalize_sandbox_dependencies,_uv_export_script_requirements_txt,construct_uv_command,- resolve_sandbox_mode,+ resolve_sandbox,run_in_sandbox,)from marimo._dependencies.dependencies import DependencyManager@@ -459,8 +458,7 @@ import marimoassert "numpy" in requirements-def test_resolve_sandbox_mode_user_confirms(tmp_path: Path) -> None:- """Test that resolve_sandbox_mode returns SandboxMode.SINGLE when user types 'y'."""+def test_resolve_sandbox_user_confirms(tmp_path: Path) -> None:# Create a file with dependenciesscript_path = tmp_path / "test.py"script_path.write_text(@@ -482,70 +480,12 @@ import marimopatch("marimo._cli.sandbox.is_uv_available", return_value=True),patch("marimo._cli.sandbox.sys.stdin.isatty", return_value=True),):- result = resolve_sandbox_mode(+ result = resolve_sandbox(sandbox=None,+ no_sandbox=False,name=str(script_path),)- assert result is SandboxMode.SINGLE---def test_resolve_sandbox_mode_explicit_single() -> None:- """Test that resolve_sandbox_mode returns SandboxMode.SINGLE for single file with sandbox=True."""- result = resolve_sandbox_mode(- sandbox=True,- name="test.py",- )- assert result is SandboxMode.SINGLE---def test_resolve_sandbox_mode_explicit_false() -> None:- """Test that resolve_sandbox_mode returns None when sandbox=False."""- result = resolve_sandbox_mode(- sandbox=False,- name="test.py",- )- assert result is None---def test_resolve_sandbox_mode_directory(tmp_path: Path) -> None:- """Test that resolve_sandbox_mode returns SandboxMode.MULTI for directories."""- dir_path = tmp_path / "notebooks"- dir_path.mkdir()-- # Directory with sandbox=True returns SandboxMode.MULTI- result = resolve_sandbox_mode(- sandbox=True,- name=str(dir_path),- )- assert result is SandboxMode.MULTI---def test_resolve_sandbox_mode_all_cases(tmp_path: Path) -> None:- """Test resolve_sandbox_mode for all cases."""- dir_path = tmp_path / "notebooks"- dir_path.mkdir()- file_path = tmp_path / "notebook.py"- file_path.write_text("# test")-- # sandbox=False always returns None- assert resolve_sandbox_mode(sandbox=False, name=None) is None- assert resolve_sandbox_mode(sandbox=False, name=str(dir_path)) is None- assert resolve_sandbox_mode(sandbox=False, name=str(file_path)) is None-- # sandbox=True with None (current dir) -> SandboxMode.MULTI- assert resolve_sandbox_mode(sandbox=True, name=None) is SandboxMode.MULTI-- # sandbox=True with directory -> SandboxMode.MULTI- assert (- resolve_sandbox_mode(sandbox=True, name=str(dir_path))- is SandboxMode.MULTI- )-- # sandbox=True with file -> SandboxMode.SINGLE- assert (- resolve_sandbox_mode(sandbox=True, name=str(file_path))- is SandboxMode.SINGLE- )+ assert result == "uv"def test_construct_uv_cmd_without_python_version(tmp_path: Path) -> None:@@ -765,47 +705,29 @@ def test_sandbox_exit_codes_propagate(tmp_path: Path) -> None:)runner = CliRunner()- for command, target in (- (- ["edit", str(notebook), "--sandbox", "--headless", "--no-token"],- "marimo._cli.sandbox.run_in_sandbox",- ),- (- ["export", "html", str(notebook), "--sandbox"],- "marimo._cli.export.commands.run_in_sandbox",- ),+ with mock_patch(+ "marimo._cli.export.commands.run_in_sandbox", return_value=3):- with (- mock_patch(target, return_value=3),- mock_patch(- "marimo._cli.sandbox.maybe_prompt_run_in_sandbox",- return_value=True,- ),- ):- result = runner.invoke(cli_main, command)- assert result.exit_code == 3, (command, result.output)---def test_resolve_sandbox_backends(tmp_path: Path) -> None:- from marimo._cli.sandbox import resolve_sandbox-- notebook = tmp_path / "nb.py"- notebook.write_text("import marimo\n")-- mode, backend = resolve_sandbox("pixi", False, str(notebook))- assert mode is SandboxMode.SINGLE- assert backend == "pixi"+ result = runner.invoke(+ cli_main, ["export", "html", str(notebook), "--sandbox"]+ )+ assert result.exit_code == 3, result.output- mode, backend = resolve_sandbox("uv", False, str(notebook))- assert mode is SandboxMode.SINGLE- assert backend == "uv"- mode, backend = resolve_sandbox("pixi", False, str(tmp_path))- assert mode is SandboxMode.MULTI- assert backend == "pixi"[email protected]("name", [None, "notebook.py"])[email protected]("backend", ["uv", "pixi"])+def test_explicit_sandbox_selection(+ name: str | None, backend: str, monkeypatch: pytest.MonkeyPatch+) -> None:+ def unexpected_prompt(_name: str | None) -> bool:+ raise AssertionError("Explicit sandbox flags must not prompt")- mode, backend = resolve_sandbox("pixi", True, str(notebook))- assert mode is None+ monkeypatch.setattr(+ "marimo._cli.sandbox.maybe_prompt_run_in_sandbox", unexpected_prompt+ )+ assert resolve_sandbox(backend, False, name) == backend+ assert resolve_sandbox(backend, True, name) is None+ assert resolve_sandbox(None, True, name) is Nonedef test_strip_sandbox_args() -> None:@@ -819,10 +741,10 @@ def test_strip_sandbox_args() -> None:) == ["-m", "marimo", "edit", "nb.py"]assert _strip_sandbox_args(["-m", "marimo", "edit", "--sandbox", "pixi", "nb.py"]- ) == ["-m", "marimo", "edit", "pixi", "nb.py"]+ ) == ["-m", "marimo", "edit", "nb.py"]assert _strip_sandbox_args(["-m", "marimo", "edit", "--sandbox", "uv"]- ) == ["-m", "marimo", "edit", "uv"]+ ) == ["-m", "marimo", "edit"]assert _strip_sandbox_args(["-m", "marimo", "run", "--sandbox", "nb.py", "--", "--sandbox"]) == ["-m", "marimo", "run", "nb.py", "--", "--sandbox"]@@ -863,3 +785,27 @@ def test_sandbox_launch_normalizes_child_status(process.wait.return_value = returncodewith patch("marimo._cli.sandbox.subprocess.Popen", return_value=process):assert _wait_on_plan(ProcessPlan(argv=("uv",), env={})) == expected+++def test_editor_reports_unsupported_sandbox_backend(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ from click.testing import CliRunner++ from marimo._cli.cli import main+ from marimo._environments.errors import EnvironmentManagerError++ def unavailable(_backend: str) -> None:+ raise EnvironmentManagerError(+ "pixi is too old for script environments"+ )++ monkeypatch.delenv("MARIMO_SERVER_OVERLAY", raising=False)+ monkeypatch.setattr(+ "marimo._environments.backends.ensure_available", unavailable+ )+ result = CliRunner().invoke(+ main, ["new", "--sandbox", "pixi", "--headless"]+ )+ assert result.exit_code == 1+ assert "Error: pixi is too old for script environments" in result.outputdiff --git a/tests/_environments/test_async_preparation.py b/tests/_environments/test_async_preparation.pynew file mode 100644index 0000000000..1bb49119ae--- /dev/null+++ b/tests/_environments/test_async_preparation.py@@ -0,0 +1,244 @@+# Copyright 2026 Marimo. All rights reserved.+from __future__ import annotations++import asyncio+import json+import os+import sys+from contextlib import nullcontext+from pathlib import Path+from typing import TYPE_CHECKING++import pytest++from marimo._environments import script_metadata+from marimo._environments.errors import SandboxRestartRequired+from marimo._environments.overlay import RuntimeOverlay+from marimo._environments.sandbox import NotebookSandbox++if TYPE_CHECKING:+ from marimo._environments.sandbox import Backend++[email protected](params=["uv", "pixi"])+def backend(+ request: pytest.FixtureRequest,+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+) -> Backend:+ if os.name == "nt":+ pytest.skip("Executable script fixtures require POSIX")+ name = request.param+ command = tmp_path / name+ command.write_text(+ f"#!{sys.executable}\n"+ + r"""+import json, os, signal, sys+if '--version' in sys.argv:+ print('uv 0.12.0')+ sys.exit()+if '--help' in sys.argv:+ print('--script')+ sys.exit()+source = sys.argv[sys.argv.index('--script') + 1]+print(json.dumps({'pid': os.getpid(), 'source': source}), file=sys.stderr, flush=True)+signal.pause()+""",+ encoding="utf-8",+ )+ command.chmod(0o755)+ monkeypatch.setenv("UV", str(tmp_path / "uv"))+ monkeypatch.setenv("PATH", str(tmp_path))+ return name+++def markdown(tmp_path: Path) -> Path:+ path = tmp_path / "notebook.md"+ path.write_text(+ "---\npyproject: |\n dependencies = []\n---\n\n# Notebook\n"+ )+ return path+++async def test_cancelled_preparation_releases_carrier(+ backend: Backend, markdown: Path+) -> None:+ import psutil++ original = markdown.read_text() # noqa: ASYNC240+ ready = asyncio.Event()+ command: dict[str, str | int] = {}++ def on_output(line: str) -> None:+ command.update(json.loads(line))+ ready.set()++ sandbox = NotebookSandbox(str(markdown), backend)+ task = asyncio.create_task(+ sandbox.launch_async(+ [], overlay=RuntimeOverlay("marimo"), on_output=on_output+ )+ )+ try:+ await asyncio.wait_for(ready.wait(), timeout=5)+ carrier = Path(str(command["source"]))+ assert carrier.exists() # noqa: ASYNC240+ task.cancel()+ with pytest.raises(asyncio.CancelledError):+ await asyncio.wait_for(asyncio.shield(task), timeout=5)+ assert not psutil.pid_exists(int(command["pid"]))+ assert not carrier.exists() # noqa: ASYNC240+ assert markdown.read_text() == original # noqa: ASYNC240+ assert sandbox.environment is None+ finally:+ task.cancel()+ await asyncio.gather(task, return_exceptions=True)+ sandbox.close()+++async def test_waiting_for_carrier_lock_is_cancellable(markdown: Path) -> None:+ started = asyncio.Event()++ async def wait_for_carrier() -> None:+ started.set()+ async with script_metadata.materialized_for_environment_async(+ str(markdown)+ ):+ pytest.fail("Acquired a carrier still owned by another operation")++ with script_metadata.materialized_for_environment(str(markdown)) as owner:+ task = asyncio.create_task(wait_for_carrier())+ try:+ await started.wait()+ task.cancel()+ with pytest.raises(asyncio.CancelledError):+ await asyncio.wait_for(asyncio.shield(task), timeout=2)+ assert Path(owner.path).exists() # noqa: ASYNC240+ finally:+ task.cancel()+ await asyncio.gather(task, return_exceptions=True)+ async with script_metadata.materialized_for_environment_async(+ str(markdown)+ ) as next_owner:+ assert next_owner.path == owner.path+++async def test_failed_preparation_leaves_notebook_directory_clean(+ markdown: Path,+) -> None:+ from unittest.mock import AsyncMock, MagicMock++ from marimo._environments.errors import EnvironmentManagerError++ adapter = MagicMock()+ adapter.name = "uv"+ adapter.ensure_available_async = AsyncMock()+ adapter.prepare_source_async = AsyncMock()+ adapter.sync_async = AsyncMock(+ side_effect=EnvironmentManagerError("No solution found")+ )+ sandbox = NotebookSandbox(str(markdown), "uv", adapter=adapter)+ try:+ with pytest.raises(EnvironmentManagerError, match="No solution found"):+ await sandbox.launch_async([], overlay=RuntimeOverlay("marimo"))+ finally:+ sandbox.close()+ assert list(markdown.parent.iterdir()) == [markdown]++[email protected]("backend", ["uv", "pixi"])+async def test_sync_running_sandbox_retains_active_environment(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, backend: str+) -> None:+ from unittest.mock import AsyncMock++ from marimo._environments.backends import (+ PixiBackendAdapter,+ UvBackendAdapter,+ )+ from marimo._environments.environment import Environment+ from marimo._environments.errors import SandboxRestartRequired+ from marimo._environments.sandbox import NotebookSandbox++ source = tmp_path / "notebook.py"+ source.write_text("# /// script\n# dependencies = []\n# ///\n")+ active = Environment(+ python="/active/bin/python", root="/active", action="unchanged"+ )+ moved = Environment(+ python="/other/bin/python", root="/other", action="updated"+ )+ adapter = UvBackendAdapter() if backend == "uv" else PixiBackendAdapter()+ monkeypatch.setattr(adapter, "ensure_available_async", AsyncMock())+ sync = AsyncMock(return_value=active if backend == "uv" else moved)+ target = (+ "marimo._environments.environment.sync_async"+ if backend == "uv"+ else "marimo._environments.pixi.sync_async"+ )+ monkeypatch.setattr(target, sync)+ sandbox = NotebookSandbox(+ str(source), backend, environment=active, adapter=adapter+ )+ if backend == "pixi":+ with pytest.raises(SandboxRestartRequired):+ await sandbox.sync_async()+ else:+ await sandbox.sync_async()+ assert sync.call_args.kwargs["active_environment"] == active+ assert sandbox.environment == active+++ ("operation", "requirement", "expected_error"),+ [+ ("sync", "==2.7.*", SandboxRestartRequired),+ ("remove", "==2.7.*", SandboxRestartRequired),+ ("sync", ">=3.0", None),+ ("remove", ">=3.0", None),+ ("sync", "invalid", script_metadata.ScriptMetadataError),+ ("sync", 42, script_metadata.ScriptMetadataError),+ ],+)+async def test_sync_checks_active_python_before_mutating_environment(+ tmp_path: Path,+ requirement: str | int,+ operation: str,+ expected_error: type[Exception] | None,+) -> None:+ from unittest.mock import AsyncMock, MagicMock++ from marimo._environments.environment import Environment++ source = tmp_path / "notebook.py"+ active = Environment(+ python=sys.executable, root=sys.prefix, action="unchanged"+ )++ adapter = MagicMock()+ adapter.name = "uv"+ adapter.ensure_available_async = AsyncMock()+ adapter.sync_async = AsyncMock(return_value=active)+ adapter.sync.return_value = active+ sandbox = NotebookSandbox(+ str(source), "uv", environment=active, adapter=adapter+ )+ manifest = (+ f"dependencies = []\nrequires-python = {json.dumps(requirement)}\n"+ )+ source.write_text(script_metadata.wrap_block(manifest))++ with pytest.raises(expected_error) if expected_error else nullcontext():+ if operation == "sync":+ await sandbox.sync_async()+ else:+ await asyncio.to_thread(sandbox.remove, "requests")++ sync = adapter.sync_async if operation == "sync" else adapter.sync+ if expected_error:+ sync.assert_not_called()+ else:+ sync.assert_called_once()diff --git a/tests/_environments/test_environment.py b/tests/_environments/test_environment.pyindex 6815653c7f..84e2f4e146 100644--- a/tests/_environments/test_environment.py+++ b/tests/_environments/test_environment.py@@ -268,14 +268,6 @@ def test_launch_layers_over_the_activated_environment() -> None:assert plan.start_new_session-def test_isolated_launcher_plan_starts_a_new_session() -> None:- isolated = environment.launch_isolated(- ["-m", "marimo"], requirements=["marimo"], python="3.13"- )-- assert isolated.start_new_session--@pytest.mark.network@pytest.mark.skipif(not SUPPORTS_SYNC, reason="uv >= 0.7.21 required")def test_launch_overlay_chains_without_mutating(diff --git a/tests/_environments/test_process.py b/tests/_environments/test_process.pynew file mode 100644index 0000000000..46630b0a2b--- /dev/null+++ b/tests/_environments/test_process.py@@ -0,0 +1,204 @@+# Copyright 2026 Marimo. All rights reserved.+from __future__ import annotations++import asyncio+import json+import os+import sys+import threading+from concurrent.futures import ThreadPoolExecutor+from typing import TYPE_CHECKING++import pytest++from marimo._environments.process import run_command++if TYPE_CHECKING:+ from pathlib import Path+++async def test_command_captures_output_and_exit_status(tmp_path: Path) -> None:+ # Fill both pipes beyond their buffers so sequential reads would hang.+ code = r"""+import json, os, sys+print(json.dumps([os.getcwd(), os.environ['SANDBOX_TEST_VALUE']]))+sys.stdout.write('x' * 131072)+sys.stdout.flush()+sys.stderr.write('y' * 131072 + '\nfinished 🎲\n')+sys.exit(3)+"""+ lines: list[str] = []+ result = await run_command(+ [sys.executable, "-c", code],+ cwd=str(tmp_path),+ env={+ **os.environ,+ "PYTHONIOENCODING": "utf-8",+ "SANDBOX_TEST_VALUE": "value with spaces",+ },+ on_stderr=lines.append,+ timeout=10,+ )+ context, stdout = result.stdout.split("\n", 1)+ expected_cwd = str(tmp_path.resolve()) # noqa: ASYNC240+ assert json.loads(context) == [expected_cwd, "value with spaces"]+ assert stdout == "x" * 131072+ assert result.stderr == "y" * 131072 + "\nfinished 🎲\n"+ assert "".join(lines) == result.stderr+ assert result.returncode == 3++[email protected](os.name == "nt", reason="POSIX process groups")[email protected]("stop", ["cancel", "timeout"])+async def test_stopping_command_cleans_up_after_launcher_exits(+ stop: str,+) -> None:+ import psutil++ # The child keeps the capture pipes open after its launcher exits.+ child_code = """+import os, signal, sys+sys.stdin.read()+print(f'{sys.argv[1]} {os.getpid()}', file=sys.stderr, flush=True)+signal.pause()+"""+ code = f"""+import os, subprocess, sys+subprocess.Popen(+ [sys.executable, '-c', {child_code!r}, str(os.getpid())],+ stdin=subprocess.PIPE,+)+"""+ ready = asyncio.Event()+ pids: list[int] = []++ def on_stderr(line: str) -> None:+ pids.extend(map(int, line.split()))+ ready.set()++ task = asyncio.create_task(+ run_command(+ [sys.executable, "-c", code],+ on_stderr=on_stderr,+ timeout=3 if stop == "timeout" else None,+ )+ )+ try:+ await asyncio.wait_for(ready.wait(), timeout=5)+ launcher, child = (psutil.Process(pid) for pid in pids)+ await asyncio.to_thread(launcher.wait, timeout=5)+ if stop == "cancel":+ assert not task.done()+ task.cancel()+ with pytest.raises(+ asyncio.CancelledError+ if stop == "cancel"+ else asyncio.TimeoutError+ ):+ await asyncio.wait_for(asyncio.shield(task), timeout=5)+ _, alive = await asyncio.to_thread(+ psutil.wait_procs, [child], timeout=5+ )+ assert not alive, "Cancelled command left its child running"+ finally:+ for pid in reversed(pids):+ try:+ psutil.Process(pid).kill()+ except psutil.NoSuchProcess:+ pass+ task.cancel()+ await asyncio.gather(task, return_exceptions=True)+++async def test_repeated_cancellation_waits_for_cleanup_without_blocking(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ from marimo._utils import subprocess as subprocess_utils++ loop = asyncio.get_running_loop()+ ready = asyncio.Event()+ stopping = asyncio.Event()+ release = threading.Event()+ kill = subprocess_utils.kill_subprocess+ processes = []++ def slow_kill(process, *, start_new_session):+ processes.append(process)+ loop.call_soon_threadsafe(stopping.set)+ try:+ assert release.wait(timeout=10)+ finally:+ kill(process, start_new_session=start_new_session)++ monkeypatch.setattr(subprocess_utils, "kill_subprocess", slow_kill)+ task = asyncio.create_task(+ run_command(+ [+ sys.executable,+ "-c",+ "import sys,time; print('ready', file=sys.stderr, flush=True); time.sleep(60)",+ ],+ on_stderr=lambda _line: ready.set(),+ )+ )+ try:+ await asyncio.wait_for(ready.wait(), timeout=5)+ task.cancel()+ await asyncio.wait_for(stopping.wait(), timeout=5)+ task.cancel()+ await asyncio.sleep(0)+ assert not task.done()+ release.set()+ with pytest.raises(asyncio.CancelledError):+ await asyncio.wait_for(task, timeout=5)+ assert processes[0].poll() is not None+ finally:+ release.set()+ task.cancel()+ await asyncio.gather(task, return_exceptions=True)+++async def test_cancellation_with_saturated_default_executor() -> None:+ import psutil++ loop = asyncio.get_running_loop()+ ready = asyncio.Event()+ child: psutil.Process | None = None++ def on_stderr(line: str) -> None:+ nonlocal child+ child = psutil.Process(int(line))+ ready.set()++ # One reader per pipe occupies every worker until the child dies.+ executor = ThreadPoolExecutor(max_workers=2)+ loop.set_default_executor(executor)+ task = asyncio.create_task(+ run_command(+ [+ sys.executable,+ "-c",+ "import os,sys,time; print(os.getpid(), file=sys.stderr, flush=True); time.sleep(60)",+ ],+ on_stderr=on_stderr,+ )+ )+ try:+ await asyncio.wait_for(ready.wait(), timeout=5)+ task.cancel()+ with pytest.raises(asyncio.CancelledError):+ await asyncio.wait_for(asyncio.shield(task), timeout=2)+ assert child is not None+ assert not child.is_running()+ finally:+ if child is not None:+ try:+ child.kill()+ except psutil.NoSuchProcess:+ pass+ task.cancel()+ await asyncio.gather(task, return_exceptions=True)+ loop.set_default_executor(ThreadPoolExecutor())+ executor.shutdown()diff --git a/tests/_environments/test_sandbox_interface.py b/tests/_environments/test_sandbox_interface.pyindex 6d09b209cd..35d1ff6432 100644--- a/tests/_environments/test_sandbox_interface.py+++ b/tests/_environments/test_sandbox_interface.py@@ -115,7 +115,7 @@ class FakeBackend:del python_override, on_output, active_environmentself.sync_targets.append(target.path)return Environment(- python=str(self.root / "bin" / "python"),+ python=sys.executable,root=str(self.root),action="updated",)@@ -578,7 +578,7 @@ def test_runtime_dependency_cannot_be_removed(tmp_path: Path) -> None:assert adapter.sync_targets == []-def test_package_view_hides_runtime_dependency(tmp_path: Path) -> None:+def test_package_view_includes_runtime_dependency(tmp_path: Path) -> None:notebook = tmp_path / "notebook.py"notebook.write_text("# /// script\n# dependencies = []\n# ///\n")adapter = FakeBackend(tmp_path / "environment")@@ -607,9 +607,14 @@ def test_package_view_hides_runtime_dependency(tmp_path: Path) -> None:state = sandbox.packages()- assert [package.name for package in state.packages] == ["obstore"]+ assert [(package.name, package.version) for package in state.packages] == [+ ("obstore", "0.8.2"),+ ("marimo", "0.24.0"),+ ]assert state.tree is not None- assert [node.name for node in state.tree.dependencies] == []+ assert [(node.name, node.version) for node in state.tree.dependencies] == [+ ("marimo", "0.24.0")+ ]def test_pixi_launch_layers_the_runtime_overlay_through_uv(diff --git a/tests/_environments/test_script_metadata.py b/tests/_environments/test_script_metadata.pyindex 4166bb7cfd..535677904e 100644--- a/tests/_environments/test_script_metadata.py+++ b/tests/_environments/test_script_metadata.py@@ -392,9 +392,14 @@ pyproject: |with script_metadata.materialized_for_environment(str(notebook)) as second:assert second.path == first.path+ assert list(tmp_path.iterdir()) == [notebook]-def _enter_carrier(notebook, attempting, entered):+def _enter_carrier(notebook, attempting, entered, temporary_directory):+ if temporary_directory is not None:+ import tempfile++ tempfile.tempdir = temporary_directoryattempting.set()with script_metadata.materialized_for_environment(notebook):entered.set()@@ -415,8 +420,16 @@ def test_stable_carrier_lifetime_is_serialized(attempting = context.Event()entered = context.Event()worker_type = context.Process if separate_process else threading.Thread+ temporary_directory = tmp_path / "worker-tmp"+ temporary_directory.mkdir()worker = worker_type(- target=_enter_carrier, args=(str(notebook), attempting, entered)+ target=_enter_carrier,+ args=(+ str(notebook),+ attempting,+ entered,+ str(temporary_directory) if separate_process else None,+ ),)with script_metadata.materialized_for_environment(str(notebook)@@ -447,35 +460,78 @@ def test_old_active_carriers_are_preserved(tmp_path: Path) -> None:assert carrier.exists()def test_stranded_stable_carrier_is_reclaimed(tmp_path: Path) -> None:notebook = tmp_path / "notebook.md"notebook.write_text("---\npyproject: |\n dependencies = []\n---\n")- stranded = tmp_path / ".marimo-v1-notebook.md.py"- stranded.write_text("stranded")+ worker = subprocess.Popen(+ [+ sys.executable,+ "-c",+ (+ "import sys, time\n"+ "from marimo._environments import script_metadata\n"+ "with script_metadata.materialized_for_environment(sys.argv[1]) as target:\n"+ " print(target.path, flush=True)\n"+ " time.sleep(60)\n"+ ),+ str(notebook),+ ],+ stdout=subprocess.PIPE,+ text=True,+ )+ try:+ assert worker.stdout is not None+ stranded = Path(worker.stdout.readline().strip())+ assert stranded.is_file()+ finally:+ worker.kill()+ worker.wait(timeout=5)+ if worker.stdout is not None:+ worker.stdout.close()+ assert stranded.exists()+ notebook.write_text(+ '---\npyproject: |\n dependencies = ["requests"]\n---\n'+ )with script_metadata.materialized_for_environment(str(notebook)) as materialized:- assert "dependencies = []" in Path(materialized.path).read_text()+ assert (+ 'dependencies = ["requests"]'+ in Path(materialized.path).read_text()+ )assert not stranded.exists()[email protected]("suffix", [".py", ".lock"])[email protected]("kind", ["carrier", "lock"])def test_carrier_symlinks_do_not_modify_target(- tmp_path: Path, suffix: str+ tmp_path: Path,+ kind: str,) -> None:notebook = tmp_path / "notebook.md"notebook.write_text("---\npyproject: |\n dependencies = []\n---\n")target = tmp_path / "precious.txt"target.write_text("do not touch")- link = tmp_path / f".marimo-v1-notebook.md{suffix}"+ link = (+ tmp_path / ".marimo-v1-notebook.md.py"+ if kind == "carrier"+ else script_metadata._notebook_lock_path(str(notebook)).with_suffix(+ ".carrier.lock"+ )+ )try:link.symlink_to(target)except OSError:pytest.skip("symlinks unavailable")- with pytest.raises(script_metadata.ScriptMetadataError, match="symlink"):- with script_metadata.materialized_for_environment(str(notebook)):- pytest.fail("must reject the symlink")- assert target.read_text() == "do not touch"+ try:+ with pytest.raises(+ script_metadata.ScriptMetadataError, match="symlink"+ ):+ with script_metadata.materialized_for_environment(str(notebook)):+ pytest.fail("must reject the symlink")+ assert target.read_text() == "do not touch"+ finally:+ link.unlink()@pytest.mark.skipif(@@ -503,3 +559,90 @@ def test_readonly_notebook_directory_fails_clearly(pytest.fail("must preserve adjacent path semantics")finally:os.chmod(tmp_path, 0o700)++[email protected]("suffix", [".py", ".md", ".qmd"])[email protected]("newline", ["\n", "\r\n"])+def test_replace_whole_manifest_preserves_custom_tables_and_notebook(+ tmp_path: Path, suffix: str, newline: str+) -> None:+ path = tmp_path / f"notebook{suffix}"+ original = 'dependencies = ["numpy==0.0.0"]\n'+ replacement = '''# Keep this comment and the user's table order.+notes = """+/// example+"""++[tool.custom]+label = "my experiment"++[tool.uv.sources]+numpy = { path = "../numpy", editable = true }++[tool.pixi.dependencies]+python = ">=3.12"+'''+ body = "\n# Notebook content\nprint('unchanged')\n"+ if suffix == ".py":+ source = script_metadata.wrap_block(original) + "\n" + body+ else:+ source = (+ "---\ntitle: My notebook\npyproject: |\n"+ ' dependencies = ["numpy==0.0.0"]\n---\n' + body+ )+ path.write_bytes(source.replace("\n", newline).encode())+ previous = script_metadata.read_manifest(str(path))+ saved = script_metadata.write_manifest(+ str(path), replacement, previous=previous+ )+ assert saved == replacement+ assert path.read_bytes().endswith(body.replace("\n", newline).encode())+ if suffix != ".py":+ assert "title: My notebook" in path.read_text()+++def test_manifest_repair_rejects_stale_edits_but_preserves_new_code(+ tmp_path: Path,+) -> None:+ path = tmp_path / "notebook.py"+ broken = "dependencies = [\n"+ path.write_text(script_metadata.wrap_block(broken) + "\nprint('old')\n")+ previous = script_metadata.read_manifest(str(path))+ path.write_text(path.read_text().replace("print('old')", "print('new')"))+ script_metadata.write_manifest(+ str(path), "[tool.custom]\nvalue = 1\n", previous=previous+ )+ saved = path.read_text()+ with pytest.raises(script_metadata.ManifestConflictError):+ script_metadata.write_manifest(+ str(path), "dependencies = []\n", previous=previous+ )+ with pytest.raises(ValueError):+ script_metadata.write_manifest(str(path), broken, previous=previous)+ with pytest.raises(+ script_metadata.ScriptMetadataError, match="script markers"+ ):+ script_metadata.write_manifest(+ str(path),+ 'value = """\n///\n"""\n',+ previous=script_metadata.read_manifest(str(path)),+ )+ assert path.read_text() == saved+ assert saved.endswith("print('new')\n")+++def test_manifest_replacement_preserves_crlf_notebook_code(+ tmp_path: Path,+) -> None:+ path = tmp_path / "notebook.py"+ path.write_bytes(+ b'# /// script\r\n# dependencies = []\r\n# ///\r\nprint("keep")\r\n'+ )+ previous = script_metadata.read_manifest(str(path))+ script_metadata.write_manifest(+ str(path), "[tool.custom]\nvalue = 1\n", previous=previous+ )+ assert (+ path.read_bytes()+ == b'# /// script\r\n# [tool.custom]\r\n# value = 1\r\n# ///\r\nprint("keep")\r\n'+ )diff --git a/tests/_server/api/endpoints/test_packages.py b/tests/_server/api/endpoints/test_packages.pyindex 7a3736df91..23d0ba50be 100644--- a/tests/_server/api/endpoints/test_packages.py+++ b/tests/_server/api/endpoints/test_packages.py@@ -850,14 +850,13 @@ def test_remove_package_with_dev_dependency(def test_get_package_manager_uses_ipc_venv_python() -> None:"""Test that _get_package_manager uses venv Python from IPC kernel."""from marimo._server.api.endpoints.packages import _get_package_manager+ from marimo._session.managers.ipc import IPCKernelManagerImpl+ from marimo._session.session import SessionImpl- # Mock the session with an IPC kernel manager having venv_python set- mock_kernel_manager = MagicMock()+ mock_kernel_manager = MagicMock(spec=IPCKernelManagerImpl)mock_kernel_manager.venv_python = "/custom/venv/python"- mock_kernel_manager.script_environment = None-- mock_session = MagicMock()+ mock_session = MagicMock(spec=SessionImpl)mock_session._kernel_manager = mock_kernel_managermock_session.notebook_sandbox = None@@ -876,19 +875,6 @@ def test_get_package_manager_uses_ipc_venv_python() -> None:patch("marimo._server.api.endpoints.packages.create_package_manager") as mock_create_pm,- patch(- "marimo._server.api.endpoints.packages.isinstance",- side_effect=lambda obj, cls: (- cls.__name__ == "SessionImpl"- if hasattr(cls, "__name__") and cls.__name__ == "SessionImpl"- else (- cls.__name__ == "IPCKernelManagerImpl"- if hasattr(cls, "__name__")- and cls.__name__ == "IPCKernelManagerImpl"- else isinstance(obj, cls)- )- ),- ),):_get_package_manager(mock_request)@@ -896,49 +882,6 @@ def test_get_package_manager_uses_ipc_venv_python() -> None:mock_create_pm.assert_called_once_with("pip",python_exe="/custom/venv/python",- script_path=None,- sandbox_environment=None,- )---def test_get_package_manager_with_script_environment() -> None:- """A kernel synchronized into a script environment routes package- changes through it."""- from marimo._server.api.endpoints.packages import _get_package_manager-- mock_kernel_manager = MagicMock()- mock_kernel_manager.venv_python = "/env/bin/python"- mock_kernel_manager.script_environment = object()-- mock_session = MagicMock()- mock_session._kernel_manager = mock_kernel_manager- mock_session.notebook_sandbox = None- mock_session.app_file_manager.filename = "/nb/notebook.py"-- mock_app_state = MagicMock()- mock_app_state.get_current_session.return_value = mock_session- mock_app_state.app_config_manager.package_manager = "uv"-- with (- patch(- "marimo._server.api.endpoints.packages.AppState",- return_value=mock_app_state,- ),- patch(- "marimo._server.api.endpoints.packages.create_package_manager"- ) as mock_create_pm,- patch(- "marimo._server.api.endpoints.packages.isinstance",- side_effect=lambda _obj, cls: cls.__name__ != "NotebookSandbox",- ),- ):- _get_package_manager(MagicMock())-- mock_create_pm.assert_called_once_with(- "uv",- python_exe="/env/bin/python",- script_path="/nb/notebook.py",- sandbox_environment=mock_kernel_manager.script_environment,)@@ -971,9 +914,7 @@ def test_get_package_manager_without_ipc_session() -> None:_get_package_manager(mock_request)# Verify create_package_manager was called with python_exe=None- mock_create_pm.assert_called_once_with(- "uv", python_exe=None, script_path=None, sandbox_environment=None- )+ mock_create_pm.assert_called_once_with("uv", python_exe=None)def test_get_package_manager_no_session() -> None:@@ -1002,35 +943,122 @@ def test_get_package_manager_no_session() -> None:mock_create_pm.assert_called_once_with("pip")[email protected]("mode", ["single", None])-def test_package_manager_binding_for_inprocess_kernel(- monkeypatch: pytest.MonkeyPatch, mode: str | None[email protected]("backend", ["uv", "pixi"])+def test_repair_manifest_without_a_kernel(+ client: TestClient, tmp_path, monkeypatch: pytest.MonkeyPatch, backend: str) -> None:- from marimo._config.settings import GLOBAL_SETTINGS- from marimo._server.api.endpoints.packages import _get_package_manager- from marimo._session.session import SessionImpl+ from marimo._server.workspace import SingleFileWorkspace+ from marimo._utils.marimo_path import MarimoPath- monkeypatch.setattr(GLOBAL_SETTINGS, "SANDBOX_MODE", mode)- session = MagicMock(spec=SessionImpl)- session.notebook_sandbox = None- session._kernel_manager = MagicMock(spec=[])- session.app_file_manager = MagicMock(filename="/nb/notebook.py")- state = MagicMock()- state.get_current_session.return_value = session- state.app_config_manager.package_manager = "uv"- with (- patch(- "marimo._server.api.endpoints.packages.AppState",- return_value=state,- ),- patch(- "marimo._server.api.endpoints.packages.create_package_manager"- ) as create,- ):- _get_package_manager(MagicMock())- create.assert_called_once_with(- "uv",- python_exe=None,- script_path="/nb/notebook.py" if mode == "single" else None,- sandbox_environment=None,+ path = tmp_path / "notebook.py"+ path.write_text(+ '# /// script\n# dependencies = ["numpy==0.0.0"]\n# ///\n'+ "import marimo\napp = marimo.App()\n"+ )+ manager = client.app.state.session_manager+ manager.sandbox = True+ manager.workspace = SingleFileWorkspace.from_path(MarimoPath(str(path)))+ monkeypatch.setattr(+ "marimo._server.api.endpoints.packages.current_backend",+ lambda: backend,+ )+ request = {"fileKey": str(path)}+ response = client.post(+ "/api/packages/sandbox", headers=HEADERS, json=request+ )+ assert response.status_code == 200+ assert response.json() == {+ "backend": backend,+ "filename": str(path),+ "manifest": 'dependencies = ["numpy==0.0.0"]\n',+ }+ update = {+ **request,+ "previous": response.json()["manifest"],+ "contents": '[tool.custom]\nmessage = "whole manifest"\n',+ }+ response = client.post(+ "/api/packages/manifest", headers=HEADERS, json=update+ )+ assert response.status_code == 200+ assert response.json()["manifest"] == update["contents"]+ assert path.read_text().endswith("import marimo\napp = marimo.App()\n")+ response = client.post(+ "/api/packages/manifest", headers=HEADERS, json=update+ )+ assert response.status_code == 409+ response = client.post("/api/packages/sync", headers=HEADERS, json=request)+ assert response.json() == {+ "success": True,+ "error": None,+ "restartRequired": False,+ "reconnect": True,+ }+++def test_manifest_access_uses_workspace_permissions(+ client: TestClient, tmp_path+) -> None:+ from marimo._server.workspace import SingleFileWorkspace+ from marimo._utils.marimo_path import MarimoPath++ allowed = tmp_path / "allowed.py"+ denied = tmp_path / "denied.py"+ allowed.write_text("import marimo\napp = marimo.App()\n")+ denied.write_text("private = True\n")+ manager = client.app.state.session_manager+ manager.sandbox = True+ manager.workspace = SingleFileWorkspace.from_path(MarimoPath(str(allowed)))+ response = client.post(+ "/api/packages/manifest",+ headers=HEADERS,+ json={+ "fileKey": str(denied),+ "contents": "value = 1",+ "previous": "",+ },+ )+ assert response.status_code == 404+ assert denied.read_text() == "private = True\n"+++ ("endpoint", "operation"),+ [("sandbox", "read_manifest"), ("manifest", "write_manifest")],+)+def test_manifest_file_errors_are_reported(+ client: TestClient,+ tmp_path,+ monkeypatch: pytest.MonkeyPatch,+ endpoint: str,+ operation: str,+) -> None:+ from marimo._server.workspace import SingleFileWorkspace+ from marimo._utils.marimo_path import MarimoPath++ path = tmp_path / "notebook.py"+ path.write_text("import marimo\napp = marimo.App()\n")+ manager = client.app.state.session_manager+ manager.sandbox = True+ manager.workspace = SingleFileWorkspace.from_path(MarimoPath(str(path)))+ monkeypatch.setattr(+ "marimo._server.api.endpoints.packages.current_backend", lambda: "uv"+ )++ def denied(*_args: Any, **_kwargs: Any) -> None:+ raise PermissionError("Permission denied for notebook manifest")++ monkeypatch.setattr(+ f"marimo._environments.script_metadata.{operation}", denied+ )+ response = client.post(+ f"/api/packages/{endpoint}",+ headers=HEADERS,+ json={+ "fileKey": str(path),+ "contents": "dependencies = []",+ "previous": "",+ },)+ assert response.status_code == 400+ assert "Permission denied for notebook manifest" in response.textdiff --git a/tests/_server/api/endpoints/test_sse.py b/tests/_server/api/endpoints/test_sse.pyindex 1c9542c693..4441a7663a 100644--- a/tests/_server/api/endpoints/test_sse.py+++ b/tests/_server/api/endpoints/test_sse.py@@ -3,14 +3,18 @@ from __future__ import annotationsimport asyncioimport json+import sysimport threadingfrom functools import partialfrom typing import TYPE_CHECKING, Any-from unittest.mock import MagicMock, patch+from unittest.mock import AsyncMock, MagicMock, patchimport pytest-from marimo._messaging.notification import AlertNotification+from marimo._messaging.notification import (+ AlertNotification,+ StartupProgressNotification,+)from marimo._messaging.serde import serialize_kernel_messagefrom marimo._server.api.endpoints.ws.sse_handler import SSESessionHandlerfrom marimo._server.api.endpoints.ws.ws_connection_validator import (@@ -30,6 +34,8 @@ from tests._server.api.endpoints.ws_helpers import (from tests._server.mocks import get_session_managerif TYPE_CHECKING:+ from pathlib import Path+from starlette.applications import Starlettefrom starlette.testclient import TestClientfrom typing_extensions import Self@@ -290,6 +296,80 @@ async def test_sse_kernel_startup_error(client: TestClient) -> None:)[email protected]("outcome", ["ready", "error", "disconnect"])+async def test_sandbox_progress_during_preparation(+ client: TestClient,+ monkeypatch: pytest.MonkeyPatch,+ tmp_path: Path,+ outcome: str,+) -> None:+ from marimo._session.managers import ipc++ release = asyncio.Event()+ cleaned_up = asyncio.Event()++ async def check_environment(_python: str) -> bool:+ try:+ await release.wait()+ return True+ finally:+ cleaned_up.set()++ # A configured interpreter that disappears before launch lets the test+ # observe both phases and a real launch failure without spawning a kernel.+ monkeypatch.setattr(+ ipc,+ "get_configured_venv_python",+ lambda *_args, **_kwargs: (+ sys.executable+ if outcome == "ready"+ else str(tmp_path / "missing-python")+ ),+ )+ monkeypatch.setattr(ipc, "has_marimo_installed", check_environment)+ manager = get_session_manager(client)+ manager.sandbox = True++ async with _connect(client) as connection:+ event = await connection.next_event()+ assert json.loads(event["data"]) == {+ "op": "startup-progress",+ "data": {+ "op": "startup-progress",+ "phase": "preparing-environment",+ },+ }+ assert not manager.sessions+ if outcome == "disconnect":+ connection.disconnect()+ await asyncio.wait_for(cleaned_up.wait(), timeout=5)+ else:+ release.set()+ event = await connection.next_event()+ assert json.loads(event["data"]) == {+ "op": "startup-progress",+ "data": {+ "op": "startup-progress",+ "phase": "starting-kernel",+ },+ }+ event = await connection.next_event()+ message = json.loads(event["data"])+ if outcome == "ready":+ assert_kernel_ready_response(message)+ else:+ assert message["op"] == "kernel-startup-error"+ assert (+ "Failed to start kernel subprocess"+ in message["data"]["error"]+ )+ await _expect_close(+ connection, 1011, "MARIMO_KERNEL_STARTUP_ERROR"+ )+ if outcome != "ready":+ assert not manager.sessions++async def test_sse_kiosk_without_session(client: TestClient) -> None:async with _connect(client, f"{SSE_QUERY}&kiosk=true") as connection:await _expect_close(connection, 1000, "MARIMO_NO_SESSION")@@ -364,8 +444,18 @@ def _make_handler(# Bypass SessionConnector; unit tests drive the handler directlysession = MagicMock()session.room.main_consumer = handler- handler._connect_session = MagicMock( # type: ignore[method-assign]- return_value=(session, ConnectionType.NEW)+ session.ttl_seconds = 120+ session.disconnect_consumer.side_effect = lambda consumer: (+ consumer.on_detach()+ )+ handler.manager.get_session.return_value = session++ async def connect(_request: Any) -> tuple[Any, ConnectionType]:+ handler.on_attach(session, MagicMock())+ return session, ConnectionType.NEW++ handler._connect_session = AsyncMock( # type: ignore[method-assign]+ side_effect=connect)return handler@@ -416,6 +506,27 @@ async def test_stream_does_not_connect_until_iterated() -> None:handler._connect_session.assert_not_called()+async def test_disconnect_during_startup_progress_detaches_session() -> None:+ request = MagicMock()+ request._receive = _never_receive()+ handler = _make_handler(request)+ session = handler.manager.get_session.return_value+ handler.notify(+ serialize_kernel_message(+ StartupProgressNotification(phase="starting-kernel")+ )+ )++ stream = handler.stream()+ assert "startup-progress" in await anext(stream)+ await asyncio.sleep(0) # Complete attachment while the yield is suspended.+ await stream.aclose()++ session.disconnect_consumer.assert_called_once_with(handler)+ assert handler.connection_state() == ConnectionState.CLOSED+ assert not handler._is_transport_connected()++async def test_stream_flushes_pending_messages_before_close() -> None:"""Messages enqueued before a server close are sent, then the close."""request = MagicMock()diff --git a/tests/_server/api/endpoints/test_ws.py b/tests/_server/api/endpoints/test_ws.pyindex 97b1f45d02..1cecb2aa4b 100644--- a/tests/_server/api/endpoints/test_ws.py+++ b/tests/_server/api/endpoints/test_ws.py@@ -5,17 +5,23 @@ import asynciofrom contextlib import contextmanagerfrom pathlib import Pathfrom typing import TYPE_CHECKING, Any-from unittest.mock import MagicMock, patch+from unittest.mock import AsyncMock, MagicMock, patchimport pytestfrom starlette.websockets import WebSocketDisconnectfrom marimo._config.config import ExperimentalConfigfrom marimo._config.manager import UserConfigManager-from marimo._messaging.notification import KernelReadyNotification+from marimo._messaging.notification import (+ KernelReadyNotification,+ StartupProgressNotification,+)+from marimo._messaging.serde import serialize_kernel_messagefrom marimo._server.api.endpoints.ws.ws_connection_validator import (ConnectionParams,)+from marimo._server.api.endpoints.ws.ws_session_connector import ConnectionType+from marimo._server.api.endpoints.ws_endpoint import WebSocketHandlerfrom marimo._server.codes import WebSocketCodesfrom marimo._server.session_manager import SessionManagerfrom marimo._session.model import ConnectionState, SessionMode@@ -51,6 +57,63 @@ def test_ws(client: TestClient) -> None:assert_kernel_ready_response(data)[email protected]("failure", ["disconnect", "cancel"])+async def test_failed_startup_progress_delivery_detaches_session(+ failure: str,+) -> None:+ websocket = MagicMock()+ websocket.accept = AsyncMock()+ websocket.close = AsyncMock()+ sending = asyncio.Event()++ async def send(_text: str) -> None:+ sending.set()+ await asyncio.sleep(0)+ if failure == "disconnect":+ raise WebSocketDisconnect(1006)+ await asyncio.Event().wait()++ websocket.send_text = send+ manager = MagicMock()+ session = manager.get_session.return_value+ session.ttl_seconds = 120+ session.disconnect_consumer.side_effect = lambda consumer: (+ consumer.on_detach()+ )+ handler = WebSocketHandler(+ websocket=websocket,+ manager=manager,+ params=ConnectionParams(+ session_id=SessionId("s1"),+ file_key="test.py",+ kiosk=False,+ auto_instantiate=False,+ rtc_enabled=False,+ ),+ mode=SessionMode.RUN,+ )++ async def connect(_connection: Any) -> tuple[Any, ConnectionType]:+ handler.on_attach(session, MagicMock())+ handler.status = ConnectionState.OPEN+ handler.notify(+ serialize_kernel_message(+ StartupProgressNotification(phase="starting-kernel")+ )+ )+ return session, ConnectionType.NEW++ with patch.object(handler, "_connect_session", side_effect=connect):+ task = asyncio.create_task(handler.start())+ await asyncio.wait_for(sending.wait(), timeout=5)+ if failure == "cancel":+ task.cancel()+ await asyncio.wait_for(task, timeout=5)++ session.disconnect_consumer.assert_called_once_with(handler)+ assert handler.connection_state() == ConnectionState.CLOSED++def test_without_session(client: TestClient) -> None:with pytest.raises(WebSocketDisconnect) as exc_info:with client.websocket_connect("/ws?access_token=fake-token"):@@ -577,68 +640,6 @@ async def test_ttl_close_does_not_kill_session_owned_by_new_consumer(ws_a.__exit__(None, None, None)-def test_ttl_close_skips_when_session_has_active_consumer() -> None:- """Unit test: _close() must not kill session when another consumer has taken over.-- Patches call_later to fire the TTL callback immediately after setup,- simulating the bug scenario where Consumer A's timer fires while- Consumer B owns the session.- """- from marimo._server.api.endpoints.ws_endpoint import WebSocketHandler-- captured_callback: list[tuple[float, Callable[[], None]]] = []-- def capture_call_later(- delay: float, callback: Callable[[], None]- ) -> MagicMock:- captured_callback.append((delay, callback))- return MagicMock()-- # Session with active consumer (Consumer B has taken over)- session_with_consumer = MagicMock()- session_with_consumer.connection_state.return_value = ConnectionState.OPEN- session_with_consumer.ttl_seconds = 0.1-- manager = MagicMock(spec=SessionManager)- manager.ttl_seconds = 120- manager.get_session.return_value = session_with_consumer- manager.close_session = MagicMock()-- params = ConnectionParams(- session_id="123",- file_key="test.py",- kiosk=False,- auto_instantiate=False,- rtc_enabled=False,- )-- handler = WebSocketHandler(- websocket=MagicMock(),- manager=manager,- params=params,- mode=SessionMode.RUN,- )- handler.status = ConnectionState.CLOSED # Consumer A disconnected-- cleanup_fn = MagicMock()-- with patch(- "marimo._server.api.endpoints.ws_endpoint.asyncio.get_running_loop"- ) as mock_loop:- mock_loop.return_value.call_later = capture_call_later- handler._on_disconnect(Exception("disconnect"), cleanup_fn)-- assert len(captured_callback) == 1- _, ttl_callback = captured_callback[0]-- # Fire the TTL callback (simulates timer firing)- ttl_callback()-- # With the fix: session has active consumer, so close_session must NOT be called- manager.close_session.assert_not_called()- cleanup_fn.assert_not_called()--@pytest.mark.parametrize(("mode", "manager_ttl"),[@@ -685,67 +686,6 @@ async def test_session_ttl_expiration(task.join()-def test_run_mode_ttl_close_with_manager_ttl_none() -> None:- """Unit test: RUN mode must schedule TTL cleanup even when- manager.ttl_seconds is None (the default for create_asgi_app).-- This was a regression from #7863 where the condition only checked- manager.ttl_seconds, causing ASGI sessions to never be cleaned up.- """- from marimo._server.api.endpoints.ws_endpoint import WebSocketHandler-- captured_callback: list[tuple[float, Callable[[], None]]] = []-- def capture_call_later(- delay: float, callback: Callable[[], None]- ) -> MagicMock:- captured_callback.append((delay, callback))- return MagicMock()-- # Session exists but no active consumer (disconnected)- session = MagicMock()- session.connection_state.return_value = ConnectionState.ORPHANED- session.ttl_seconds = 120-- manager = MagicMock(spec=SessionManager)- manager.ttl_seconds = None # ASGI default- manager.get_session.return_value = session-- params = ConnectionParams(- session_id="123",- file_key="test.py",- kiosk=False,- auto_instantiate=False,- rtc_enabled=False,- )-- handler = WebSocketHandler(- websocket=MagicMock(),- manager=manager,- params=params,- mode=SessionMode.RUN,- )- handler.status = ConnectionState.CLOSED-- cleanup_fn = MagicMock()-- with patch(- "marimo._server.api.endpoints.ws_endpoint.asyncio.get_running_loop"- ) as mock_loop:- mock_loop.return_value.call_later = capture_call_later- handler._on_disconnect(Exception("disconnect"), cleanup_fn)-- # Must schedule TTL cleanup even though manager.ttl_seconds is None- assert len(captured_callback) == 1- delay, ttl_callback = captured_callback[0]- assert delay == 120 # session.ttl_seconds-- # Fire the callback — session has no active consumer, so it should close- ttl_callback()- manager.close_session.assert_called_once_with("123")- cleanup_fn.assert_called_once()--async def test_edit_mode_without_session_ttl_no_delayed_cleanup(client: TestClient,) -> None:@@ -870,3 +810,67 @@ async def test_websocket_message_queue_delivery(client: TestClient) -> None:messages = flush_messages(websocket, at_least=1)assert len(messages) >= 1+++def test_disconnect_cancels_pending_startup(+ client: TestClient, monkeypatch: pytest.MonkeyPatch+) -> None:+ import asyncio+ import threading++ from marimo._session.session import SessionImpl++ started = threading.Event()+ cleaned_up = threading.Event()++ async def create(**_kwargs: object) -> None:+ started.set()+ try:+ await asyncio.Event().wait()+ finally:+ cleaned_up.set()++ monkeypatch.setattr(SessionImpl, "create", create)+ with client.websocket_connect(WS_URL) as websocket:+ assert started.wait(timeout=5)+ websocket.close()+ # Stay in the client context: its teardown cancels the server task,+ # which would hide a failure to notice the actual disconnect.+ assert cleaned_up.wait(timeout=5)+ assert not get_session_manager(client).sessions+++def test_sandbox_progress_before_preparation_failure(+ client: TestClient, monkeypatch: pytest.MonkeyPatch+) -> None:+ from marimo._environments.errors import EnvironmentManagerError+ from marimo._environments.sandbox import NotebookSandbox++ release = asyncio.Event()++ async def prepare(*_args: object, **_kwargs: object) -> None:+ try:+ await asyncio.wait_for(release.wait(), timeout=5)+ except asyncio.TimeoutError:+ pass+ raise EnvironmentManagerError("Could not resolve dependencies")++ monkeypatch.setattr(NotebookSandbox, "launch_async", prepare)+ get_session_manager(client).sandbox = True++ with client.websocket_connect(WS_URL) as websocket:+ assert websocket.receive_json() == {+ "op": "startup-progress",+ "data": {+ "op": "startup-progress",+ "phase": "preparing-environment",+ },+ }+ assert not get_session_manager(client).sessions+ websocket.portal.call(release.set)+ error = websocket.receive_json()+ assert error["op"] == "kernel-startup-error"+ assert "Could not resolve dependencies" in error["data"]["error"]+ with pytest.raises(WebSocketDisconnect) as closed:+ websocket.receive_json()+ assert closed.value.reason == "MARIMO_KERNEL_STARTUP_ERROR"diff --git a/tests/_server/api/test_middleware.py b/tests/_server/api/test_middleware.pyindex 71bbe983e4..addd7bfc47 100644--- a/tests/_server/api/test_middleware.py+++ b/tests/_server/api/test_middleware.py@@ -1,6 +1,7 @@# Copyright 2026 Marimo. All rights reserved.from __future__ import annotations+import asyncioimport ioimport jsonimport socket@@ -241,7 +242,7 @@ def read_app() -> Starlette:yield apptry:- join_kernel_thread_tasks(session_manager)+ asyncio.run(join_kernel_thread_tasks(session_manager))finally:sys.modules["__main__"] = main@@ -279,7 +280,7 @@ def no_auth_read_app() -> Starlette:yield apptry:- join_kernel_thread_tasks(session_manager)+ asyncio.run(join_kernel_thread_tasks(session_manager))finally:sys.modules["__main__"] = maindiff --git a/tests/_server/conftest.py b/tests/_server/conftest.pyindex 1307636a0a..ae7c186a3e 100644--- a/tests/_server/conftest.py+++ b/tests/_server/conftest.py@@ -1,6 +1,7 @@# Copyright 2026 Marimo. All rights reserved.from __future__ import annotations+import asyncioimport sysimport threadingfrom pathlib import Path@@ -41,20 +42,20 @@ def get_kernel_tasks(return kernel_tasks-def join_kernel_thread_tasks(session_manager: SessionManager) -> None:+async def join_kernel_thread_tasks(session_manager: SessionManager) -> None:# Kernels started in run mode run in their own threads; if these kernels# execute code, they may patch and restore their own main modules.# To ensure that this fixture correctly restores the original saved# main module, we wait for threads to finish before restoring the module.kernel_tasks = get_kernel_tasks(session_manager)- session_manager.shutdown()+ await session_manager.shutdown()for task in kernel_tasks:# At least some tests are flaky with processes (edit tasks)# not joining for a long time; orphaned edit tasks# won't affect other tests, but they are somewhat concerning# ...if isinstance(task, threading.Thread):- task.join()+ await asyncio.to_thread(task.join)@pytest.fixture(scope="session", autouse=True)@@ -117,7 +118,7 @@ def client(user_config_manager: UserConfigManager) -> Iterator[TestClient]:yield clienttry:- join_kernel_thread_tasks(client.app.state.session_manager)+ asyncio.run(join_kernel_thread_tasks(client.app.state.session_manager))finally:sys.modules["__main__"] = maindiff --git a/tests/_server/test_session_manager.py b/tests/_server/test_session_manager.pyindex ce7f34b0ff..f0ad254e9c 100644--- a/tests/_server/test_session_manager.py+++ b/tests/_server/test_session_manager.py@@ -1,5 +1,6 @@from __future__ import annotations+import asyncioimport sysfrom textwrap import dedentfrom typing import TYPE_CHECKING@@ -96,7 +97,7 @@ async def test_start_lsp_server(session_manager: SessionManager) -> None:async def test_create_session_new(session_manager: SessionManager, mock_session_consumer: SessionConsumer) -> None:- session = session_manager.create_session(+ session = await session_manager.create_session(session_id,mock_session_consumer,query_params={},@@ -114,7 +115,7 @@ async def test_create_session_absolute_url(mock_session_consumer: SessionConsumer,temp_marimo_file: str,) -> None:- session = session_manager.create_session(+ session = await session_manager.create_session(session_id,mock_session_consumer,query_params={},@@ -225,13 +226,13 @@ def test_close_all_sessions(assert mock_session.close.call_count == 2-def test_shutdown(+async def test_shutdown(session_manager: SessionManager, mock_session: Session) -> None:add_session(session_manager, SessionId("session1"), mock_session)add_session(session_manager, SessionId("session2"), mock_session)- session_manager.shutdown()+ await session_manager.shutdown()session_manager.lsp_server.stop.assert_called_once()assert len(session_manager.sessions) == 0assert mock_session.close.call_count == 2@@ -254,7 +255,7 @@ async def test_create_session_with_script_config_overrides())- session = session_manager.create_session(+ session = await session_manager.create_session(session_id,mock_session_consumer,query_params={},@@ -461,7 +462,7 @@ async def test_recents_touch_called_on_session_create(session_manager.recents.touch = mock_touch # type: ignore# Create a session- session = session_manager.create_session(+ session = await session_manager.create_session(SessionId("recents_test_session"),mock_session_consumer,query_params={},@@ -479,3 +480,165 @@ async def test_recents_touch_called_on_session_create(assert str(tmp_file) in touched_files[0]session.close()+++async def test_concurrent_startup_survives_disconnected_waiter(+ session_manager: SessionManager,+ mock_session: Session,+ mock_session_consumer: SessionConsumer,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ from marimo._session.session import SessionImpl++ entered = asyncio.Event()+ release = asyncio.Event()+ launches = 0+ mock_session.app_file_manager = AppFileManager(filename=None)++ async def create(**_kwargs: object) -> Session:+ nonlocal launches+ launches += 1+ entered.set()+ await release.wait()+ return mock_session++ monkeypatch.setattr(SessionImpl, "create", create)++ async def connect() -> Session:+ return await session_manager.create_session(+ session_id, mock_session_consumer, {}, NEW_FILE, False+ )++ first = asyncio.create_task(connect())+ try:+ await asyncio.wait_for(entered.wait(), 5)+ assert not session_manager.sessions+ second_entered = asyncio.Event()++ async def reconnect() -> Session:+ second_entered.set()+ return await connect()++ second = asyncio.create_task(reconnect())+ await asyncio.wait_for(second_entered.wait(), 5)+ first.cancel()+ with pytest.raises(asyncio.CancelledError):+ await first+ release.set()+ assert await asyncio.wait_for(second, 5) is mock_session+ assert launches == 1+ finally:+ await session_manager.shutdown()+++async def test_shutdown_waits_for_pending_startup_cleanup(+ session_manager: SessionManager,+ mock_session_consumer: SessionConsumer,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ from marimo._session.managers.ipc import KernelStartupError+ from marimo._session.session import SessionImpl++ entered = asyncio.Event()+ cleaning_up = asyncio.Event()+ release = asyncio.Event()++ async def create(**_kwargs: object) -> Session:+ entered.set()+ try:+ await asyncio.Event().wait()+ finally:+ cleaning_up.set()+ await release.wait()+ raise AssertionError("unreachable")++ monkeypatch.setattr(SessionImpl, "create", create)+ startup = asyncio.create_task(+ session_manager.create_session(+ session_id, mock_session_consumer, {}, NEW_FILE, False+ )+ )+ await asyncio.wait_for(entered.wait(), 5)+ shutdown = asyncio.create_task(session_manager.shutdown())+ try:+ await asyncio.wait_for(cleaning_up.wait(), 5)+ assert not shutdown.done()+ assert not session_manager.sessions+ with pytest.raises(KernelStartupError, match="shut down"):+ await session_manager.create_session(+ session_id, mock_session_consumer, {}, NEW_FILE, False+ )+ finally:+ release.set()+ await asyncio.wait_for(shutdown, 5)+ with pytest.raises(asyncio.CancelledError):+ await startup+ assert not session_manager.sessions+++async def test_connections_share_starting_notebook(+ session_manager: SessionManager,+ mock_session: Session,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ from starlette.requests import HTTPConnection++ from marimo._server.api.endpoints.ws.ws_connection_validator import (+ ConnectionParams,+ )+ from marimo._server.api.endpoints.ws.ws_session_connector import (+ ConnectionType,+ SessionConnector,+ )+ from marimo._session.session import SessionImpl++ entered = asyncio.Event()+ release = asyncio.Event()+ mock_session.initialization_id = NEW_FILE+ mock_session.room = MagicMock()+ mock_session.room.get_consumer.return_value = None+ mock_session.app_file_manager = AppFileManager(filename=None)+ launches = 0++ async def create(**_kwargs: object) -> Session:+ nonlocal launches+ launches += 1+ entered.set()+ await release.wait()+ return mock_session++ monkeypatch.setattr(SessionImpl, "create", create)++ def connector(sid: str) -> SessionConnector:+ return SessionConnector(+ manager=session_manager,+ handler=MagicMock(),+ params=ConnectionParams(+ session_id=SessionId(sid),+ file_key=NEW_FILE,+ kiosk=False,+ auto_instantiate=False,+ rtc_enabled=True,+ ),+ connection=HTTPConnection({"type": "http", "query_string": b""}),+ )++ first = asyncio.create_task(connector("first").connect())+ try:+ await asyncio.wait_for(entered.wait(), 5)+ second = asyncio.create_task(connector("second").connect())+ # Scheduling the second connection before releasing preparation+ # exercises its decision against an initially empty repository.+ release.set()+ assert await asyncio.wait_for(first, 5) == (+ mock_session,+ ConnectionType.NEW,+ )+ assert await asyncio.wait_for(second, 5) == (+ mock_session,+ ConnectionType.RTC_EXISTING,+ )+ assert launches == 1+ finally:+ release.set()+ await session_manager.shutdown()diff --git a/tests/_server/test_sessions.py b/tests/_server/test_sessions.pyindex d58c568b0b..9e0bed695d 100644--- a/tests/_server/test_sessions.py+++ b/tests/_server/test_sessions.py@@ -15,7 +15,7 @@ from pathlib import Pathfrom tempfile import NamedTemporaryFilefrom textwrap import dedentfrom typing import Any-from unittest.mock import MagicMock, patch+from unittest.mock import MagicMockimport pytest@@ -24,7 +24,10 @@ from marimo._ast.app_config import _AppConfigfrom marimo._config.manager import (get_default_config_manager,)+from marimo._messaging.errors import MarimoInterruptionErrorfrom marimo._messaging.notification import (+ CellNotification,+ CompletedRunNotification,NotebookDocumentTransactionNotification,NotificationMessage,)@@ -59,40 +62,6 @@ from marimo._utils.marimo_path import MarimoPathinitialize_asyncio()[email protected]("inherited_mode", ["single", None])-def test_single_sandbox_edit_uses_notebook_bound_kernel(- inherited_mode: str | None, monkeypatch: pytest.MonkeyPatch-) -> None:- from marimo._cli.sandbox import SandboxMode- from marimo._config.settings import GLOBAL_SETTINGS- from marimo._session.managers.ipc import IPCKernelManagerImpl-- monkeypatch.setattr(GLOBAL_SETTINGS, "SANDBOX_MODE", inherited_mode)- # Inspect the factory without starting a process or attaching consumers.- with patch.object(- SessionImpl, "__init__", return_value=None- ) as initialize:- SessionImpl.create(- initialization_id="sandbox-restart",- session_consumer=MagicMock(),- mode=SessionMode.EDIT,- app_metadata=app_metadata,- app_file_manager=AppFileManager.from_app(InternalApp(App())),- config_manager=get_default_config_manager(current_path=None),- virtual_file_storage="shared_memory",- redirect_console_to_browser=False,- ttl_seconds=None,- auto_instantiate=False,- sandbox_mode=None if inherited_mode else SandboxMode.SINGLE,- )- manager = initialize.call_args.kwargs["kernel_manager"]- try:- assert isinstance(manager, IPCKernelManagerImpl)- assert manager.sandbox_mode is SandboxMode.SINGLE- finally:- manager.queue_manager.close_queues()--app_metadata = AppMetadata(query_params={"some_param": "some_value"},filename="test.py",@@ -140,7 +109,7 @@ def test_queue_manager() -> None:assert isinstance(queue_manager_thread.input_queue, queue.Queue)-def test_kernel_manager_run_mode() -> None:+async def test_kernel_manager_run_mode() -> None:# Mock objects and data for testingqueue_manager = QueueManagerImpl(use_multiprocessing=False)mode = SessionMode.RUN@@ -156,7 +125,7 @@ def test_kernel_manager_run_mode() -> None:redirect_console_to_browser=False,)- kernel_manager.start_kernel()+ await kernel_manager.start_kernel()# Assert startupassert kernel_manager.kernel_task is not None@@ -173,7 +142,7 @@ def test_kernel_manager_run_mode() -> None:assert queue_manager.control_queue.empty()-def test_kernel_manager_edit_mode() -> None:+async def test_kernel_manager_edit_mode() -> None:# Mock objects and data for testingqueue_manager = QueueManagerImpl(use_multiprocessing=True)mode = SessionMode.EDIT@@ -189,7 +158,7 @@ def test_kernel_manager_edit_mode() -> None:redirect_console_to_browser=False,)- kernel_manager.start_kernel()+ await kernel_manager.start_kernel()# Assert startupassert kernel_manager.kernel_task is not None@@ -206,113 +175,74 @@ def test_kernel_manager_edit_mode() -> None:queue_manager.control_queue.join_thread() # type: ignore-def test_kernel_manager_interrupt(tmp_path: Path) -> None:+async def test_kernel_manager_interrupt() -> None:queue_manager = QueueManagerImpl(use_multiprocessing=True)- mode = SessionMode.EDIT-kernel_manager = KernelManagerImpl(queue_manager=queue_manager,- mode=mode,+ mode=SessionMode.EDIT,configs={},app_metadata=app_metadata,config_manager=get_default_config_manager(current_path=None),virtual_file_storage="shared_memory",redirect_console_to_browser=False,)+ await kernel_manager.start_kernel()- # Assert startup- kernel_manager.start_kernel()- assert kernel_manager.kernel_task is not None- assert kernel_manager._read_conn is not None- assert kernel_manager.is_alive()- if sys.platform == "win32":- import random- import string-- # Having trouble persisting the write to a temp file on Windows- file = Path(- "".join(random.choice(string.ascii_uppercase) for _ in range(10))- + ".txt"- )- else:- file = tmp_path / "output.txt"-- Path(file).write_text("-1")+ def interrupt_running_cell() -> bool:+ interrupted = False+ while True:+ message = deserialize_kernel_message(+ kernel_manager.kernel_connection.recv()+ )+ if isinstance(message, CompletedRunNotification):+ return interrupted+ if (+ not isinstance(message, CellNotification)+ or message.output is None+ ):+ continue+ output = message.output.data+ if isinstance(output, str) and "ready-to-interrupt" in output:+ kernel_manager.interrupt_kernel()+ elif isinstance(output, list):+ interrupted |= any(+ isinstance(error, MarimoInterruptionError)+ for error in output+ )- queue_manager.control_queue.put(- CreateNotebookCommand(- execution_requests=(- ExecuteCellCommand(- cell_id="1",- code=inspect.cleandoc(- f"""- import time- with open("{file}", 'w') as f:- f.write('0')- time.sleep(2)- with open("{file}", 'w') as f:- f.write('1')- """+ try:+ queue_manager.put_control_request(+ CreateNotebookCommand(+ execution_requests=(+ ExecuteCellCommand(+ cell_id="1",+ code=inspect.cleandoc("""+ import marimo as mo+ mo.output.append("ready-to-interrupt")+ while True:+ pass+ """),),),- ),- cell_ids=("1",),- set_ui_element_value_request=UpdateUIElementCommand(- object_ids=[], values=[]- ),- auto_run=True,+ cell_ids=("1",),+ set_ui_element_value_request=UpdateUIElementCommand(+ object_ids=[], values=[]+ ),+ auto_run=True,+ )+ )+ assert await asyncio.wait_for(+ asyncio.to_thread(interrupt_running_cell), timeout=5)- )-- timeout = 5- # Wait for the file to be written to 0- start_time = time.time()- while time.time() < start_time + timeout / 2:- time.sleep(0.1)- if file.read_text() == "0":- break- kernel_manager.interrupt_kernel()-- try:- assert file.read_text() == "0"- # if kernel failed to interrupt, f will read as "1"- time.sleep(1.5)- assert file.read_text() == "0"finally:- if sys.platform == "win32":- os.remove(file)-- # Wait for queues to be empty with timeout- # This makes the test more resilient to timing issues in CI- start_time = time.time()- timeout = 5 # 5-second timeout for queues to be empty-- # Give some time for queues to be processed first- time.sleep(0.5)-- while time.time() - start_time < timeout:- if (- queue_manager.input_queue.empty()- and queue_manager.control_queue.empty()- ):- break- time.sleep(0.2) # slightly longer interval-- # Now check if queues are empty- assert queue_manager.input_queue.empty()- assert queue_manager.control_queue.empty()-- # Assert shutdownkernel_manager.close_kernel()- kernel_manager.kernel_task.join(timeout=5)- assert not kernel_manager.is_alive()@pytest.mark.skipif(sys.platform == "win32",reason="interrupts don't reach subprocesses on Windows",)-def test_kernel_manager_interrupt_reaches_subprocesses(+async def test_kernel_manager_interrupt_reaches_subprocesses(tmp_path: Path,) -> None:queue_manager = QueueManagerImpl(use_multiprocessing=True)@@ -326,7 +256,7 @@ def test_kernel_manager_interrupt_reaches_subprocesses(redirect_console_to_browser=False,)- kernel_manager.start_kernel()+ await kernel_manager.start_kernel()assert kernel_manager.kernel_task is not Noneassert kernel_manager.is_alive()@@ -371,7 +301,7 @@ def test_kernel_manager_interrupt_reaches_subprocesses(int(pid) for pid in pid_file.read_text().split())break- time.sleep(0.1)+ await asyncio.sleep(0.1)def terminated(pid: int) -> bool:# An interrupted child of the kernel may linger as a zombie until@@ -389,8 +319,8 @@ def test_kernel_manager_interrupt_reaches_subprocesses(kernel_manager.interrupt_kernel()deadline = time.time() + 10- while time.time() < deadline and not terminated(child_pid):- time.sleep(0.1)+ while time.time() < deadline and not terminated(child_pid): # noqa: ASYNC110+ await asyncio.sleep(0.1)# The interrupt reaches subprocesses in the kernel's process groupassert terminated(child_pid)# ... but spares subprocesses that detached into their own session@@ -424,6 +354,8 @@ async def test_session() -> None:redirect_console_to_browser=False,)+ await kernel_manager.start_kernel()+# Instantiate a Sessionsession = SessionImpl(initialization_id=session_id,@@ -455,7 +387,7 @@ async def test_session() -> None:assert session.connection_state() == ConnectionState.CLOSED-def test_session_disconnect_reconnect() -> None:+async def test_session_disconnect_reconnect() -> None:session_consumer: Any = MagicMock()session_consumer.connection_state.return_value = ConnectionState.OPENqueue_manager = QueueManagerImpl(use_multiprocessing=False)@@ -469,6 +401,8 @@ def test_session_disconnect_reconnect() -> None:redirect_console_to_browser=False,)+ await kernel_manager.start_kernel()+# Instantiate a Sessionsession = SessionImpl(initialization_id=session_id,@@ -512,7 +446,7 @@ def test_session_disconnect_reconnect() -> None:assert session.connection_state() == ConnectionState.CLOSED-def test_session_with_kiosk_consumers() -> None:+async def test_session_with_kiosk_consumers() -> None:session_consumer: Any = MagicMock()session_consumer.connection_state.return_value = ConnectionState.OPENqueue_manager = QueueManagerImpl(use_multiprocessing=False)@@ -526,6 +460,8 @@ def test_session_with_kiosk_consumers() -> None:redirect_console_to_browser=False,)+ await kernel_manager.start_kernel()+# Instantiate a Sessionsession = SessionImpl(initialization_id=session_id,@@ -620,7 +556,7 @@ def __():session_consumer = MockSessionConsumer()# Create a session- session_manager.create_session(+ await session_manager.create_session(session_id=session_id,session_consumer=session_consumer,query_params={},@@ -657,7 +593,7 @@ def __():# Create another session for the same filesession_consumer2 = MockSessionConsumer()- session_manager.create_session(+ await session_manager.create_session(session_id=SessionId("test2"),session_consumer=session_consumer2,query_params={},@@ -728,10 +664,10 @@ def __():assert len(update_ops2) >= 1finally:# Cleanup- session_manager.shutdown()+ await session_manager.shutdown()-def test_watch_mode_does_not_override_config(tmp_path: Path) -> None:+async def test_watch_mode_does_not_override_config(tmp_path: Path) -> None:"""Test that watch mode does not override config settings."""# Create a temporary filetmp_file = tmp_path / "test_watch_mode_config_override.py"@@ -780,8 +716,8 @@ def test_watch_mode_does_not_override_config(tmp_path: Path) -> None:finally:# Cleanup- session_manager.shutdown()- session_manager_no_watch.shutdown()+ await session_manager.shutdown()+ await session_manager_no_watch.shutdown()@pytest.mark.flaky(reruns=3)@@ -834,7 +770,7 @@ async def test_watch_mode_with_watcher_on_save_autorun(tmp_path: Path) -> None:session_consumer = MockSessionConsumer()# Create a session- session = session_manager.create_session(+ session = await session_manager.create_session(session_id=session_id,session_consumer=session_consumer,query_params={},@@ -891,7 +827,7 @@ async def test_watch_mode_with_watcher_on_save_autorun(tmp_path: Path) -> None:finally:# Cleanupif session_manager:- session_manager.shutdown()+ await session_manager.shutdown()async def test_watch_mode_with_watcher_on_save_lazy(tmp_path: Path) -> None:@@ -943,7 +879,7 @@ async def test_watch_mode_with_watcher_on_save_lazy(tmp_path: Path) -> None:session_consumer = MockSessionConsumer()# Create a session- session = session_manager.create_session(+ session = await session_manager.create_session(session_id=session_id,session_consumer=session_consumer,query_params={},@@ -989,7 +925,7 @@ async def test_watch_mode_with_watcher_on_save_lazy(tmp_path: Path) -> None:finally:# Cleanupif session_manager:- session_manager.shutdown()+ await session_manager.shutdown()async def test_session_manager_file_rename() -> None:@@ -1039,7 +975,7 @@ def __():)# Create a session- session_manager.create_session(+ await session_manager.create_session(session_id=session_id,session_consumer=session_consumer,query_params={},@@ -1104,14 +1040,14 @@ def __():finally:# Cleanup- session_manager.shutdown()+ await session_manager.shutdown()if new_path.exists():os.remove(new_path)if tmp_path1.exists(): # noqa: ASYNC240os.remove(tmp_path1)-def test_session_with_script_config_overrides(+async def test_session_with_script_config_overrides(tmp_path: Path,) -> None:session_consumer = MagicMock()@@ -1134,7 +1070,7 @@ def test_session_with_script_config_overrides(app_file_manager = AppFileManager(filename=str(tmp_file))# Create session with the file that has script config- session = SessionImpl.create(+ session = await SessionImpl.create(initialization_id="test_id",session_consumer=session_consumer,mode=SessionMode.RUN,@@ -1172,7 +1108,7 @@ async def test_caching_extension_respects_mode_and_config() -> None:session_consumer = MagicMock()session_consumer.connection_state.return_value = ConnectionState.OPEN- def create_session(+ async def create_session(mode: SessionMode,auto_instantiate: bool,*,@@ -1187,7 +1123,7 @@ async def test_caching_extension_respects_mode_and_config() -> None:}})- return SessionImpl.create(+ return await SessionImpl.create(initialization_id="test_session",session_consumer=session_consumer,mode=mode,@@ -1212,7 +1148,7 @@ async def test_caching_extension_respects_mode_and_config() -> None:return extension[0]# Test 1: EDIT mode with auto_instantiate=False -> caching enabled/read-write- session_edit = create_session(SessionMode.EDIT, False)+ session_edit = await create_session(SessionMode.EDIT, False)# Find the CachingExtensioncaching_extension_edit = find_caching_extension(session_edit)@@ -1220,7 +1156,7 @@ async def test_caching_extension_respects_mode_and_config() -> None:assert caching_extension_edit.mode is CacheMode.READ_WRITE# Test 2: EDIT mode with auto_instantiate=True -> caching disabled- session_edit_disabled = create_session(SessionMode.EDIT, True)+ session_edit_disabled = await create_session(SessionMode.EDIT, True)caching_extension_edit_disabled = find_caching_extension(session_edit_disabled)@@ -1228,7 +1164,7 @@ async def test_caching_extension_respects_mode_and_config() -> None:assert caching_extension_edit_disabled.mode is CacheMode.READ_WRITE# Test 3: RUN mode with config disabled -> caching disabled/read-only- session_run_disabled = create_session(+ session_run_disabled = await create_session(SessionMode.RUN, True, serve_cached_sessions_in_apps=False)@@ -1240,7 +1176,7 @@ async def test_caching_extension_respects_mode_and_config() -> None:assert caching_extension_run_disabled.mode is CacheMode.READ# Test 4: RUN mode with config enabled -> caching enabled/read-only- session_run_enabled = create_session(+ session_run_enabled = await create_session(SessionMode.RUN, True, serve_cached_sessions_in_apps=True)caching_extension_run_enabled = find_caching_extension(session_run_enabled)diff --git a/tests/_session/app_host/test_app_host.py b/tests/_session/app_host/test_app_host.pyindex cb49897076..138100be22 100644--- a/tests/_session/app_host/test_app_host.py+++ b/tests/_session/app_host/test_app_host.py@@ -333,7 +333,7 @@ class TestAppHostQueueManager:@pytest.mark.requires("zmq")class TestAppHostMultipleClients:- def test_create_session_uses_per_client_session_id(self) -> None:+ async def test_create_session_uses_per_client_session_id(self) -> None:"""SessionImpl.create() must pass the per-client session_id — notthe shared initialization_id (file_key) — to the AppHost managers.@@ -361,7 +361,7 @@ class TestAppHostMultipleClients:"AppHostKernelManager.start_kernel"):for sid in ("session-1", "session-2"):- SessionImpl.create(+ await SessionImpl.create(initialization_id=file_key,session_consumer=Mock(),mode=SessionMode.RUN,diff --git a/tests/_session/managers/test_app_host_kernel_manager.py b/tests/_session/managers/test_app_host_kernel_manager.pyindex d2cdb7d276..ad78946c86 100644--- a/tests/_session/managers/test_app_host_kernel_manager.py+++ b/tests/_session/managers/test_app_host_kernel_manager.py@@ -98,32 +98,7 @@ class TestAppHostLike:@pytest.mark.requires("zmq")class TestAppHostKernelManagerStartAndClose:- def test_start_kernel_sets_kernel_task(self) -> None:- app_host = Mock()- app_host.create_kernel.return_value = KernelCreatedResponse(- session_id="s1", success=True- )-- config_manager = Mock()- config_manager.get_config.return_value = {}-- mgr = AppHostKernelManager(- app_host=app_host,- session_id="s1",- queue_manager=Mock(),- mode=SessionMode.RUN,- configs={},- app_metadata=Mock(),- config_manager=config_manager,- redirect_console_to_browser=True,- )-- mgr.start_kernel()-- app_host.create_kernel.assert_called_once()- assert isinstance(mgr.kernel_task, _AppHostLike)-- def test_start_kernel_failure_raises(self) -> None:+ async def test_start_kernel_failure_raises(self) -> None:app_host = Mock()app_host.create_kernel.return_value = KernelCreatedResponse(session_id="s1", success=False, error="boom"@@ -144,7 +119,7 @@ class TestAppHostKernelManagerStartAndClose:)with pytest.raises(RuntimeError, match="boom"):- mgr.start_kernel()+ await mgr.start_kernel()assert mgr.kernel_task is Nonediff --git a/tests/_session/managers/test_ipc.py b/tests/_session/managers/test_ipc.pyindex 4cc43cbd75..75fb7ec678 100644--- a/tests/_session/managers/test_ipc.py+++ b/tests/_session/managers/test_ipc.py@@ -1,10 +1,13 @@# Copyright 2026 Marimo. All rights reserved.from __future__ import annotations+import asyncioimport os+import subprocess+import sysimport timefrom pathlib import Path-from unittest.mock import MagicMock, patch+from unittest.mock import AsyncMock, MagicMockimport pytest@@ -303,49 +306,6 @@ def _make_manager(filename: str | None = None) -> object:)[email protected]("saved", [False, True])-def test_single_launch_preserves_manifest_binding_and_precedence(- saved: bool, tmp_path: Path, monkeypatch: pytest.MonkeyPatch-) -> None:- from marimo._cli.sandbox import SandboxMode- from marimo._environments.sandbox import MANIFEST_SOURCE, NotebookSandbox- from marimo._session.managers import ipc-- temporary_manifest = tmp_path / "temporary.py"- temporary_manifest.write_text(- '# /// script\n# dependencies = ["six"]\n# ///\n'- )- saved_manifest = tmp_path / "saved.py"- saved_manifest.write_text(temporary_manifest.read_text())- monkeypatch.setenv(MANIFEST_SOURCE, str(temporary_manifest))- manager = _make_manager(str(saved_manifest) if saved else None)- manager.sandbox_mode = SandboxMode.SINGLE- configured_venv = MagicMock(- side_effect=AssertionError("SINGLE must retain its sandbox precedence")- )- monkeypatch.setattr(ipc, "get_configured_venv_python", configured_venv)-- # Stop at the launch boundary: the selected source must be the original- # unnamed manifest or the newly saved path, never a fresh empty manifest.- class LaunchObserved(Exception):- pass-- def observe(- sandbox: NotebookSandbox, *_args: object, **_kwargs: object- ) -> None:- assert sandbox.source == str(- saved_manifest if saved else temporary_manifest- )- assert "six" in Path(sandbox.source).read_text()- raise LaunchObserved-- monkeypatch.setattr(NotebookSandbox, "launch", observe)- with pytest.raises(LaunchObserved):- manager.start_kernel()- configured_venv.assert_not_called()- assert temporary_manifest.exists()--class TestProfilePath:def test_none_without_profile_dir(self, monkeypatch: pytest.MonkeyPatch@@ -415,107 +375,6 @@ class TestCloseKernel:)-class TestFailedStartCleanup:- def test_kills_process_and_closes_sandbox(self) -> None:- from marimo._session.managers import ipc-- manager = _make_manager("nb.py")- manager._process = MagicMock()- manager._process.poll.return_value = None- manager._notebook_sandbox = MagicMock()- sandbox = manager._notebook_sandbox-- with patch.object(ipc, "try_kill_process_and_group") as kill:- manager._cleanup_failed_start()-- kill.assert_called_once()- sandbox.close.assert_called_once()- assert manager.notebook_sandbox is None---class TestAwaitHandshakeLine:- @staticmethod- def _await(manager: object, handshake: object, deadline: float) -> str:- from collections import deque-- return manager._await_handshake_line(- handshake, deadline, deque(), ["python", "-m", "kernel"]- )-- def test_returns_pending_line(self) -> None:- import queue- import subprocess- import sys as _sys-- manager = _make_manager("nb.py")- manager._process = subprocess.Popen(- [_sys.executable, "-c", "import time; time.sleep(30)"]- )- try:- handshake: queue.Queue[str] = queue.Queue()- handshake.put("KERNEL_READY")- line = self._await(- manager, handshake, deadline=time.monotonic() + 5- )- assert line == "KERNEL_READY"- finally:- manager._process.kill()- manager._process.wait()-- def test_child_exit_fails_fast_with_exit_code(self) -> None:- import queue- import subprocess- import sys as _sys-- from marimo._session.managers.ipc import KernelStartupError-- manager = _make_manager("nb.py")- manager._process = subprocess.Popen(- [_sys.executable, "-c", "import sys; sys.exit(3)"]- )- manager._process.wait()- with pytest.raises(KernelStartupError, match="exit code 3"):- self._await(manager, queue.Queue(), deadline=time.monotonic() + 30)-- def test_queued_handshake_takes_precedence_over_child_exit(self) -> None:- import queue- import subprocess- import sys as _sys-- manager = _make_manager("nb.py")- manager._process = subprocess.Popen([_sys.executable, "-c", "pass"])- manager._process.wait()- handshake: queue.Queue[str] = queue.Queue()- handshake.put("KERNEL_READY")- line = self._await(manager, handshake, deadline=time.monotonic() + 5)- assert line == "KERNEL_READY"-- def test_hung_child_times_out_and_is_killed(self) -> None:- import queue- import subprocess- import sys as _sys-- from marimo._session.managers.ipc import KernelStartupError-- manager = _make_manager("nb.py")- manager._process = subprocess.Popen(- [_sys.executable, "-c", "import time; time.sleep(60)"]- )- try:- with pytest.raises(- KernelStartupError, match="did not become ready"- ):- self._await(- manager, queue.Queue(), deadline=time.monotonic() - 1- )- manager._process.wait(timeout=10)- assert manager._process.poll() is not None- finally:- if manager._process.poll() is None:- manager._process.kill()- manager._process.wait()--class TestParseKernelInfo:def test_full_line(self) -> None:from marimo._session.managers.ipc import _parse_kernel_info@@ -566,3 +425,153 @@ def test_launch_kernel_handshake_reports_identity() -> None:pid, exe = _parse_kernel_info(lines[1])assert pid is not Noneassert exe is not None++[email protected]("zmq")+ ("outcome", "configured"),+ [+ ("exit", False),+ ("timeout", False),+ ("cancel", False),+ ("cancel", True),+ ("output", False),+ ],+)+async def test_startup_owns_kernel_process_and_pipes(+ outcome: str,+ configured: bool,+ monkeypatch: pytest.MonkeyPatch,+ tmp_path: Path,+) -> None:+ from marimo._ast.app_config import _AppConfig+ from marimo._config.manager import get_default_config_manager+ from marimo._environments.environment import ProcessPlan+ from marimo._ipc import QueueManager+ from marimo._runtime.commands import AppMetadata+ from marimo._session.managers.ipc import (+ IPCKernelManagerImpl,+ IPCQueueManagerImpl,+ KernelStartupError,+ )+ from marimo._session.model import SessionMode++ started = asyncio.Event()++ async def ready(+ reader: asyncio.StreamReader, writer: asyncio.StreamWriter+ ) -> None:+ await reader.read(1)+ started.set()+ writer.close()+ await writer.wait_closed()++ server = await asyncio.start_server(ready, "127.0.0.1", 0)+ port = server.sockets[0].getsockname()[1]+ code = (+ "import socket, sys, time, signal; sys.stdin.read(); "+ "signal.signal(signal.SIGTERM, signal.SIG_IGN); "+ f"socket.create_connection(('127.0.0.1', {port})).send(b'x'); "+ + ("" if configured else "print('KERNEL_READY', flush=True); ")+ + (+ # The launcher exits, but a descendant still holds its pipes.+ "import subprocess; "+ "subprocess.Popen([sys.executable, '-c', 'import time; time.sleep(60)']); "+ "sys.exit(3)"+ if outcome == "exit"+ else "time.sleep(60)"+ )+ )+ output_ready = tmp_path / "output-ready"+ if outcome == "output":+ child_code = "import sys; sys.stdout.write('x' * 131072)"+ code = (+ "import socket, sys, os, subprocess, time\n"+ "from pathlib import Path\n"+ "sys.stdin.read()\n"+ f"socket.create_connection(('127.0.0.1', {port})).send(b'x')\n"+ "print('KERNEL_READY', flush=True)\n"+ "print(f'KERNEL_INFO {os.getpid()} {sys.executable}', flush=True)\n"+ f"while not Path({str(output_ready)!r}).exists(): time.sleep(0.01)\n"+ # Inherit the kernel's stdout and fill more than the pipe buffer.+ f"result = subprocess.run([sys.executable, '-c', {child_code!r}], stdout=sys.stdout)\n"+ "sys.exit(result.returncode)\n"+ )+ sandbox = MagicMock()+ sandbox.launch_async = AsyncMock(+ return_value=ProcessPlan(+ argv=(sys.executable, "-c", code),+ env=os.environ.copy(),+ start_new_session=True,+ )+ )+ monkeypatch.setattr(+ "marimo._environments.sandbox.NotebookSandbox", lambda *_: sandbox+ )+ if configured:+ monkeypatch.setattr(+ "marimo._session.managers.ipc.get_configured_venv_python",+ lambda *_args, **_kwargs: sys.executable,+ )+ monkeypatch.setattr(+ "marimo._session.managers.ipc.has_marimo_installed",+ AsyncMock(return_value=True),+ )+ popen = subprocess.Popen+ # Windows cleanup also uses Popen for taskkill; only replace the kernel.+ monkeypatch.setattr(+ "marimo._session.managers.ipc.subprocess.Popen",+ lambda cmd, **kwargs: popen(+ [sys.executable, "-c", code]+ if cmd == [sys.executable, "-m", "marimo._ipc.launch_kernel"]+ else cmd,+ **kwargs,+ ),+ )+ monkeypatch.setenv(+ "MARIMO_KERNEL_STARTUP_TIMEOUT", "1" if outcome == "timeout" else "30"+ )+ queues, connection_info = QueueManager.create()+ manager = IPCKernelManagerImpl(+ queue_manager=IPCQueueManagerImpl.from_ipc(queues),+ connection_info=connection_info,+ mode=SessionMode.EDIT,+ configs={},+ app_metadata=AppMetadata(+ query_params={},+ filename=None,+ cli_args={},+ argv=None,+ app_config=_AppConfig(),+ ),+ config_manager=get_default_config_manager(current_path=None),+ )+ startup = asyncio.create_task(manager.start_kernel())+ try:+ await asyncio.wait_for(started.wait(), 5)+ if outcome == "output":+ await asyncio.wait_for(startup, 5)+ output_ready.touch() # noqa: ASYNC240+ assert manager.kernel_task is not None+ await asyncio.to_thread(manager.kernel_task.join, 5)+ assert manager.kernel_task.exitcode == 0+ elif outcome == "cancel":+ startup.cancel()+ with pytest.raises(asyncio.CancelledError):+ await asyncio.wait_for(startup, 5)+ else:+ message = (+ "exit code 3" if outcome == "exit" else "did not become ready"+ )+ with pytest.raises(KernelStartupError, match=message):+ await asyncio.wait_for(startup, 5)+ assert not manager.is_alive()+ if outcome != "output":+ assert manager.notebook_sandbox is None+ finally:+ startup.cancel()+ await asyncio.gather(startup, return_exceptions=True)+ await manager._cleanup_failed_start()+ manager.queue_manager.close_queues()+ server.close()+ await server.wait_closed()diff --git a/tests/_session/notebook/test_app_file_manager.py b/tests/_session/notebook/test_app_file_manager.pyindex d86323603a..a4faa647fd 100644--- a/tests/_session/notebook/test_app_file_manager.py+++ b/tests/_session/notebook/test_app_file_manager.py@@ -2,6 +2,8 @@from __future__ import annotationsimport os+import threading+from concurrent.futures import ThreadPoolExecutor, waitfrom typing import TYPE_CHECKINGimport pytest@@ -88,3 +90,105 @@ def test_new_notebook_returns_unbacked_manager() -> None:def test_new_notebook_advances_document_version() -> None:fm = new_notebook()assert fm.app.cell_manager.document.version > 0++[email protected]("suffix", [".py", ".md"])[email protected]("first_writer", ["manifest", "cells"])+def test_manifest_and_cell_saves_preserve_each_other(+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+ suffix: str,+ first_writer: str,+) -> None:+ from marimo._environments import script_metadata+ from marimo._server.models.models import SaveNotebookRequest+ from marimo._session.notebook.serializer import get_notebook_serializer++ path = tmp_path / f"notebook{suffix}"+ serializer = get_notebook_serializer(path)+ notebook = get_notebook_serializer(tmp_path / "notebook.py").deserialize(+ script_metadata.dumps({"dependencies": []}) + "\n" + _NOTEBOOK_SOURCE+ )+ path.write_text(serializer.serialize(notebook))+ manager = load_notebook(path)+ previous = script_metadata.read_manifest(str(path))+ read = threading.Event()+ release = threading.Event()+ second_started = threading.Event()++ def pause_after_read(value):+ read.set()+ assert release.wait(timeout=5)+ return value++ if first_writer == "manifest":+ wrap_block = script_metadata.wrap_block+ monkeypatch.setattr(+ script_metadata,+ "wrap_block",+ lambda contents: pause_after_read(wrap_block(contents)),+ )+ else:+ serializer_type = type(serializer)+ extract_header = serializer_type.extract_header+ monkeypatch.setattr(+ serializer_type,+ "extract_header",+ lambda self, path: pause_after_read(extract_header(self, path)),+ )++ def save_manifest():+ return script_metadata.write_manifest(+ str(path), 'dependencies = ["requests"]\n', previous=previous+ )++ def save_cells():+ return manager.save(+ SaveNotebookRequest(+ cell_ids=list(manager.app.cell_manager.cell_ids()),+ codes=["x = 2"],+ names=["__"],+ configs=[{}],+ filename=str(path),+ layout=None,+ persist=True,+ )+ )++ first, second = (+ (save_manifest, save_cells)+ if first_writer == "manifest"+ else (save_cells, save_manifest)+ )++ def second_save():+ second_started.set()+ return second()++ # An in-flight environment operation can retain its carrier while saves+ # proceed; it must not own the notebook's read-modify-write lock.+ with (+ script_metadata.materialized_for_environment(str(path)),+ ThreadPoolExecutor(max_workers=2) as executor,+ ):+ first_task = executor.submit(first)+ try:+ assert read.wait(timeout=5)+ second_task = executor.submit(second_save)+ assert second_started.wait(timeout=5)+ # Give the second writer a chance to finish if saves don't+ # serialize; the final contents must preserve both edits either way.+ wait([second_task], timeout=0.1)+ finally:+ release.set()+ first_task.result(timeout=5)+ second_task.result(timeout=5)++ assert (+ script_metadata.read_manifest(str(path))+ == 'dependencies = ["requests"]\n'+ )+ saved = load_notebook(path)+ assert [cell.code for cell in saved.app.cell_manager.cell_data()] == [+ "x = 2"+ ]diff --git a/tests/_session/test_venv.py b/tests/_session/test_venv.pyindex f8adf717f6..d1dd00469b 100644--- a/tests/_session/test_venv.py+++ b/tests/_session/test_venv.py@@ -187,7 +187,7 @@ def test_get_kernel_pythonpath_deduplicates(assert paths.count(os.path.normpath("/shared/site-packages")) == 1-def test_has_marimo_installed_returns_true_when_imports_succeed(+async def test_has_marimo_installed_returns_true_when_imports_succeed(monkeypatch: pytest.MonkeyPatch,) -> None:"""Test returns True when marimo and deps can be imported."""@@ -195,7 +195,7 @@ def test_has_marimo_installed_returns_true_when_imports_succeed(from marimo._version import __version__- def mock_run(+ async def mock_run(*args: Any, **_kwargs: Any) -> subprocess.CompletedProcess[str]:return subprocess.CompletedProcess(@@ -205,17 +205,17 @@ def test_has_marimo_installed_returns_true_when_imports_succeed(stderr="",)- monkeypatch.setattr(subprocess, "run", mock_run)- assert has_marimo_installed("/fake/python") is True+ monkeypatch.setattr("marimo._session._venv.run_command", mock_run)+ assert await has_marimo_installed("/fake/python") is True-def test_has_marimo_installed_returns_false_when_import_fails(+async def test_has_marimo_installed_returns_false_when_import_fails(monkeypatch: pytest.MonkeyPatch,) -> None:"""Test returns False when imports fail."""import subprocess- def mock_run(+ async def mock_run(*args: Any, **_kwargs: Any) -> subprocess.CompletedProcess[str]:return subprocess.CompletedProcess(@@ -225,17 +225,17 @@ def test_has_marimo_installed_returns_false_when_import_fails(stderr="ModuleNotFoundError: No module named 'marimo'",)- monkeypatch.setattr(subprocess, "run", mock_run)- assert has_marimo_installed("/fake/python") is False+ monkeypatch.setattr("marimo._session._venv.run_command", mock_run)+ assert await has_marimo_installed("/fake/python") is False-def test_has_marimo_installed_returns_true_on_version_mismatch(+async def test_has_marimo_installed_returns_true_on_version_mismatch(monkeypatch: pytest.MonkeyPatch,) -> None:"""Test returns True even when venv has different marimo version."""import subprocess- def mock_run(+ async def mock_run(*args: Any, **_kwargs: Any) -> subprocess.CompletedProcess[str]:return subprocess.CompletedProcess(@@ -245,12 +245,12 @@ def test_has_marimo_installed_returns_true_on_version_mismatch(stderr="",)- monkeypatch.setattr(subprocess, "run", mock_run)+ monkeypatch.setattr("marimo._session._venv.run_command", mock_run)# Should return True even with version mismatch (warning is logged)- assert has_marimo_installed("/fake/python") is True+ assert await has_marimo_installed("/fake/python") is True-def test_check_python_version_compatibility_returns_true_when_match(+async def test_check_python_version_compatibility_returns_true_when_match(monkeypatch: pytest.MonkeyPatch,) -> None:"""Test returns True when Python versions match."""@@ -258,7 +258,7 @@ def test_check_python_version_compatibility_returns_true_when_match(current_version = f"{sys.version_info.major}.{sys.version_info.minor}"- def mock_run(+ async def mock_run(*args: Any, **_kwargs: Any) -> subprocess.CompletedProcess[str]:return subprocess.CompletedProcess(@@ -268,17 +268,17 @@ def test_check_python_version_compatibility_returns_true_when_match(stderr="",)- monkeypatch.setattr(subprocess, "run", mock_run)- assert check_python_version_compatibility("/fake/python") is True+ monkeypatch.setattr("marimo._session._venv.run_command", mock_run)+ assert await check_python_version_compatibility("/fake/python") is True-def test_check_python_version_compatibility_returns_false_when_mismatch(+async def test_check_python_version_compatibility_returns_false_when_mismatch(monkeypatch: pytest.MonkeyPatch,) -> None:"""Test returns False when Python versions differ."""import subprocess- def mock_run(+ async def mock_run(*args: Any, **_kwargs: Any) -> subprocess.CompletedProcess[str]:return subprocess.CompletedProcess(@@ -288,5 +288,5 @@ def test_check_python_version_compatibility_returns_false_when_mismatch(stderr="",)- monkeypatch.setattr(subprocess, "run", mock_run)- assert check_python_version_compatibility("/fake/python") is False+ monkeypatch.setattr("marimo._session._venv.run_command", mock_run)+ assert await check_python_version_compatibility("/fake/python") is Falsediff --git a/tests/_utils/test_inline_script_metadata.py b/tests/_utils/test_inline_script_metadata.pyindex 1ee786d8b6..622c637060 100644--- a/tests/_utils/test_inline_script_metadata.py+++ b/tests/_utils/test_inline_script_metadata.py@@ -738,3 +738,23 @@ def test_pin_for_wasm_falls_back_to_installed_on_fetch_failure(out = pin_pep723_dependencies_for_wasm(_WASM_SRC, _wasm_path(tmp_path))# Fall-through path pins to whatever's installed.assert "numpy==1.99.0" in out+++ "contents",+ [+ '# A comment\ndependencies = ["numpy"]\n',+ '# /// script-example\ndependencies = ["numpy"]\n',+ '# /// script\n# dependencies = ["numpy"]\n# ///',+ ],+)+def test_markdown_manifest_accepts_comments_and_wrapped_metadata(+ contents: str,+) -> None:+ from marimo._environments import script_metadata+ from marimo._utils.inline_script_metadata import (+ get_headers_from_frontmatter,+ )++ header = get_headers_from_frontmatter({"pyproject": contents})["pyproject"]+ assert script_metadata.loads(header) == {"dependencies": ["numpy"]}