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
refactor: extract NotebookWorkspace from AppFileRouter (#9448)
Myles Scolnickd559ab7933c6
diff --git a/marimo/_cli/cli.py b/marimo/_cli/cli.pyindex 1850b5ff89..4703d2c077 100644--- a/marimo/_cli/cli.py+++ b/marimo/_cli/cli.py@@ -45,14 +45,18 @@ from marimo._cli.utils import (from marimo._config.settings import GLOBAL_SETTINGSfrom marimo._lint import run_checkfrom marimo._mcp.setup import McpType-from marimo._server.file_router import (- AppFileRouter,- LazyListOfFilesAppFileRouter,- flatten_files,-)from marimo._server.files.directory_scanner import DirectoryScannerfrom marimo._server.models.home import MarimoFilefrom marimo._server.start import start+from marimo._server.workspace import (+ DirectoryWorkspace,+ EmptyWorkspace,+ FixedFilesWorkspace,+ NotebookWorkspace,+ SingleFileWorkspace,+ flatten_files,+ infer_workspace,+)from marimo._session.model import SessionModefrom marimo._tutorials import (Tutorial,@@ -580,7 +584,7 @@ def edit(check_for_updates(print_latest_version)start(- file_router=AppFileRouter.infer(name),+ workspace=infer_workspace(name),development_mode=GLOBAL_SETTINGS.DEVELOPMENT_MODE,quiet=GLOBAL_SETTINGS.QUIET,host=host,@@ -735,7 +739,7 @@ def new(run_in_sandbox(sys.argv[1:], name=None, additional_features=["lsp"])return- file_router: AppFileRouter | None = None+ workspace: NotebookWorkspace | None = Noneif prompt is None:# We support unix-style prompting, cat prompt.txt | marimo new@@ -763,7 +767,7 @@ def new(suffix=".py", mode="w", encoding="utf-8", delete=False) as temp_file:temp_file.write(notebook_content)- file_router = AppFileRouter.infer(temp_file.name)+ workspace = infer_workspace(temp_file.name)def _cleanup() -> None:try:@@ -783,11 +787,11 @@ def new(f"Failed to generate notebook: {e!s}") from e- if file_router is None:- file_router = AppFileRouter.new_file()+ if workspace is None:+ workspace = EmptyWorkspace()start(- file_router=file_router,+ workspace=workspace,development_mode=GLOBAL_SETTINGS.DEVELOPMENT_MODE,quiet=GLOBAL_SETTINGS.QUIET,host=host,@@ -900,12 +904,12 @@ def _collect_marimo_files(paths: list[str]) -> _CollectedRunFiles:return _CollectedRunFiles(files=files, root_dir=root_dir)-def _create_run_file_router(+def _create_run_workspace(validated_paths: list[str], *, watch: bool-) -> AppFileRouter:- """Create the file router for `marimo run`.+) -> NotebookWorkspace:+ """Create the workspace for `marimo run`.- For `--watch` with a single directory, use a lazy directory router so the+ For `--watch` with a single directory, use a directory workspace so thegallery index can reflect file additions/deletions on subsequent requests.For all other invocation shapes, preserve static snapshot behavior."""@@ -914,22 +918,18 @@ def _create_run_file_router(and len(validated_paths) == 1and Path(validated_paths[0]).is_dir()):- return LazyListOfFilesAppFileRouter(- validated_paths[0], include_markdown=True- )+ return DirectoryWorkspace(validated_paths[0], include_markdown=True)has_directory = any(Path(path).is_dir() for path in validated_paths)is_multi = has_directory or len(validated_paths) > 1if is_multi:marimo_files = _collect_marimo_files(validated_paths)- return AppFileRouter.from_files(+ return FixedFilesWorkspace(marimo_files.files,directory=marimo_files.root_dir,- allow_single_file_key=False,- allow_dynamic=False,)- return AppFileRouter.from_filename(MarimoPath(validated_paths[0]))+ return SingleFileWorkspace.from_path(MarimoPath(validated_paths[0]))@main.command(@@ -1210,10 +1210,10 @@ def run("pyzmq",)- file_router = _create_run_file_router(validated_paths, watch=watch)+ workspace = _create_run_workspace(validated_paths, watch=watch)start(- file_router=file_router,+ workspace=workspace,development_mode=GLOBAL_SETTINGS.DEVELOPMENT_MODE,quiet=GLOBAL_SETTINGS.QUIET,host=host,@@ -1342,7 +1342,7 @@ def tutorial(path = create_temp_tutorial_file(name, temp_dir)start(- file_router=AppFileRouter.from_filename(path),+ workspace=SingleFileWorkspace.from_path(path),development_mode=GLOBAL_SETTINGS.DEVELOPMENT_MODE,quiet=GLOBAL_SETTINGS.QUIET,host=host,diff --git a/marimo/_cli/export/_common.py b/marimo/_cli/export/_common.pyindex 0f6d0b2554..30c578ab27 100644--- a/marimo/_cli/export/_common.py+++ b/marimo/_cli/export/_common.py@@ -8,8 +8,8 @@ from typing import TYPE_CHECKING, Anyimport click-from marimo._server.file_router import flatten_filesfrom marimo._server.files.directory_scanner import DirectoryScanner+from marimo._server.workspace import flatten_filesfrom marimo._utils.http import HTTPException, HTTPStatusfrom marimo._utils.marimo_path import MarimoPathdiff --git a/marimo/_server/api/endpoints/assets.py b/marimo/_server/api/endpoints/assets.pyindex 7fc203e6fc..793da1ca3f 100644--- a/marimo/_server/api/endpoints/assets.py+++ b/marimo/_server/api/endpoints/assets.py@@ -194,16 +194,14 @@ def og_thumbnail(*, request: Request) -> Response:app_state = AppState(request)file_key = (app_state.query_params(FILE_QUERY_PARAM_KEY)- or app_state.session_manager.file_router.get_unique_file_key()+ or app_state.session_manager.workspace.get_unique_file_key())if not file_key:raise HTTPException(status_code=HTTPStatus.NOT_FOUND, detail="File not found")- notebook_path = app_state.session_manager.file_router.resolve_file_path(- file_key- )+ notebook_path = app_state.session_manager.workspace.resolve(file_key)if notebook_path is None:raise HTTPException(status_code=HTTPStatus.NOT_FOUND, detail="File not found"@@ -313,7 +311,7 @@ async def index(request: Request) -> Response:file_key_from_query = app_state.query_params(FILE_QUERY_PARAM_KEY)file_key = (file_key_from_query- or app_state.session_manager.file_router.get_unique_file_key()+ or app_state.session_manager.workspace.get_unique_file_key())# Try local index.html first, fallback to asset_url if local file doesn't exist@@ -374,7 +372,7 @@ async def index(request: Request) -> Response:LOGGER.debug("Failed to pre-compute notebook snapshot")filename = app_manager.filename- directory = app_state.session_manager.file_router.directory+ directory = app_state.session_manager.workspace.directorylsp_workspace = _resolve_lsp_workspace(filename, directory)# Make filename relative to file router's directory if possiblediff --git a/marimo/_server/api/endpoints/execution.py b/marimo/_server/api/endpoints/execution.pyindex 638585f86e..1b94f81fa3 100644--- a/marimo/_server/api/endpoints/execution.py+++ b/marimo/_server/api/endpoints/execution.py@@ -18,7 +18,6 @@ from marimo._server.api.endpoints.ws.ws_connection_validator import ()from marimo._server.api.endpoints.ws_endpoint import DOC_MANAGERfrom marimo._server.api.utils import dispatch_control_request, parse_request-from marimo._server.file_router import MarimoFileKeyfrom marimo._server.models.models import (BaseResponse,DebugCellRequest,@@ -32,6 +31,7 @@ from marimo._server.models.models import ()from marimo._server.router import APIRouterfrom marimo._server.uvicorn_utils import close_uvicorn+from marimo._server.workspace import MarimoFileKeyfrom marimo._types.ids import ConsumerIdif TYPE_CHECKING:@@ -426,7 +426,7 @@ async def restart_session(# Close RTC doc if it existsfile_key: MarimoFileKey | None = (app_state.query_params(FILE_QUERY_PARAM_KEY)- or session_manager.file_router.get_unique_file_key()+ or session_manager.workspace.get_unique_file_key()or session.app_file_manager.path)if file_key is not None:@@ -461,7 +461,7 @@ async def shutdown(LOGGER.debug("Received shutdown request")app_state = AppState(request)session_manager = app_state.session_manager- file_router = session_manager.file_router+ workspace = session_manager.workspacedef shutdown_server() -> None:app_state.session_manager.shutdown()@@ -470,7 +470,7 @@ async def shutdown(# If we are only operating on a single file (new or explicit file),# and there are no other sessions (user may have opened another notebook# from the file explorer) then we should shutdown the whole server- key = file_router.get_unique_file_key()+ key = workspace.get_unique_file_key()if key and len(session_manager.sessions) <= 1:shutdown_server()return SuccessResponse()@@ -516,7 +516,7 @@ async def takeover_endpoint(file_key: MarimoFileKey | None = (app_state.query_params(FILE_QUERY_PARAM_KEY)- or app_state.session_manager.file_router.get_unique_file_key()+ or app_state.session_manager.workspace.get_unique_file_key())if file_key is None:LOGGER.error("No file key provided")diff --git a/marimo/_server/api/endpoints/file_explorer.py b/marimo/_server/api/endpoints/file_explorer.pyindex 6a9451672c..f31ec6c55b 100644--- a/marimo/_server/api/endpoints/file_explorer.py+++ b/marimo/_server/api/endpoints/file_explorer.py@@ -69,8 +69,8 @@ async def list_files("""app_state = AppState(request)body = await parse_request(request, cls=FileListRequest)- # Use file router's directory as default, fall back to cwd- directory = app_state.session_manager.file_router.directory+ # Use workspace's directory as default, fall back to cwd+ directory = app_state.session_manager.workspace.directoryroot = body.path or directory or file_system.get_root()files = file_system.list_files(root)return FileListResponse(files=files, root=root)diff --git a/marimo/_server/api/endpoints/files.py b/marimo/_server/api/endpoints/files.pyindex 24ff145f29..45550b1596 100644--- a/marimo/_server/api/endpoints/files.py+++ b/marimo/_server/api/endpoints/files.py@@ -111,9 +111,9 @@ async def rename_file("""body = await parse_request(request, cls=RenameNotebookRequest)app_state = AppState(request)- directory = app_state.session_manager.file_router.directory+ directory = app_state.session_manager.workspace.directory- # Resolve relative filenames against the file router's directory+ # Resolve relative filenames against the workspace's directoryif not Path(body.filename).is_absolute() and directory:body.filename = str(Path(directory) / body.filename)@@ -165,9 +165,9 @@ async def save("""app_state = AppState(request)body = await parse_request(request, cls=SaveNotebookRequest)- directory = app_state.session_manager.file_router.directory+ directory = app_state.session_manager.workspace.directory- # Resolve relative filenames against the file router's directory+ # Resolve relative filenames against the workspace's directoryif body.filename and not Path(body.filename).is_absolute():if directory:body.filename = str(Path(directory) / body.filename)@@ -213,8 +213,8 @@ async def copy(app_state = AppState(request)body = await parse_request(request, cls=CopyNotebookRequest)- # Resolve relative filenames against the file router's directory- directory = app_state.session_manager.file_router.directory+ # Resolve relative filenames against the workspace's directory+ directory = app_state.session_manager.workspace.directoryif directory:if body.source and not Path(body.source).is_absolute():body.source = str(Path(directory) / body.source)diff --git a/marimo/_server/api/endpoints/home.py b/marimo/_server/api/endpoints/home.pyindex 48caf3321e..a16b660313 100644--- a/marimo/_server/api/endpoints/home.py+++ b/marimo/_server/api/endpoints/home.py@@ -13,10 +13,6 @@ from starlette.responses import JSONResponsefrom marimo import _loggersfrom marimo._server.api.deps import AppStatefrom marimo._server.api.utils import parse_request-from marimo._server.file_router import (- count_files,- flatten_files,-)from marimo._server.files.directory_scanner import DirectoryScannerfrom marimo._server.models.home import (MarimoFile,@@ -28,6 +24,10 @@ from marimo._server.models.home import (WorkspaceFilesResponse,)from marimo._server.router import APIRouter+from marimo._server.workspace import (+ count_files,+ flatten_files,+)from marimo._session.model import ConnectionState, SessionModefrom marimo._tutorials import create_temp_tutorial_file # type: ignorefrom marimo._utils.http import HTTPException, HTTPStatus@@ -60,9 +60,9 @@ async def read_code($ref: "#/components/schemas/RecentFilesResponse""""app_state = AppState(request)- # Pass the file router's directory to filter and relativize paths+ # Pass the workspace's directory to filter and relativize pathsdirectory = None- dir_str = app_state.session_manager.file_router.directory+ dir_str = app_state.session_manager.workspace.directoryif dir_str:directory = pathlib.Path(dir_str)files = app_state.session_manager.recents.get_recents(directory)@@ -102,23 +102,21 @@ async def workspace_files(if session_manager.watch:# In watched folder mode, refresh the index to include new/removed files since the previous request.- session_manager.file_router.mark_stale()+ session_manager.workspace.invalidate()base_url = app_state.base_urlmode = session_manager.mode.valuedef get_files_with_metadata() -> list[FileInfo]:- files = session_manager.file_router.files+ files = session_manager.workspace.filesmarimo_files = [file for file in flatten_files(files) if file.is_marimo_file]result: list[FileInfo] = []for file in marimo_files:try:- resolved_path = (- session_manager.file_router.resolve_file_path(- file.path- )+ resolved_path = session_manager.workspace.resolve(+ file.path)except HTTPException as e:if e.status_code == HTTPStatus.NOT_FOUND:@@ -155,21 +153,19 @@ async def workspace_files(has_more = file_count >= MAX_FILESreturn WorkspaceFilesResponse(files=marimo_files,- root=session_manager.file_router.directory or "",+ root=session_manager.workspace.directory or "",has_more=has_more,file_count=file_count,)- # Mark stale (no-op for routers without cached listings) and toggle- # markdown inclusion (no-op-returns-self for non-directory routers).- session_manager.file_router.mark_stale()- session_manager.file_router = session_manager.file_router.toggle_markdown(- body.include_markdown- )- root = session_manager.file_router.directory or ""+ # Both calls are no-ops on workspaces that don't support these+ # capabilities (single-file, fixed-files, empty).+ session_manager.workspace.invalidate()+ session_manager.workspace.set_include_markdown(body.include_markdown)+ root = session_manager.workspace.directory or ""# Run file scanning in thread pool to avoid blocking the server- files = await asyncio.to_thread(lambda: session_manager.file_router.files)+ files = await asyncio.to_thread(lambda: session_manager.workspace.files)file_count = count_files(files)has_more = file_count >= MAX_FILES@@ -184,8 +180,8 @@ async def workspace_files(def _get_active_sessions(app_state: AppState) -> list[MarimoFile]:"""Get list of active sessions with prettified paths."""- # Get directory from file router for path relativization- base_dir = app_state.session_manager.file_router.directory+ # Get directory from workspace for path relativization+ base_dir = app_state.session_manager.workspace.directoryfiles: list[MarimoFile] = []for session_id, session in app_state.session_manager.sessions.items():@@ -287,11 +283,11 @@ async def tutorial(atexit.register(temp_dir.cleanup)- # Register the temp file/directory with the router so it can be accessed.- # Each method is a no-op on routers that don't support that capability.+ # Register the temp file/directory with the workspace so it can be accessed.+ # Each method is a no-op on workspaces that don't support that capability.app_state = AppState(request)- app_state.session_manager.file_router.register_temp_dir(temp_dir.name)- app_state.session_manager.file_router.register_allowed_file(+ app_state.session_manager.workspace.register_temp_dir(temp_dir.name)+ app_state.session_manager.workspace.register_allowed_path(path.absolute_name)diff --git a/marimo/_server/api/endpoints/ws/ws_connection_validator.py b/marimo/_server/api/endpoints/ws/ws_connection_validator.pyindex 4d8ae26e91..21f65a3d03 100644--- a/marimo/_server/api/endpoints/ws/ws_connection_validator.py+++ b/marimo/_server/api/endpoints/ws/ws_connection_validator.py@@ -11,7 +11,7 @@ from marimo import _loggersfrom marimo._server.api.auth import validate_authfrom marimo._server.api.deps import AppStatefrom marimo._server.codes import WebSocketCodes-from marimo._server.file_router import MarimoFileKey+from marimo._server.workspace import MarimoFileKeyfrom marimo._types.ids import SessionIdLOGGER = _loggers.marimo_logger()@@ -73,7 +73,7 @@ class WebSocketConnectionValidator:# Extract file_keyfile_key: MarimoFileKey | None = (self.app_state.query_params(FILE_QUERY_PARAM_KEY)- or self.app_state.session_manager.file_router.get_unique_file_key()+ or self.app_state.session_manager.workspace.get_unique_file_key())if file_key is None:@@ -106,7 +106,7 @@ class WebSocketConnectionValidator:"""file_key: MarimoFileKey | None = (self.app_state.query_params(FILE_QUERY_PARAM_KEY)- or self.app_state.session_manager.file_router.get_unique_file_key()+ or self.app_state.session_manager.workspace.get_unique_file_key())if file_key is None:diff --git a/marimo/_server/api/endpoints/ws/ws_kernel_ready.py b/marimo/_server/api/endpoints/ws/ws_kernel_ready.pyindex c2b049f449..f3bdea78cf 100644--- a/marimo/_server/api/endpoints/ws/ws_kernel_ready.py+++ b/marimo/_server/api/endpoints/ws/ws_kernel_ready.py@@ -18,9 +18,9 @@ from marimo._session.model import SessionModefrom marimo._types.ids import CellId_tif TYPE_CHECKING:- from marimo._server.file_router import MarimoFileKeyfrom marimo._server.rtc.doc import LoroDocManagerfrom marimo._server.session_manager import SessionManager+ from marimo._server.workspace import MarimoFileKeyfrom marimo._session import SessionLOGGER = _loggers.marimo_logger()diff --git a/marimo/_server/api/endpoints/ws/ws_rtc_handler.py b/marimo/_server/api/endpoints/ws/ws_rtc_handler.pyindex 2b0358ff42..6e0263ba56 100644--- a/marimo/_server/api/endpoints/ws/ws_rtc_handler.py+++ b/marimo/_server/api/endpoints/ws/ws_rtc_handler.py@@ -12,8 +12,8 @@ if TYPE_CHECKING:from loro import DiffEvent, ExportMode, LoroDocfrom starlette.websockets import WebSocket- from marimo._server.file_router import MarimoFileKeyfrom marimo._server.rtc.doc import LoroDocManager+ from marimo._server.workspace import MarimoFileKeyLOGGER = _loggers.marimo_logger()diff --git a/marimo/_server/api/lifespans.py b/marimo/_server/api/lifespans.pyindex 16b30a66dc..10903d0b08 100644--- a/marimo/_server/api/lifespans.py+++ b/marimo/_server/api/lifespans.py@@ -13,7 +13,6 @@ from marimo._server.ai.tools.tool_manager import setup_tool_managerfrom marimo._server.api.deps import AppState, AppStateBasefrom marimo._server.api.interrupt import InterruptHandlerfrom marimo._server.api.utils import open_url_in_browser-from marimo._server.file_router import AppFileRouterfrom marimo._server.lsp import any_lsp_server_runningfrom marimo._server.print import (print_experimental_features,@@ -26,6 +25,7 @@ from marimo._server.session_manager import SessionManagerfrom marimo._server.tokens import AuthTokenfrom marimo._server.utils import initialize_mimetypesfrom marimo._server.uvicorn_utils import close_uvicorn+from marimo._server.workspace import NEW_FILEfrom marimo._session.model import SessionModefrom marimo._utils.subprocess import cancel_pending_reaps@@ -159,18 +159,18 @@ async def logging(app: Starlette) -> AsyncIterator[None]:state = AppState.from_app(app)manager: SessionManager = state.session_managerquiet = state.quiet- file_router = manager.file_router+ workspace = manager.workspacemcp_server_enabled = state.mcp_server_enabledskew_protection_enabled = state.skew_protection# Startup messageif not quiet:- file = file_router.maybe_get_single_file()+ file = workspace.single_file()print_startup(file_name=file.name if file else None,url=_startup_url(state),run=manager.mode == SessionMode.RUN,- new=file_router.get_unique_file_key() == AppFileRouter.NEW_FILE,+ new=workspace.get_unique_file_key() == NEW_FILE,network=state.host == "0.0.0.0",startup_tip=state.startup_tip,)diff --git a/marimo/_server/asgi.py b/marimo/_server/asgi.pyindex 7565891255..1eac5d9188 100644--- a/marimo/_server/asgi.py+++ b/marimo/_server/asgi.py@@ -463,13 +463,13 @@ def create_asgi_app(from marimo._config.config import PartialMarimoConfigfrom marimo._config.manager import get_default_config_managerfrom marimo._server.api import lifespans- from marimo._server.file_router import AppFileRouterfrom marimo._server.lsp import NoopLspServerfrom marimo._server.main import create_starlette_appfrom marimo._server.registry import LIFESPAN_REGISTRYfrom marimo._server.session_manager import SessionManagerfrom marimo._server.tokens import AuthTokenfrom marimo._server.utils import initialize_asyncio+ from marimo._server.workspace import SingleFileWorkspacefrom marimo._session.model import SessionModefrom marimo._utils.lifespans import Lifespansfrom marimo._utils.marimo_path import MarimoPath@@ -544,7 +544,7 @@ def create_asgi_app()session_manager = SessionManager(- file_router=AppFileRouter.from_filename(MarimoPath(file_path)),+ workspace=SingleFileWorkspace.from_path(MarimoPath(file_path)),mode=SessionMode.RUN,quiet=quiet,include_code=include_code,diff --git a/marimo/_server/file_router.py b/marimo/_server/file_router.pydeleted file mode 100644index f7ef402da9..0000000000--- a/marimo/_server/file_router.py+++ /dev/null@@ -1,450 +0,0 @@-# Copyright 2026 Marimo. All rights reserved.-from __future__ import annotations--import abc-import os-from pathlib import Path-from typing import TYPE_CHECKING--from marimo import _loggers-from marimo._server.app_defaults import AppDefaults-from marimo._server.files.directory_scanner import DirectoryScanner-from marimo._server.files.path_validator import PathValidator-from marimo._server.models.files import FileInfo-from marimo._server.models.home import MarimoFile-from marimo._session.notebook import AppFileManager-from marimo._utils.http import HTTPException, HTTPStatus-from marimo._utils.marimo_path import MarimoPath-from marimo._utils.paths import normalize_path--if TYPE_CHECKING:- from collections.abc import Iterator--LOGGER = _loggers.marimo_logger()--# Some unique identifier for a file-MarimoFileKey = str---class AppFileRouter(abc.ABC):- """Abstract class for routing files to an AppFileManager."""-- NEW_FILE: MarimoFileKey = "__new__"-- @property- def directory(self) -> str | None:- return None-- @staticmethod- def infer(path: str) -> AppFileRouter:- if os.path.isfile(path):- LOGGER.debug("Routing to file %s", path)- return AppFileRouter.from_filename(MarimoPath(path))- if os.path.isdir(path):- LOGGER.debug("Routing to directory %s", path)- return AppFileRouter.from_directory(path)- raise HTTPException(- status_code=HTTPStatus.BAD_REQUEST,- detail=f"Path {path} is not a valid file or directory",- )-- @staticmethod- def from_filename(file: MarimoPath) -> AppFileRouter:- files = [- MarimoFile(- name=file.relative_name,- path=file.absolute_name,- last_modified=file.last_modified,- )- ]- return ListOfFilesAppFileRouter(files, allow_dynamic=True)-- @staticmethod- def from_directory(directory: str) -> AppFileRouter:- return LazyListOfFilesAppFileRouter(directory, include_markdown=False)-- @staticmethod- def from_files(- files: list[MarimoFile],- *,- directory: str | None = None,- allow_single_file_key: bool = True,- allow_dynamic: bool = False,- ) -> AppFileRouter:- return ListOfFilesAppFileRouter(- files,- directory=directory,- allow_single_file_key=allow_single_file_key,- allow_dynamic=allow_dynamic,- )-- @staticmethod- def new_file() -> AppFileRouter:- return NewFileAppFileRouter()-- def get_single_app_file_manager(- self,- defaults: AppDefaults | None = None,- ) -> AppFileManager:- key = self.get_unique_file_key()- assert key is not None, "Expected a single file"- return self.get_file_manager(key, defaults)-- @abc.abstractmethod- def get_file_manager(- self,- key: MarimoFileKey,- defaults: AppDefaults | None = None,- ) -> AppFileManager:- """Given a key, return an ``AppFileManager``."""-- @abc.abstractmethod- def resolve_file_path(self, key: MarimoFileKey) -> str | None:- """Resolve a file key to an absolute file path, without loading the app.-- This is useful for endpoints that need file-backed resources (e.g.- thumbnails) without the overhead of parsing/loading a notebook.-- Returns the absolute file path if resolvable, otherwise ``None`` (for- the new-file sentinel).- """-- @abc.abstractmethod- def get_unique_file_key(self) -> MarimoFileKey | None:- """- If there is a unique file key, return it. Otherwise, return None.- """-- @abc.abstractmethod- def maybe_get_single_file(self) -> MarimoFile | None:- """- If there is a single file, return it. Otherwise, return None.- """-- @property- @abc.abstractmethod- def files(self) -> list[FileInfo]:- """- Get all files in a recursive tree.- """-- # Optional capabilities — subclasses override only if they support them.-- def register_allowed_file(self, filepath: str) -> None:- """Allow a file path that wasn't part of the original collection.-- No-op by default; routers that maintain a fixed allowlist override.- """- del filepath-- def register_temp_dir(self, temp_dir: str) -> None:- """Register a temp directory as allowed for file access.-- No-op by default; only directory-backed routers override.- """- del temp_dir-- def is_file_in_allowed_temp_dir(self, filepath: str) -> bool:- """Whether a file lives inside an allowed temp directory.-- Returns ``False`` by default; only directory-backed routers override.- """- del filepath- return False-- def mark_stale(self) -> None: # noqa: B027 — intentional no-op default- """Invalidate any cached listing.-- No-op by default; lazy directory routers override.- """-- def toggle_markdown(self, include_markdown: bool) -> AppFileRouter:- """Return a router with markdown inclusion toggled.-- No-op by default — returns ``self``. Lazy directory routers override.- """- del include_markdown- return self---class NewFileAppFileRouter(AppFileRouter):- def get_unique_file_key(self) -> MarimoFileKey | None:- return AppFileRouter.NEW_FILE-- def maybe_get_single_file(self) -> MarimoFile | None:- return None-- @property- def files(self) -> list[FileInfo]:- return []-- def get_file_manager(- self,- key: MarimoFileKey,- defaults: AppDefaults | None = None,- ) -> AppFileManager:- defaults = defaults or AppDefaults()- if key.startswith(AppFileRouter.NEW_FILE):- return AppFileManager(None, defaults=defaults)- # Fall back to loading any existing path. This is used by callers- # (and tests) that bootstrap with ``new_file()`` but then create- # sessions for concrete files.- if os.path.exists(key):- return AppFileManager(key, defaults=defaults)- raise HTTPException(- status_code=HTTPStatus.NOT_FOUND,- detail=f"File {key} not found",- )-- def resolve_file_path(self, key: MarimoFileKey) -> str | None:- if key.startswith(AppFileRouter.NEW_FILE):- return None- if os.path.exists(key):- return key- raise HTTPException(- status_code=HTTPStatus.NOT_FOUND,- detail=f"File {key} not found",- )---class ListOfFilesAppFileRouter(AppFileRouter):- def __init__(- self,- files: list[MarimoFile],- directory: str | None = None,- allow_single_file_key: bool = True,- allow_dynamic: bool = False,- ) -> None:- self._files = files- self._directory = directory- self._allow_single_file_key = allow_single_file_key- self._allow_dynamic = allow_dynamic- self._allowed_paths = {- str(normalize_path(Path(MarimoPath(file.path).absolute_name)))- for file in files- }-- @property- def directory(self) -> str | None:- return self._directory-- @property- def files(self) -> list[FileInfo]:- return [- FileInfo(- id=file.path,- name=file.name,- path=file.path,- last_modified=file.last_modified,- is_directory=False,- is_marimo_file=True,- )- for file in self._files- ]-- def get_file_manager(- self,- key: MarimoFileKey,- defaults: AppDefaults | None = None,- ) -> AppFileManager:- defaults = defaults or AppDefaults()-- resolved_path = self.resolve_file_path(key)- if resolved_path is None:- return AppFileManager(None, defaults=defaults)- return AppFileManager(resolved_path, defaults=defaults)-- def resolve_file_path(self, key: MarimoFileKey) -> str | None:- if key.startswith(AppFileRouter.NEW_FILE):- if self._allow_single_file_key:- return None- raise HTTPException(- status_code=HTTPStatus.NOT_FOUND,- detail=f"File {key} not found",- )-- filepath = Path(key)- if not filepath.is_absolute() and self._directory:- filepath = Path(self._directory) / filepath- normalized_path = normalize_path(filepath)- absolute_path = str(normalized_path)- if absolute_path not in self._allowed_paths:- raise HTTPException(- status_code=HTTPStatus.NOT_FOUND,- detail=f"File {key} not found",- )-- if normalized_path.exists():- return absolute_path-- raise HTTPException(- status_code=HTTPStatus.NOT_FOUND,- detail=f"File {key} not found",- )-- def get_unique_file_key(self) -> MarimoFileKey | None:- if self._allow_single_file_key and len(self._files) == 1:- return self._files[0].path- return None-- def maybe_get_single_file(self) -> MarimoFile | None:- if self._allow_single_file_key and len(self._files) == 1:- return self._files[0]- return None-- def register_allowed_file(self, filepath: str) -> None:- """Allow a file path in this router.-- This extends the allowlist for files that were not part of the original- collection and may live outside the router's base directory (for- example, files created at runtime in a separate location).- """- if not self._allow_dynamic:- return- self._allowed_paths.add(- str(normalize_path(Path(MarimoPath(filepath).absolute_name)))- )---class LazyListOfFilesAppFileRouter(AppFileRouter):- def __init__(self, directory: str, include_markdown: bool) -> None:- # Make directory absolute but don't resolve symlinks to preserve user paths- abs_directory = Path(directory).absolute()- self._directory = str(abs_directory)- self.include_markdown = include_markdown- self._lazy_files: list[FileInfo] | None = None-- # Use PathValidator for security validation- self._validator = PathValidator(abs_directory)- # Use DirectoryScanner for file discovery (use absolute path)- self._scanner = DirectoryScanner(str(abs_directory), include_markdown)-- @property- def directory(self) -> str:- return self._directory-- def toggle_markdown(- self, include_markdown: bool- ) -> LazyListOfFilesAppFileRouter:- # Only create a new instance if the include_markdown flag is different- if include_markdown != self.include_markdown:- return LazyListOfFilesAppFileRouter(- self.directory, include_markdown- )- return self-- def mark_stale(self) -> None:- self._lazy_files = None-- def register_temp_dir(self, temp_dir: str) -> None:- """Register a temp directory as allowed for file access.-- Args:- temp_dir: The absolute path to the temp directory to allow.- """- self._validator.register_temp_dir(temp_dir)-- def is_file_in_allowed_temp_dir(self, filepath: str) -> bool:- """Check if a file is inside an allowed temp directory.-- Args:- filepath: The file path to check.-- Returns:- True if the file is in an allowed temp directory, False otherwise.- """- return self._validator.is_file_in_allowed_temp_dir(filepath)-- def get_file_manager(- self,- key: MarimoFileKey,- defaults: AppDefaults | None = None,- ) -> AppFileManager:- """- Given a key, return an AppFileManager.-- For directory sources, if the key is a relative path, resolve it- relative to the source's directory. Absolute paths must be within- the source's directory for security.- """- defaults = defaults or AppDefaults()- resolved_path = self.resolve_file_path(key)- if resolved_path is None:- return AppFileManager(None, defaults=defaults)- return AppFileManager(resolved_path, defaults=defaults)-- def resolve_file_path(self, key: MarimoFileKey) -> str | None:- if key.startswith(AppFileRouter.NEW_FILE):- return None-- directory = Path(self._directory)- filepath = Path(key)-- # Resolve filepath for use- # If filepath is relative, resolve it relative to directory- if not filepath.is_absolute():- filepath = directory / filepath-- # Use PathValidator for security validation- # Check if file is in an allowed temp directory (e.g., for tutorials)- # If so, skip the directory validation- is_in_allowed_temp_dir = self._validator.is_file_in_allowed_temp_dir(- str(filepath)- )-- if not is_in_allowed_temp_dir:- # Validate that filepath is inside directory- self._validator.validate_inside_directory(directory, filepath)-- if filepath.exists():- return str(filepath)-- raise HTTPException(- status_code=HTTPStatus.NOT_FOUND,- detail=f"File {key} not found",- )-- @property- def files(self) -> list[FileInfo]:- if self._lazy_files is None:- try:- # Use DirectoryScanner to load files- self._lazy_files = self._scanner.scan()- except HTTPException as e:- if e.status_code == HTTPStatus.REQUEST_TIMEOUT:- # Return partial results on timeout- LOGGER.warning(- "Timeout during file scan, returning partial results"- )- self._lazy_files = self._scanner.partial_results- else:- raise- return self._lazy_files-- def get_unique_file_key(self) -> str | None:- return None-- def maybe_get_single_file(self) -> MarimoFile | None:- return None---# Count total marimo files (not directories)-def count_files(file_list: list[FileInfo]) -> int:- count = 0- for item in file_list:- if not item.is_directory:- count += 1- if item.children:- count += count_files(item.children)- return count---def flatten_files(files: list[FileInfo]) -> Iterator[FileInfo]:- """Iterate over files, skipping directories."""- stack = files.copy()- while stack:- file = stack.pop()- if file.is_directory:- stack.extend(file.children)- else:- yield filediff --git a/marimo/_server/resume_strategies.py b/marimo/_server/resume_strategies.pyindex 3943691415..1996339cf6 100644--- a/marimo/_server/resume_strategies.py+++ b/marimo/_server/resume_strategies.py@@ -17,7 +17,7 @@ from marimo._types.ids import SessionIdLOGGER = _loggers.marimo_logger()if TYPE_CHECKING:- from marimo._server.file_router import MarimoFileKey+ from marimo._server.workspace import MarimoFileKeyclass SessionResumeStrategy(Protocol):diff --git a/marimo/_server/rtc/doc.py b/marimo/_server/rtc/doc.pyindex 277b6c16f1..7165f6bad6 100644--- a/marimo/_server/rtc/doc.py+++ b/marimo/_server/rtc/doc.py@@ -5,7 +5,7 @@ import asynciofrom typing import TYPE_CHECKINGfrom marimo import _loggers-from marimo._server.file_router import MarimoFileKey+from marimo._server.workspace import MarimoFileKeyfrom marimo._types.ids import CellId_tif TYPE_CHECKING:diff --git a/marimo/_server/session_manager.py b/marimo/_server/session_manager.pyindex 8ccfa66190..3c115d659d 100644--- a/marimo/_server/session_manager.py+++ b/marimo/_server/session_manager.py@@ -20,17 +20,18 @@ from marimo._runtime.commands import (SerializedQueryParams,)from marimo._server.app_defaults import AppDefaults-from marimo._server.file_router import (- AppFileRouter,- MarimoFileKey,- flatten_files,-)from marimo._server.lsp import LspServerfrom marimo._server.recents import RecentFilesManagerfrom marimo._server.resume_strategies import create_resume_strategyfrom marimo._server.session.listeners import RecentsTrackerListenerfrom marimo._server.token_manager import TokenManagerfrom marimo._server.tokens import AuthToken, SkewProtectionToken+from marimo._server.workspace import (+ NEW_FILE,+ MarimoFileKey,+ NotebookWorkspace,+ flatten_files,+)from marimo._session.app_host import AppHostContext, AppHostPoolfrom marimo._session.consumer import SessionConsumerfrom marimo._session.events import SessionEventBus@@ -70,7 +71,7 @@ class SessionManager:def __init__(self,*,- file_router: AppFileRouter,+ workspace: NotebookWorkspace,mode: SessionMode,quiet: bool,include_code: bool,@@ -86,7 +87,7 @@ class SessionManager:isolate_apps: bool = False,) -> None:# Core configuration- self.file_router = file_router+ self.workspace = workspaceself.mode = modeself.quiet = quietself.include_code = include_code@@ -111,11 +112,11 @@ class SessionManager:def _get_code() -> str:defaults = AppDefaults.from_config_manager(config_manager)- if file_router.get_unique_file_key() is not None:- app = file_router.get_single_app_file_manager(defaults).app+ if workspace.get_unique_file_key() is not None:+ app = workspace.get_single_app_file_manager(defaults).appreturn "".join(code for code in app.cell_manager.codes())- files = list(flatten_files(file_router.files))+ files = list(flatten_files(workspace.files))entries = [f"{file.path}:{file.last_modified or 0.0}"for file in files@@ -161,11 +162,9 @@ class SessionManager:def app_manager(self, key: MarimoFileKey) -> AppFileManager:"""Get the app manager for the given key."""defaults = AppDefaults.from_config_manager(self._config_manager)- if self.mode is SessionMode.EDIT and not key.startswith(- AppFileRouter.NEW_FILE- ):- self.file_router.register_allowed_file(key)- return self.file_router.get_file_manager(key, defaults)+ if self.mode is SessionMode.EDIT and not key.startswith(NEW_FILE):+ self.workspace.register_allowed_path(key)+ return self.workspace.load(key, defaults)def create_session(self,@@ -185,13 +184,9 @@ class SessionManager:# Get app file managerdefaults = AppDefaults.from_config_manager(self._config_manager)- if self.mode is SessionMode.EDIT and not file_key.startswith(- AppFileRouter.NEW_FILE- ):- self.file_router.register_allowed_file(file_key)- app_file_manager = self.file_router.get_file_manager(- file_key, defaults- )+ if self.mode is SessionMode.EDIT and not file_key.startswith(NEW_FILE):+ self.workspace.register_allowed_path(file_key)+ app_file_manager = self.workspace.load(file_key, defaults)# Create the sessionfrom marimo._runtime.commands import AppMetadata@@ -356,7 +351,7 @@ class SessionManager:def any_clients_connected(self, key: MarimoFileKey) -> bool:"""Returns True if at least one client has an open socket."""- if key.startswith(AppFileRouter.NEW_FILE):+ if key.startswith(NEW_FILE):return Falsesessions_for_file = self._repository.get_by_file_path(key)diff --git a/marimo/_server/start.py b/marimo/_server/start.pyindex 36a18df6fb..711bd18311 100644--- a/marimo/_server/start.py+++ b/marimo/_server/start.py@@ -22,10 +22,6 @@ from marimo._server.api import lifespansfrom marimo._server.config import (StarletteServerStateInit,)-from marimo._server.file_router import (- AppFileRouter,- LazyListOfFilesAppFileRouter,-)from marimo._server.lsp import CompositeLspServer, NoopLspServerfrom marimo._server.main import create_starlette_appfrom marimo._server.registry import LIFESPAN_REGISTRY@@ -36,6 +32,10 @@ from marimo._server.utils import (initialize_fd_limit,)from marimo._server.uvicorn_utils import initialize_signals+from marimo._server.workspace import (+ DirectoryWorkspace,+ NotebookWorkspace,+)from marimo._session.model import SessionModefrom marimo._tracer import LOGGERfrom marimo._utils.lifespans import Lifespans@@ -187,7 +187,7 @@ def _resolve_proxy(port: int, host: str, proxy: str | None) -> tuple[int, str]:def start(*,- file_router: AppFileRouter,+ workspace: NotebookWorkspace,mode: SessionMode,development_mode: bool,quiet: bool,@@ -250,9 +250,9 @@ def start(# This is the path that will be used to read the project configurationstart_path: str | None = None- if (single_file := file_router.maybe_get_single_file()) is not None:+ if (single_file := workspace.single_file()) is not None:start_path = single_file.path- elif (directory := file_router.directory) is not None:+ elif (directory := workspace.directory) is not None:start_path = directoryelse:start_path = os.getcwd()@@ -272,7 +272,7 @@ def start(if (mode == SessionMode.RUNand watch- and isinstance(file_router, LazyListOfFilesAppFileRouter)+ and isinstance(workspace, DirectoryWorkspace)):LOGGER.warning("Using `marimo run <folder> --watch`: gallery files are "@@ -293,7 +293,7 @@ def start(})- is_multi = file_router.get_unique_file_key() is None+ is_multi = workspace.get_unique_file_key() is Noneisolate_apps = is_multi and config_reader.experimental.get("isolate_apps", False)@@ -308,7 +308,7 @@ def start()session_manager = SessionManager(- file_router=file_router,+ workspace=workspace,mode=mode,quiet=quiet,include_code=include_code,diff --git a/marimo/_server/workspace/__init__.py b/marimo/_server/workspace/__init__.pynew file mode 100644index 0000000000..68dc8c90ce--- /dev/null+++ b/marimo/_server/workspace/__init__.py@@ -0,0 +1,58 @@+# Copyright 2026 Marimo. All rights reserved.+"""Server-side notebook workspace abstractions.++A :class:`NotebookWorkspace` represents the set of notebooks a server is+hosting. Concrete subclasses cover:++- :class:`EmptyWorkspace` — untitled (``__new__``) notebook+- :class:`SingleFileWorkspace` — single notebook (``marimo edit nb.py``)+- :class:`FixedFilesWorkspace` — fixed allowlist (``marimo run a.py b.py``)+- :class:`DirectoryWorkspace` — lazy directory scan (``marimo edit ./``)+"""++import os++from marimo import _loggers+from marimo._server.workspace._base import (+ NEW_FILE,+ MarimoFileKey,+ NotebookWorkspace,+ count_files,+ flatten_files,+)+from marimo._server.workspace._directory import DirectoryWorkspace+from marimo._server.workspace._empty import EmptyWorkspace+from marimo._server.workspace._fixed import FixedFilesWorkspace+from marimo._server.workspace._single import SingleFileWorkspace+from marimo._utils.http import HTTPException, HTTPStatus+from marimo._utils.marimo_path import MarimoPath++LOGGER = _loggers.marimo_logger()+++def infer_workspace(path: str) -> NotebookWorkspace:+ """Pick a concrete workspace for a user-supplied file or directory path."""+ if os.path.isfile(path):+ LOGGER.debug("Routing to file %s", path)+ return SingleFileWorkspace.from_path(MarimoPath(path))+ if os.path.isdir(path):+ LOGGER.debug("Routing to directory %s", path)+ return DirectoryWorkspace(path, include_markdown=False)+ raise HTTPException(+ status_code=HTTPStatus.BAD_REQUEST,+ detail=f"Path {path} is not a valid file or directory",+ )+++__all__ = [+ "NEW_FILE",+ "DirectoryWorkspace",+ "EmptyWorkspace",+ "FixedFilesWorkspace",+ "MarimoFileKey",+ "NotebookWorkspace",+ "SingleFileWorkspace",+ "count_files",+ "flatten_files",+ "infer_workspace",+]diff --git a/marimo/_server/workspace/_base.py b/marimo/_server/workspace/_base.pynew file mode 100644index 0000000000..1afb8cd354--- /dev/null+++ b/marimo/_server/workspace/_base.py@@ -0,0 +1,167 @@+# Copyright 2026 Marimo. All rights reserved.+"""Abstract base class for server-side notebook workspaces."""++from __future__ import annotations++import abc+from pathlib import Path+from typing import TYPE_CHECKING++from marimo._server.app_defaults import AppDefaults+from marimo._session.notebook import AppFileManager+from marimo._utils.http import HTTPException, HTTPStatus+from marimo._utils.marimo_path import MarimoPath+from marimo._utils.paths import normalize_path++if TYPE_CHECKING:+ from collections.abc import Iterator++ from marimo._server.models.files import FileInfo+ from marimo._server.models.home import MarimoFile++# Wire-format key for an untitled notebook. The string boundary is preserved+# for HTTP query params and session initialization IDs.+NEW_FILE: str = "__new__"++# Some unique identifier for a file. Phase 3 will replace this with a tagged+# union (NewFileKey | PathFileKey).+MarimoFileKey = str+++class NotebookWorkspace(abc.ABC):+ """A server-side abstraction for the set of notebooks a server is hosting.++ Owned by ``SessionManager``. Handles workspace browsing, allowlisting, lazy+ directory scanning, and security validation.+ """++ @property+ def directory(self) -> str | None:+ """The root directory of this workspace, if any."""+ return None++ @property+ @abc.abstractmethod+ def files(self) -> list[FileInfo]:+ """All files in this workspace as a recursive tree."""++ @abc.abstractmethod+ def single_file(self) -> MarimoFile | None:+ """If this workspace represents a single notebook, return it."""++ @abc.abstractmethod+ def get_unique_file_key(self) -> MarimoFileKey | None:+ """The unique file key for this workspace, if any."""++ @abc.abstractmethod+ def resolve(self, key: MarimoFileKey) -> str | None:+ """Resolve a key to an absolute path; ``None`` for new files.++ Useful for endpoints that need file-backed resources (e.g. thumbnails)+ without the overhead of parsing/loading a notebook.+ """++ def load(+ self,+ key: MarimoFileKey,+ defaults: AppDefaults | None = None,+ ) -> AppFileManager:+ """Load the notebook for the given key into an ``AppFileManager``.++ Built on top of :meth:`resolve` — subclasses customize ``resolve`` and+ inherit the right ``load`` semantics for free.+ """+ defaults = defaults or AppDefaults()+ resolved = self.resolve(key)+ if resolved is None:+ return AppFileManager(None, defaults=defaults)+ return AppFileManager(resolved, defaults=defaults)++ def get_single_app_file_manager(+ self,+ defaults: AppDefaults | None = None,+ ) -> AppFileManager:+ """Convenience for workspaces with a unique single file."""+ key = self.get_unique_file_key()+ assert key is not None, "Expected a single file"+ return self.load(key, defaults)++ # Optional capabilities — subclasses override only when supported.++ def register_allowed_path(self, path: str) -> None:+ """Allow a file path that wasn't part of the original collection.++ No-op by default. ``SingleFileWorkspace`` overrides to extend its+ allowlist for files created at runtime.+ """+ del path++ def register_temp_dir(self, temp_dir: str) -> None:+ """Register a temp directory as allowed for file access.++ No-op by default. ``DirectoryWorkspace`` overrides for tutorial+ support.+ """+ del temp_dir++ def is_in_allowed_temp_dir(self, path: str) -> bool:+ """Whether ``path`` lives inside an allowed temp directory.++ Returns ``False`` by default. ``DirectoryWorkspace`` overrides.+ """+ del path+ return False++ def invalidate(self) -> None: # noqa: B027 — intentional no-op default+ """Invalidate any cached listing.++ No-op by default. ``DirectoryWorkspace`` overrides.+ """++ def set_include_markdown(self, include_markdown: bool) -> None:+ """Toggle markdown inclusion in directory listings.++ No-op by default. ``DirectoryWorkspace`` overrides — mutates in+ place.+ """+ del include_markdown+++def file_not_found(key: MarimoFileKey) -> HTTPException:+ """Build the standard 404 response for an unresolvable file key."""+ return HTTPException(+ status_code=HTTPStatus.NOT_FOUND,+ detail=f"File {key} not found",+ )+++def normalize_allowlist_entry(path: str) -> str:+ """Canonicalize a path for storage in or lookup against an allowlist.++ Resolves the path to absolute form (validating it as a marimo source file)+ and applies our standard normalization. Allowlist entries and lookup keys+ must run through this same pipeline to match.+ """+ return str(normalize_path(Path(MarimoPath(path).absolute_name)))+++def count_files(file_list: list[FileInfo]) -> int:+ """Count notebook files (not directories) in a recursive tree."""+ count = 0+ for item in file_list:+ if not item.is_directory:+ count += 1+ if item.children:+ count += count_files(item.children)+ return count+++def flatten_files(files: list[FileInfo]) -> Iterator[FileInfo]:+ """Iterate over files, skipping directories."""+ stack = files.copy()+ while stack:+ file = stack.pop()+ if file.is_directory:+ stack.extend(file.children)+ else:+ yield filediff --git a/marimo/_server/workspace/_directory.py b/marimo/_server/workspace/_directory.pynew file mode 100644index 0000000000..b77b5ada50--- /dev/null+++ b/marimo/_server/workspace/_directory.py@@ -0,0 +1,108 @@+# Copyright 2026 Marimo. All rights reserved.+"""Workspace that lazily scans a directory of notebooks."""++from __future__ import annotations++from pathlib import Path+from typing import TYPE_CHECKING++from marimo import _loggers+from marimo._server.files.directory_scanner import DirectoryScanner+from marimo._server.files.path_validator import PathValidator+from marimo._server.workspace._base import (+ NEW_FILE,+ MarimoFileKey,+ NotebookWorkspace,+ file_not_found,+)+from marimo._utils.http import HTTPException, HTTPStatus++if TYPE_CHECKING:+ from marimo._server.models.files import FileInfo+ from marimo._server.models.home import MarimoFile++LOGGER = _loggers.marimo_logger()+++class DirectoryWorkspace(NotebookWorkspace):+ """A workspace backed by a directory, scanned lazily on demand.++ Used by ``marimo edit ./`` and ``marimo run ./``. File access is validated+ via :class:`PathValidator` to ensure paths stay within the directory (or an+ explicitly registered temp directory).+ """++ def __init__(self, directory: str, include_markdown: bool) -> None:+ # Make absolute but don't resolve symlinks — preserve user paths.+ abs_directory = Path(directory).absolute()+ self._directory = str(abs_directory)+ self._include_markdown = include_markdown+ self._lazy_files: list[FileInfo] | None = None+ self._validator = PathValidator(abs_directory)+ self._scanner = DirectoryScanner(str(abs_directory), include_markdown)++ @property+ def directory(self) -> str:+ return self._directory++ @property+ def include_markdown(self) -> bool:+ return self._include_markdown++ def set_include_markdown(self, include_markdown: bool) -> None:+ """Toggle markdown inclusion in place; rescans on next access."""+ if include_markdown == self._include_markdown:+ return+ self._include_markdown = include_markdown+ self._scanner = DirectoryScanner(self._directory, include_markdown)+ self._lazy_files = None++ def invalidate(self) -> None:+ self._lazy_files = None++ def register_temp_dir(self, temp_dir: str) -> None:+ self._validator.register_temp_dir(temp_dir)++ def is_in_allowed_temp_dir(self, path: str) -> bool:+ return self._validator.is_file_in_allowed_temp_dir(path)++ def single_file(self) -> MarimoFile | None:+ return None++ def get_unique_file_key(self) -> MarimoFileKey | None:+ return None++ def resolve(self, key: MarimoFileKey) -> str | None:+ if key.startswith(NEW_FILE):+ return None++ directory = Path(self._directory)+ filepath = Path(key)++ # Resolve relative paths against the workspace directory.+ if not filepath.is_absolute():+ filepath = directory / filepath++ # Tutorial files live in registered temp dirs and bypass containment.+ if not self._validator.is_file_in_allowed_temp_dir(str(filepath)):+ self._validator.validate_inside_directory(directory, filepath)++ if filepath.exists():+ return str(filepath)++ raise file_not_found(key)++ @property+ def files(self) -> list[FileInfo]:+ if self._lazy_files is None:+ try:+ self._lazy_files = self._scanner.scan()+ except HTTPException as e:+ if e.status_code == HTTPStatus.REQUEST_TIMEOUT:+ LOGGER.warning(+ "Timeout during file scan, returning partial results"+ )+ self._lazy_files = self._scanner.partial_results+ else:+ raise+ return self._lazy_filesdiff --git a/marimo/_server/workspace/_empty.py b/marimo/_server/workspace/_empty.pynew file mode 100644index 0000000000..2391fef6eb--- /dev/null+++ b/marimo/_server/workspace/_empty.py@@ -0,0 +1,50 @@+# Copyright 2026 Marimo. All rights reserved.+"""Workspace for an untitled (new) notebook."""++from __future__ import annotations++import os+from pathlib import Path+from typing import TYPE_CHECKING++from marimo._server.workspace._base import (+ NEW_FILE,+ MarimoFileKey,+ NotebookWorkspace,+ file_not_found,+)+from marimo._utils.paths import normalize_path++if TYPE_CHECKING:+ from marimo._server.models.files import FileInfo+ from marimo._server.models.home import MarimoFile+++class EmptyWorkspace(NotebookWorkspace):+ """An empty (untitled) workspace, used by ``marimo new``.++ The workspace key is the ``__new__`` sentinel; concrete file paths are+ accepted as a fallback so that callers which bootstrap with+ ``EmptyWorkspace`` and later open a real file (e.g. via the homepage)+ continue to work.+ """++ def get_unique_file_key(self) -> MarimoFileKey | None:+ return NEW_FILE++ def single_file(self) -> MarimoFile | None:+ return None++ @property+ def files(self) -> list[FileInfo]:+ return []++ def resolve(self, key: MarimoFileKey) -> str | None:+ if key.startswith(NEW_FILE):+ return None+ if os.path.exists(key):+ # Match sibling workspaces: return an absolute normalized path so+ # downstream comparisons (e.g. session lookups) don't trip on+ # relative-vs-absolute mismatches.+ return str(normalize_path(Path(key)))+ raise file_not_found(key)diff --git a/marimo/_server/workspace/_fixed.py b/marimo/_server/workspace/_fixed.pynew file mode 100644index 0000000000..aab60798a4--- /dev/null+++ b/marimo/_server/workspace/_fixed.py@@ -0,0 +1,80 @@+# Copyright 2026 Marimo. All rights reserved.+"""Workspace for a fixed list of notebooks (``marimo run a.py b.py``)."""++from __future__ import annotations++from pathlib import Path+from typing import TYPE_CHECKING++from marimo._server.models.files import FileInfo+from marimo._server.workspace._base import (+ NEW_FILE,+ MarimoFileKey,+ NotebookWorkspace,+ file_not_found,+ normalize_allowlist_entry,+)+from marimo._utils.paths import normalize_path++if TYPE_CHECKING:+ from marimo._server.models.home import MarimoFile+++class FixedFilesWorkspace(NotebookWorkspace):+ """A workspace pointing at a fixed allowlist of notebooks.++ Used by ``marimo run a.py b.py`` and ``marimo run dir/`` snapshots. The+ allowlist is set at construction time and never grows.+ """++ def __init__(+ self,+ files: list[MarimoFile],+ directory: str | None = None,+ ) -> None:+ self._files = files+ self._directory = directory+ self._allowed_paths = {+ normalize_allowlist_entry(file.path) for file in files+ }++ @property+ def directory(self) -> str | None:+ return self._directory++ @property+ def files(self) -> list[FileInfo]:+ return [+ FileInfo(+ id=file.path,+ name=file.name,+ path=file.path,+ last_modified=file.last_modified,+ is_directory=False,+ is_marimo_file=True,+ )+ for file in self._files+ ]++ def single_file(self) -> MarimoFile | None:+ return None++ def get_unique_file_key(self) -> MarimoFileKey | None:+ return None++ def resolve(self, key: MarimoFileKey) -> str | None:+ if key.startswith(NEW_FILE):+ raise file_not_found(key)++ filepath = Path(key)+ if not filepath.is_absolute() and self._directory:+ filepath = Path(self._directory) / filepath+ normalized_path = normalize_path(filepath)+ absolute_path = str(normalized_path)+ if absolute_path not in self._allowed_paths:+ raise file_not_found(key)++ if normalized_path.exists():+ return absolute_path++ raise file_not_found(key)diff --git a/marimo/_server/workspace/_single.py b/marimo/_server/workspace/_single.pynew file mode 100644index 0000000000..ff9325dcb2--- /dev/null+++ b/marimo/_server/workspace/_single.py@@ -0,0 +1,91 @@+# Copyright 2026 Marimo. All rights reserved.+"""Workspace for a single notebook (``marimo edit nb.py``)."""++from __future__ import annotations++from pathlib import Path+from typing import TYPE_CHECKING++from marimo._server.models.home import MarimoFile+from marimo._server.workspace._base import (+ NEW_FILE,+ MarimoFileKey,+ NotebookWorkspace,+ file_not_found,+ normalize_allowlist_entry,+)+from marimo._utils.marimo_path import MarimoPath+from marimo._utils.paths import normalize_path++if TYPE_CHECKING:+ from marimo._server.models.files import FileInfo+++class SingleFileWorkspace(NotebookWorkspace):+ """A workspace pointing at a single notebook.++ Used by ``marimo edit nb.py`` and ``marimo run nb.py``. In edit mode the+ allowlist can grow at runtime (via ``register_allowed_path``) to support+ notebooks created during the session.+ """++ def __init__(self, file: MarimoFile) -> None:+ self._file = file+ self._allowed_paths = {normalize_allowlist_entry(file.path)}++ @staticmethod+ def from_path(file: MarimoPath) -> SingleFileWorkspace:+ """Build a workspace from a validated marimo path."""+ return SingleFileWorkspace(+ MarimoFile(+ name=file.relative_name,+ path=file.absolute_name,+ last_modified=file.last_modified,+ )+ )++ @property+ def files(self) -> list[FileInfo]:+ from marimo._server.models.files import FileInfo++ return [+ FileInfo(+ id=self._file.path,+ name=self._file.name,+ path=self._file.path,+ last_modified=self._file.last_modified,+ is_directory=False,+ is_marimo_file=True,+ )+ ]++ def single_file(self) -> MarimoFile | None:+ return self._file++ def get_unique_file_key(self) -> MarimoFileKey | None:+ return self._file.path++ def resolve(self, key: MarimoFileKey) -> str | None:+ if key.startswith(NEW_FILE):+ return None++ filepath = Path(key)+ normalized_path = normalize_path(filepath)+ absolute_path = str(normalized_path)+ if absolute_path not in self._allowed_paths:+ raise file_not_found(key)++ if normalized_path.exists():+ return absolute_path++ raise file_not_found(key)++ def register_allowed_path(self, path: str) -> None:+ """Extend the allowlist for files created at runtime.++ Always extends, unconditionally — ``SingleFileWorkspace`` represents+ single-file edit mode, where the user can branch off into new+ notebooks created by the kernel. The fixed-allowlist behavior of+ :class:`FixedFilesWorkspace` is the read-only counterpart.+ """+ self._allowed_paths.add(normalize_allowlist_entry(path))diff --git a/marimo/_session/session_repository.py b/marimo/_session/session_repository.pyindex 0b4db898d3..65a3565a94 100644--- a/marimo/_session/session_repository.py+++ b/marimo/_session/session_repository.py@@ -13,7 +13,7 @@ from marimo._types.ids import ConsumerId, SessionIdif TYPE_CHECKING:from collections.abc import Mapping- from marimo._server.file_router import MarimoFileKey+ from marimo._server.workspace import MarimoFileKeyclass SessionRepository:diff --git a/tests/_cli/test_cli.py b/tests/_cli/test_cli.pyindex 4a1ed1aed9..bd02b21a95 100644--- a/tests/_cli/test_cli.py+++ b/tests/_cli/test_cli.py@@ -29,16 +29,16 @@ from marimo._ast import codegenfrom marimo._ast.cell import CellConfigfrom marimo._cli.cli import (_collect_marimo_files,- _create_run_file_router,+ _create_run_workspace,main as cli_main,)from marimo._config.manager import get_default_config_managerfrom marimo._dependencies.dependencies import DependencyManager-from marimo._server.file_router import (- LazyListOfFilesAppFileRouter,- ListOfFilesAppFileRouter,-)from marimo._server.templates.templates import get_version+from marimo._server.workspace import (+ DirectoryWorkspace,+ FixedFilesWorkspace,+)from marimo._utils.platform import is_windowsfrom marimo._utils.toml import toml_reader@@ -1173,30 +1173,30 @@ def test_collect_marimo_files_excludes_marimo_generated_markdown(assert str(generated_md) not in paths-def test_create_run_file_router_watch_single_directory_is_lazy(+def test_create_run_workspace_watch_single_directory_is_lazy(tmp_path: Path,) -> None:(tmp_path / "one.py").write_text("import marimo\napp = marimo.App()\n", encoding="utf-8")- router = _create_run_file_router([str(tmp_path)], watch=True)- assert isinstance(router, LazyListOfFilesAppFileRouter)- assert router.include_markdown is True+ workspace = _create_run_workspace([str(tmp_path)], watch=True)+ assert isinstance(workspace, DirectoryWorkspace)+ assert workspace.include_markdown is True-def test_create_run_file_router_no_watch_single_directory_is_static(+def test_create_run_workspace_no_watch_single_directory_is_static(tmp_path: Path,) -> None:(tmp_path / "one.py").write_text("import marimo\napp = marimo.App()\n", encoding="utf-8")- router = _create_run_file_router([str(tmp_path)], watch=False)- assert isinstance(router, ListOfFilesAppFileRouter)+ workspace = _create_run_workspace([str(tmp_path)], watch=False)+ assert isinstance(workspace, FixedFilesWorkspace)-def test_create_run_file_router_watch_mixed_paths_is_static(+def test_create_run_workspace_watch_mixed_paths_is_static(tmp_path: Path,) -> None:directory = tmp_path / "gallery"@@ -1209,10 +1209,10 @@ def test_create_run_file_router_watch_mixed_paths_is_static("import marimo\napp = marimo.App()\n", encoding="utf-8")- router = _create_run_file_router(+ workspace = _create_run_workspace([str(directory), str(standalone)], watch=True)- assert isinstance(router, ListOfFilesAppFileRouter)+ assert isinstance(workspace, FixedFilesWorkspace)def test_cli_run_with_show_code(temp_marimo_file: str) -> None:diff --git a/tests/_server/api/endpoints/test_assets.py b/tests/_server/api/endpoints/test_assets.pyindex 4e48789eef..065263fa12 100644--- a/tests/_server/api/endpoints/test_assets.py+++ b/tests/_server/api/endpoints/test_assets.py@@ -14,13 +14,18 @@ from marimo._server.api.endpoints.assets import (_inject_service_worker,)from marimo._server.api.utils import parse_title-from marimo._server.file_router import AppFileRouter+from marimo._server.workspace import (+ DirectoryWorkspace,+ EmptyWorkspace,+ FixedFilesWorkspace,+ SingleFileWorkspace,+)from marimo._session.model import SessionModefrom marimo._utils.marimo_path import MarimoPathfrom tests._server.mocks import (- file_router_scope,token_header,- with_file_router,+ with_workspace,+ workspace_scope,)if TYPE_CHECKING:@@ -39,7 +44,7 @@ def test_index(client: TestClient) -> None:response = client.get("/", headers=token_header())assert response.status_code == 200, response.textcontent = response.text- filename = session_manager.file_router.get_unique_file_key()+ filename = session_manager.workspace.get_unique_file_key()title = parse_title(filename)assert f"<marimo-filename hidden>{filename}</marimo-filename>" in contentassert filename is not None@@ -51,7 +56,7 @@ def test_index(client: TestClient) -> None:assert "public-files-sw.js" in content-@with_file_router(AppFileRouter.from_files([]))+@with_workspace(FixedFilesWorkspace([]))def test_index_when_empty(client: TestClient) -> None:# Login pageresponse = client.get("/") # no header@@ -67,7 +72,7 @@ def test_index_when_empty(client: TestClient) -> None:assert "<title>marimo</title>" in content-@with_file_router(AppFileRouter.new_file())+@with_workspace(EmptyWorkspace())def test_index_when_new_file(client: TestClient) -> None:# Login pageresponse = client.get("/") # no header@@ -206,8 +211,8 @@ def test_index_response_has_security_headers(client: TestClient) -> None:def test_index_with_directory(client: TestClient, tmp_path: Path) -> None:- with file_router_scope(- client, AppFileRouter.from_directory(str(tmp_path))+ with workspace_scope(+ client, DirectoryWorkspace(str(tmp_path), include_markdown=False)):response = client.get("/", headers=token_header())assert response.status_code == 200, response.text@@ -223,8 +228,8 @@ def test_index_with_directory_run_mode(app_state = AppState.from_app(cast(Any, client.app))app_state.session_manager.mode = SessionMode.RUN- with file_router_scope(- client, AppFileRouter.from_directory(str(tmp_path))+ with workspace_scope(+ client, DirectoryWorkspace(str(tmp_path), include_markdown=False)):response = client.get("/", headers=token_header())assert response.status_code == 200, response.text@@ -398,7 +403,7 @@ def test_vfile_download_query_param_sets_content_disposition(def test_public_file_serving(client: TestClient) -> None:# Setup app state with a mock notebookapp_state = AppState.from_app(cast(Any, client.app))- file_key = app_state.session_manager.file_router.get_unique_file_key()+ file_key = app_state.session_manager.workspace.get_unique_file_key()assert file_key is not Noneassert file_key.endswith(".py")@@ -438,7 +443,7 @@ def test_service_worker(client: TestClient) -> None:def test_public_file_security(client: TestClient) -> None:# Setup app stateapp_state = AppState.from_app(cast(Any, client.app))- file_key = app_state.session_manager.file_router.get_unique_file_key()+ file_key = app_state.session_manager.workspace.get_unique_file_key()assert file_key is not Noneassert file_key.endswith(".py")@@ -615,8 +620,8 @@ def test_index_lsp_workspace_with_filename(notebook_file = subdir.joinpath("notebook.py")notebook_file.touch()- with file_router_scope(- client, AppFileRouter.from_filename(MarimoPath(notebook_file))+ with workspace_scope(+ client, SingleFileWorkspace.from_path(MarimoPath(notebook_file))):response = client.get("/", headers=token_header())root_uri = json.dumps(temp_project_dir.as_uri())@@ -631,8 +636,9 @@ def test_index_lsp_workspace_with_root_directory(temp_project_dir = tmp_pathtemp_project_dir.joinpath("pyproject.toml").touch()- with file_router_scope(- client, AppFileRouter.from_directory(str(temp_project_dir))+ with workspace_scope(+ client,+ DirectoryWorkspace(str(temp_project_dir), include_markdown=False),):response = client.get("/?file=__new__file.py", headers=token_header())root_path = temp_project_dir@@ -651,7 +657,9 @@ def test_index_lsp_workspace_with_sub_directory(subdir = temp_project_dir.joinpath("subdir")subdir.mkdir()- with file_router_scope(client, AppFileRouter.from_directory(str(subdir))):+ with workspace_scope(+ client, DirectoryWorkspace(str(subdir), include_markdown=False)+ ):response = client.get("/?file=__new__file.py", headers=token_header())root_path = temp_project_dirroot_uri = json.dumps(root_path.as_uri())@@ -661,7 +669,7 @@ def test_index_lsp_workspace_with_sub_directory(assert f'"documentUri": {document_uri}' in response.text-@with_file_router(AppFileRouter.new_file())+@with_workspace(EmptyWorkspace())def test_index_lsp_workspace_fallback_to_cwd(client: TestClient) -> None:response = client.get("/", headers=token_header())root_path = Path.cwd()diff --git a/tests/_server/api/endpoints/test_file_explorer.py b/tests/_server/api/endpoints/test_file_explorer.pyindex e21d07ae73..8e954b0ddc 100644--- a/tests/_server/api/endpoints/test_file_explorer.py+++ b/tests/_server/api/endpoints/test_file_explorer.py@@ -122,7 +122,7 @@ def test_update_file_with_session(client: TestClient) -> None:# Enable watch mode (file watcher is set up automatically)sm.watch = True- file_path = sm.file_router.get_unique_file_key()+ file_path = sm.workspace.get_unique_file_key()assert file_pathfile_path = Path(file_path)assert file_path.exists()diff --git a/tests/_server/api/endpoints/test_files.py b/tests/_server/api/endpoints/test_files.pyindex 95b83576a5..ade1c754da 100644--- a/tests/_server/api/endpoints/test_files.py+++ b/tests/_server/api/endpoints/test_files.py@@ -37,7 +37,7 @@ HEADERS = {def test_rename(client: TestClient) -> None:current_filename = get_session_manager(client- ).file_router.get_unique_file_key()+ ).workspace.get_unique_file_key()assert current_filenamecurrent_path = Path(current_filename)@@ -103,7 +103,7 @@ def test_read_code_in_run_mode_without_include_code(@pytest.mark.flaky(reruns=5)@with_session(SESSION_ID)def test_save_file(client: TestClient) -> None:- filename = get_session_manager(client).file_router.get_unique_file_key()+ filename = get_session_manager(client).workspace.get_unique_file_key()assert filenamepath = Path(filename)@@ -157,7 +157,7 @@ def test_save_file(client: TestClient) -> None:)@with_session(SESSION_ID)def test_save_with_header(client: TestClient) -> None:- filename = get_session_manager(client).file_router.get_unique_file_key()+ filename = get_session_manager(client).workspace.get_unique_file_key()assert filenamepath = Path(filename)assert path.exists()@@ -208,7 +208,7 @@ def test_save_with_header(client: TestClient) -> None:@pytest.mark.flaky(reruns=5)@with_session(SESSION_ID)def test_save_with_invalid_file(client: TestClient) -> None:- filename = get_session_manager(client).file_router.get_unique_file_key()+ filename = get_session_manager(client).workspace.get_unique_file_key()assert filenamepath = Path(filename)assert path.exists()@@ -286,7 +286,7 @@ def test_save_file_cannot_rename(client: TestClient) -> None:@pytest.mark.flaky(reruns=5)@with_session(SESSION_ID)def test_save_app_config(client: TestClient) -> None:- filename = get_session_manager(client).file_router.get_unique_file_key()+ filename = get_session_manager(client).workspace.get_unique_file_key()assert filenamepath = Path(filename)@@ -315,7 +315,7 @@ def test_save_app_config(client: TestClient) -> None:@with_session(SESSION_ID)def test_copy_file(client: TestClient) -> None:- filename = get_session_manager(client).file_router.get_unique_file_key()+ filename = get_session_manager(client).workspace.get_unique_file_key()assert filenamepath = Path(filename)assert path.exists()@@ -346,18 +346,18 @@ def test_copy_file(client: TestClient) -> None:@with_session(SESSION_ID)def test_copy_file_with_relative_paths(client: TestClient) -> None:- """Test that copy works with relative paths when file_router has a directory."""- filename = get_session_manager(client).file_router.get_unique_file_key()+ """Test that copy works with relative paths when workspace has a directory."""+ filename = get_session_manager(client).workspace.get_unique_file_key()assert filenamepath = Path(filename)assert path.exists()file_contents = path.read_text()assert "import marimo as mo" in file_contents- # Get the directory and mock the file_router.directory property to simulate+ # Get the directory and mock the workspace.directory property to simulate# running from a subdirectory (marimo edit foo/dir/)directory = str(path.parent)- file_router = get_session_manager(client).file_router+ workspace = get_session_manager(client).workspace# Use relative paths (as the frontend would send when running from a# subdirectory)@@ -365,9 +365,9 @@ def test_copy_file_with_relative_paths(client: TestClient) -> None:dest_relative = f"_copy_{path.name}"copied_file = path.parent / dest_relative- # Mock the directory property on the file router+ # Mock the directory property on the workspacewith patch.object(- type(file_router),+ type(workspace),"directory",new_callable=lambda: property(lambda _: directory),):@@ -392,15 +392,15 @@ def test_copy_file_with_relative_paths(client: TestClient) -> None:@with_session(SESSION_ID)def test_path_traversal_save_blocked(client: TestClient) -> None:- """Save endpoint must not write outside the router's directory."""- filename = get_session_manager(client).file_router.get_unique_file_key()+ """Save endpoint must not write outside the workspace's directory."""+ filename = get_session_manager(client).workspace.get_unique_file_key()assert filenamepath = Path(filename)directory = str(path.parent)- file_router = get_session_manager(client).file_router+ workspace = get_session_manager(client).workspacewith patch.object(- type(file_router),+ type(workspace),"directory",new_callable=lambda: property(lambda _: directory),):@@ -422,15 +422,15 @@ def test_path_traversal_save_blocked(client: TestClient) -> None:@with_session(SESSION_ID)def test_path_traversal_rename_blocked(client: TestClient) -> None:- """Rename endpoint must not move files outside the router's directory."""- filename = get_session_manager(client).file_router.get_unique_file_key()+ """Rename endpoint must not move files outside the workspace's directory."""+ filename = get_session_manager(client).workspace.get_unique_file_key()assert filenamepath = Path(filename)directory = str(path.parent)- file_router = get_session_manager(client).file_router+ workspace = get_session_manager(client).workspacewith patch.object(- type(file_router),+ type(workspace),"directory",new_callable=lambda: property(lambda _: directory),):@@ -445,15 +445,15 @@ def test_path_traversal_rename_blocked(client: TestClient) -> None:@with_session(SESSION_ID)def test_path_traversal_copy_blocked(client: TestClient) -> None:- """Copy endpoint must not write outside the router's directory."""- filename = get_session_manager(client).file_router.get_unique_file_key()+ """Copy endpoint must not write outside the workspace's directory."""+ filename = get_session_manager(client).workspace.get_unique_file_key()assert filenamepath = Path(filename)directory = str(path.parent)- file_router = get_session_manager(client).file_router+ workspace = get_session_manager(client).workspacewith patch.object(- type(file_router),+ type(workspace),"directory",new_callable=lambda: property(lambda _: directory),):@@ -475,7 +475,7 @@ def test_rename_propagates() -> None:current_filename = get_session_manager(client- ).file_router.get_unique_file_key()+ ).workspace.get_unique_file_key()assert current_filenameassert os.path.exists(current_filename)@@ -558,7 +558,7 @@ def test_read_code_without_saved_file(client: TestClient) -> None:@with_session(SESSION_ID)def test_save_with_unicode_content(client: TestClient) -> None:"""Test save endpoint with unicode and special characters."""- filename = get_session_manager(client).file_router.get_unique_file_key()+ filename = get_session_manager(client).workspace.get_unique_file_key()assert filenamepath = Path(filename)@@ -633,7 +633,7 @@ def test_rename_with_edge_case_filenames(client: TestClient) -> None:for filename in EDGE_CASE_FILENAMES:current_filename = get_session_manager(client- ).file_router.get_unique_file_key()+ ).workspace.get_unique_file_key()assert current_filenamenew_path = Path(tmpdir) / filenamediff --git a/tests/_server/api/endpoints/test_home.py b/tests/_server/api/endpoints/test_home.pyindex 01d97663a7..9533ebb99f 100644--- a/tests/_server/api/endpoints/test_home.py+++ b/tests/_server/api/endpoints/test_home.py@@ -11,8 +11,11 @@ from typing import TYPE_CHECKINGimport pytest-from marimo._server.file_router import AppFileRouterfrom marimo._server.models.home import MarimoFile+from marimo._server.workspace import (+ DirectoryWorkspace,+ FixedFilesWorkspace,+)from marimo._session.model import SessionModefrom tests._server.mocks import get_session_manager, token_header, with_session@@ -30,7 +33,7 @@ HEADERS = {def test_workspace_files(client: TestClient) -> None:current_filename = get_session_manager(client- ).file_router.get_unique_file_key()+ ).workspace.get_unique_file_key()assert current_filenameresponse = client.post(@@ -64,7 +67,7 @@ def test_workspace_files_no_files(client: TestClient) -> None:def test_running_notebooks(client: TestClient) -> None:current_filename = get_session_manager(client- ).file_router.get_unique_file_key()+ ).workspace.get_unique_file_key()assert current_filenameresponse = client.post(@@ -127,7 +130,9 @@ def test_workspace_files_in_run_mode(client: TestClient) -> None:non_marimo_file = Path(temp_dir) / "text.txt"non_marimo_file.write_text("This is not a marimo file")- session_manager.file_router = AppFileRouter.from_directory(temp_dir)+ session_manager.workspace = DirectoryWorkspace(+ temp_dir, include_markdown=False+ )response = client.post("/api/home/workspace_files",@@ -154,7 +159,9 @@ def test_workspace_files_run_mode_watch_directory_refreshes_add_remove(file_one = Path(temp_dir) / "one.py"file_one.write_text("import marimo\napp = marimo.App()")- session_manager.file_router = AppFileRouter.from_directory(temp_dir)+ session_manager.workspace = DirectoryWorkspace(+ temp_dir, include_markdown=False+ )response_initial = client.post("/api/home/workspace_files",@@ -203,7 +210,9 @@ def test_workspace_files_empty_directory(client: TestClient) -> None:session_manager.mode = SessionMode.RUNwith tempfile.TemporaryDirectory() as temp_dir:- session_manager.file_router = AppFileRouter.from_directory(temp_dir)+ session_manager.workspace = DirectoryWorkspace(+ temp_dir, include_markdown=False+ )response = client.post("/api/home/workspace_files",@@ -239,10 +248,8 @@ def test_workspace_files_run_mode_allowlist(client: TestClient) -> None:last_modified=file_two.stat().st_mtime,),]- session_manager.file_router = AppFileRouter.from_files(- marimo_files,- directory=temp_dir,- allow_single_file_key=False,+ session_manager.workspace = FixedFilesWorkspace(+ marimo_files, directory=temp_dir)response = client.post(@@ -285,10 +292,8 @@ def test_workspace_files_run_mode_allowlist_skips_deleted_file(last_modified=file_two.stat().st_mtime,),]- session_manager.file_router = AppFileRouter.from_files(- marimo_files,- directory=temp_dir,- allow_single_file_key=False,+ session_manager.workspace = FixedFilesWorkspace(+ marimo_files, directory=temp_dir)file_two.unlink()@@ -330,7 +335,9 @@ def test_thumbnail_redirects_for_https_opengraph_image().lstrip())- session_manager.file_router = AppFileRouter.from_directory(temp_dir)+ session_manager.workspace = DirectoryWorkspace(+ temp_dir, include_markdown=False+ )response = client.get("/og/thumbnail?file=notebook.py",@@ -349,11 +356,9 @@ def test_tutorial_file_accessible_after_open(client: TestClient) -> None:This is an integration test for issue #7424.When a tutorial is opened via the endpoint, it creates a file in a temp- directory. This test verifies that the file router can access that+ directory. This test verifies that the workspace can access thatfile despite it being outside the base directory."""- from marimo._server.file_router import LazyListOfFilesAppFileRouter-# Open a tutorialresponse = client.post("/api/home/tutorial/open",@@ -364,13 +369,13 @@ def test_tutorial_file_accessible_after_open(client: TestClient) -> None:data = response.json()tutorial_path = data["path"]- # Verify the temp directory was registered with the file router+ # Verify the temp directory was registered with the workspacesession_manager = get_session_manager(client)- file_router = session_manager.file_router+ workspace = session_manager.workspace- # Only test for directory-based routers- if isinstance(file_router, LazyListOfFilesAppFileRouter):- assert file_router.is_file_in_allowed_temp_dir(tutorial_path)+ # Only test for directory-based workspaces+ if isinstance(workspace, DirectoryWorkspace):+ assert workspace.is_in_allowed_temp_dir(tutorial_path)# Try to get a file manager for the tutorial file# This should not raise an HTTPException about being outside the directory@@ -381,13 +386,11 @@ def test_tutorial_file_accessible_after_open(client: TestClient) -> None:@with_session(SESSION_ID)def test_running_notebooks_returns_relative_paths(client: TestClient) -> None:- """Test that running_notebooks returns paths relative to file router directory.+ """Test that running_notebooks returns paths relative to workspace directory.This is a regression test for the bug where `marimo edit subdirectory`would return paths like `subdirectory/notebook.py` instead of `notebook.py`."""- from marimo._server.file_router import LazyListOfFilesAppFileRouter-session_manager = get_session_manager(client)# Create a temp directory structure: /tmp/xxx/subdir/notebook.py@@ -413,15 +416,13 @@ def test_running_notebooks_returns_relative_paths(client: TestClient) -> None:with open(notebook_path, "w") as f:f.write(content)- # Create a file router pointing to the subdirectory+ # Create a workspace pointing to the subdirectory# This simulates `marimo edit subdir`- file_router = LazyListOfFilesAppFileRouter(- subdir, include_markdown=False- )+ workspace = DirectoryWorkspace(subdir, include_markdown=False)- # Replace the session manager's file router- original_file_router = session_manager.file_router- session_manager.file_router = file_router+ # Replace the session manager's workspace+ original_workspace = session_manager.workspace+ session_manager.workspace = workspace# Update the session's filename to the absolute path of the notebooksession = session_manager.get_session(SESSION_ID)@@ -444,16 +445,14 @@ def test_running_notebooks_returns_relative_paths(client: TestClient) -> None:assert files[0]["name"] == "notebook.py"finally:# Restore original state- session_manager.file_router = original_file_router+ session_manager.workspace = original_workspacesession.app_file_manager.filename = original_filename@pytest.mark.skipif(sys.platform == "win32", reason="Failing on Windows CI")@with_session(SESSION_ID, auto_shutdown=False)def test_shutdown_session_returns_relative_paths(client: TestClient) -> None:- """Test that shutdown_session returns paths relative to file router directory."""- from marimo._server.file_router import LazyListOfFilesAppFileRouter-+ """Test that shutdown_session returns paths relative to workspace directory."""session_manager = get_session_manager(client)# Create a second session to test shutdown returns correct paths@@ -479,12 +478,10 @@ def test_shutdown_session_returns_relative_paths(client: TestClient) -> None:with open(notebook_path, "w") as f:f.write(content)- file_router = LazyListOfFilesAppFileRouter(- subdir, include_markdown=False- )+ workspace = DirectoryWorkspace(subdir, include_markdown=False)- original_file_router = session_manager.file_router- session_manager.file_router = file_router+ original_workspace = session_manager.workspace+ session_manager.workspace = workspacesession = session_manager.get_session(SESSION_ID)assert session is not None@@ -503,7 +500,7 @@ def test_shutdown_session_returns_relative_paths(client: TestClient) -> None:# After shutdown, no sessions remainassert response.json() == {"files": []}finally:- session_manager.file_router = original_file_router+ session_manager.workspace = original_workspace# Note: session is already shut down, so we don't restore filename@@ -516,8 +513,6 @@ def test_running_notebooks_handles_files_outside_directory(client: TestClient,) -> None:"""Test that files outside the directory still get pretty_path treatment."""- from marimo._server.file_router import LazyListOfFilesAppFileRouter-session_manager = get_session_manager(client)auth_token = session_manager.auth_tokenheaders = token_header(auth_token)@@ -550,13 +545,13 @@ def test_running_notebooks_handles_files_outside_directory(with open(notebook_path, "w") as f:f.write(content)- # Set up file router pointing to router_dir- file_router = LazyListOfFilesAppFileRouter(+ # Set up workspace pointing to router_dir+ workspace = DirectoryWorkspace(router_dir, include_markdown=False)- original_file_router = session_manager.file_router- session_manager.file_router = file_router+ original_workspace = session_manager.workspace+ session_manager.workspace = workspacesession = session_manager.get_session(SESSION_ID)assert session is not None@@ -579,5 +574,5 @@ def test_running_notebooks_handles_files_outside_directory(# Path should contain the filename (exact path depends on CWD)assert "outside.py" in files[0]["path"]finally:- session_manager.file_router = original_file_router+ session_manager.workspace = original_workspacesession.app_file_manager.filename = original_filenamediff --git a/tests/_server/api/endpoints/test_resume_session.py b/tests/_server/api/endpoints/test_resume_session.pyindex 9be93471bd..9200553000 100644--- a/tests/_server/api/endpoints/test_resume_session.py+++ b/tests/_server/api/endpoints/test_resume_session.py@@ -114,7 +114,7 @@ def test_refresh_session(client: TestClient) -> None:def test_save_session(client: TestClient) -> None:filename = (get_session_manager(client)- .file_router.get_single_app_file_manager()+ .workspace.get_single_app_file_manager().filename)with client.websocket_connect(_create_ws_url("123")) as websocket:@@ -263,7 +263,7 @@ def test_resume_session_after_file_change(client: TestClient) -> None:# Write to the notebook file to add a new cell# we write it as the second to last cell- filename = session_manager.file_router.get_unique_file_key()+ filename = session_manager.workspace.get_unique_file_key()assert filenamewith open(filename) as f:content = f.read()diff --git a/tests/_server/api/endpoints/test_ws.py b/tests/_server/api/endpoints/test_ws.pyindex 54cbddb4d7..245ce376a9 100644--- a/tests/_server/api/endpoints/test_ws.py+++ b/tests/_server/api/endpoints/test_ws.py@@ -163,7 +163,7 @@ async def test_file_watcher_calls_reload(client: TestClient) -> None:with client.websocket_connect(WS_URL) as websocket:data = websocket.receive_json()assert_kernel_ready_response(data)- filename = session_manager.file_router.get_unique_file_key()+ filename = session_manager.workspace.get_unique_file_key()assert filenamewith open(filename, "a") as f: # noqa: ASYNC230f.write("\n# test")@@ -710,7 +710,7 @@ async def test_edit_mode_without_session_ttl_no_delayed_cleanup(def test_missing_file_key_closes_connection(client: TestClient) -> None:"""Test that missing file key causes connection to close.- This can happen when file_router.get_unique_file_key() returns None.+ This can happen when workspace.get_unique_file_key() returns None."""from unittest.mock import patch@@ -718,7 +718,7 @@ def test_missing_file_key_closes_connection(client: TestClient) -> None:# Mock get_unique_file_key to return Nonewith patch.object(- session_manager.file_router,+ session_manager.workspace,"get_unique_file_key",return_value=None,):diff --git a/tests/_server/api/endpoints/test_ws_rtc.py b/tests/_server/api/endpoints/test_ws_rtc.pyindex 6059a36415..4d4cc72025 100644--- a/tests/_server/api/endpoints/test_ws_rtc.py+++ b/tests/_server/api/endpoints/test_ws_rtc.py@@ -105,7 +105,7 @@ async def test_loro_cleanup_on_session_close(doc = LoroDoc()initial_code = doc.export(ExportMode.Snapshot())- file_key = get_session_manager(client).file_router.get_unique_file_key()+ file_key = get_session_manager(client).workspace.get_unique_file_key()assert file_key is not Nonewith (@@ -199,7 +199,7 @@ async def test_rtc_degrades_without_loro(client: TestClient) -> None:"""from unittest.mock import patch- file_key = get_session_manager(client).file_router.get_unique_file_key()+ file_key = get_session_manager(client).workspace.get_unique_file_key()assert file_key is not None# Clear any existing docs@@ -237,7 +237,7 @@ async def test_rtc_degrades_without_loro(client: TestClient) -> None:)async def test_ws_sync_without_existing_session(client: TestClient) -> None:"""Test that ws_sync endpoint requires an existing session."""- file_key = get_session_manager(client).file_router.get_unique_file_key()+ file_key = get_session_manager(client).workspace.get_unique_file_key()assert file_key is not Nonews_sync_url = f"/ws_sync?file={file_key}&access_token=fake-token"@@ -258,7 +258,7 @@ async def test_ws_sync_without_existing_session(client: TestClient) -> None:)async def test_ws_sync_cleanup_on_main_disconnect(client: TestClient) -> None:"""Test that ws_sync clients are cleaned up when main session disconnects."""- file_key = get_session_manager(client).file_router.get_unique_file_key()+ file_key = get_session_manager(client).workspace.get_unique_file_key()assert file_key is not None# Clear any existing docsdiff --git a/tests/_server/mocks.py b/tests/_server/mocks.pyindex 85f923c99e..0c395e2bfe 100644--- a/tests/_server/mocks.py+++ b/tests/_server/mocks.py@@ -12,10 +12,13 @@ from marimo._config.manager import (get_default_config_manager,)from marimo._server.config import StarletteServerStateInit-from marimo._server.file_router import AppFileRouterfrom marimo._server.lsp import NoopLspServerfrom marimo._server.session_manager import SessionManagerfrom marimo._server.tokens import AuthToken, SkewProtectionToken+from marimo._server.workspace import (+ NotebookWorkspace,+ SingleFileWorkspace,+)from marimo._session.model import SessionModefrom marimo._utils.marimo_path import MarimoPath@@ -79,7 +82,7 @@ if __name__ == "__main__":lsp_server = NoopLspServer()sm = SessionManager(- file_router=AppFileRouter.from_filename(MarimoPath(temp_file.name)),+ workspace=SingleFileWorkspace.from_path(MarimoPath(temp_file.name)),mode=mode,quiet=False,include_code=True,@@ -96,28 +99,28 @@ if __name__ == "__main__":@contextlib.contextmanager-def file_router_scope(- client: TestClient, file_router: AppFileRouter+def workspace_scope(+ client: TestClient, workspace: NotebookWorkspace) -> Iterator[None]:session_manager: SessionManager = cast(Any, client.app).state.session_manager- original_file_router = session_manager.file_router- session_manager.file_router = file_router+ original_workspace = session_manager.workspace+ session_manager.workspace = workspacetry:yieldfinally:- session_manager.file_router = original_file_router+ session_manager.workspace = original_workspace-def with_file_router(- file_router: AppFileRouter,+def with_workspace(+ workspace: NotebookWorkspace,) -> Callable[[Callable[..., None]], Callable[..., None]]:- """Decorator to create a session and close it after the test"""+ """Decorator to swap a workspace for the duration of the test."""def decorator(func: Callable[..., None]) -> Callable[..., None]:def wrapper(client: TestClient, *args: Any, **kwargs: Any) -> None:- with file_router_scope(client, file_router):+ with workspace_scope(client, workspace):func(client, *args, **kwargs)return wrapperdiff --git a/tests/_server/rtc/test_rtc_doc.py b/tests/_server/rtc/test_rtc_doc.pyindex 07be31cdf6..f0920a881b 100644--- a/tests/_server/rtc/test_rtc_doc.py+++ b/tests/_server/rtc/test_rtc_doc.py@@ -6,8 +6,8 @@ from typing import TYPE_CHECKING, castimport pytest-from marimo._server.file_router import MarimoFileKeyfrom marimo._server.rtc.doc import LoroDocManager+from marimo._server.workspace import MarimoFileKeyfrom marimo._types.ids import CellId_tif sys.version_info >= (3, 11) and sys.version_info < (3, 14):diff --git a/tests/_server/test_file_manager_absolute_path.py b/tests/_server/test_file_manager_absolute_path.pyindex cb8b8de53e..141bc7d7ac 100644--- a/tests/_server/test_file_manager_absolute_path.py+++ b/tests/_server/test_file_manager_absolute_path.py@@ -9,7 +9,7 @@ from pathlib import Pathimport pytest-from marimo._server.file_router import AppFileRouter+from marimo._server.workspace import DirectoryWorkspacefrom marimo._utils.http import HTTPException, HTTPStatusis_windows = sys.platform == "win32"@@ -44,7 +44,7 @@ if __name__ == "__main__":# Test with absolute pathabsolute_dir = str(test_dir.absolute())- router = AppFileRouter.from_directory(absolute_dir)+ router = DirectoryWorkspace(absolute_dir, include_markdown=False)# The directory should be stored correctly (always absolute)assert router.directory == absolute_dir@@ -58,7 +58,7 @@ if __name__ == "__main__":assert file_info.path == "notebook.py"# Try to get a file manager using the relative path from files list- file_manager = router.get_file_manager(file_info.path)+ file_manager = router.load(file_info.path)assert file_manager is not None# File manager resolves to absolute pathassert file_manager.filename == str(test_file)@@ -95,7 +95,7 @@ if __name__ == "__main__":# Test with relative pathrelative_dir = "test_dir"- router = AppFileRouter.from_directory(relative_dir)+ router = DirectoryWorkspace(relative_dir, include_markdown=False)# The directory is converted to absolute for consistencyassert router.directory == str(test_dir.absolute())@@ -108,7 +108,7 @@ if __name__ == "__main__":assert file_info.path == "notebook.py"# Try to get a file manager using the relative file path- file_manager = router.get_file_manager(file_info.path)+ file_manager = router.load(file_info.path)assert file_manager is not Noneassert file_manager.is_notebook_named# File manager resolves to absolute path@@ -143,15 +143,15 @@ if __name__ == "__main__":# Test with absolute pathabsolute_dir = str(test_dir.absolute())- absolute_router = AppFileRouter.from_directory(absolute_dir)+ absolute_router = DirectoryWorkspace(+ absolute_dir, include_markdown=False+ )absolute_files = absolute_router.filesassert len(absolute_files) > 0# Get file manager with absolute pathabsolute_file_path = absolute_files[0].path- absolute_file_manager = absolute_router.get_file_manager(- absolute_file_path- )+ absolute_file_manager = absolute_router.load(absolute_file_path)# Change to the parent directoryoriginal_cwd = os.getcwd()@@ -160,15 +160,15 @@ if __name__ == "__main__":# Test with relative pathrelative_dir = "test_dir"- relative_router = AppFileRouter.from_directory(relative_dir)+ relative_router = DirectoryWorkspace(+ relative_dir, include_markdown=False+ )relative_files = relative_router.filesassert len(relative_files) > 0# Get file manager with relative pathrelative_file_path = relative_files[0].path- relative_file_manager = relative_router.get_file_manager(- relative_file_path- )+ relative_file_manager = relative_router.load(relative_file_path)# Both should reference the same fileassert (@@ -215,7 +215,7 @@ if __name__ == "__main__":# Set up router with absolute directoryabsolute_dir = str(test_dir.absolute())- router = AppFileRouter.from_directory(absolute_dir)+ router = DirectoryWorkspace(absolute_dir, include_markdown=False)# Simulate the case where the client sends a relative filename# This might happen if the frontend sends just the filename@@ -229,7 +229,7 @@ if __name__ == "__main__":assert os.path.exists(full_path)# Try to get a file manager- file_manager = router.get_file_manager(full_path)+ file_manager = router.load(full_path)assert file_manager is not Noneassert file_manager.is_notebook_namedassert file_manager.read_file() is not None@@ -266,7 +266,7 @@ if __name__ == "__main__":# Set up router with absolute directoryabsolute_dir = str(test_dir.absolute())- router = AppFileRouter.from_directory(absolute_dir)+ router = DirectoryWorkspace(absolute_dir, include_markdown=False)# Get the files before changing directoryfiles_before = router.files@@ -285,7 +285,7 @@ if __name__ == "__main__":# Try to get a file managerfile_path = files_after[0].path- file_manager = router.get_file_manager(file_path)+ file_manager = router.load(file_path)assert file_manager is not Noneassert file_manager.is_notebook_namedcontent = file_manager.read_file()@@ -324,7 +324,7 @@ if __name__ == "__main__":# Set up router with absolute directoryabsolute_dir = str(test_dir.absolute())- router = AppFileRouter.from_directory(absolute_dir)+ router = DirectoryWorkspace(absolute_dir, include_markdown=False)# Change to a different directoryoriginal_cwd = os.getcwd()@@ -336,7 +336,7 @@ if __name__ == "__main__":# the router's directoryrelative_filename = "notebook.py"- file_manager = router.get_file_manager(relative_filename)+ file_manager = router.load(relative_filename)assert file_manager is not Noneassert file_manager.is_notebook_named# Verify it opened the correct file@@ -385,7 +385,7 @@ if __name__ == "__main__":# Simulate: marimo edit /absolute/path/to/dirabsolute_dir = str(test_dir.absolute())- router = AppFileRouter.from_directory(absolute_dir)+ router = DirectoryWorkspace(absolute_dir, include_markdown=False)# Change to a different directory to simulate the server running elsewhereoriginal_cwd = os.getcwd()@@ -400,7 +400,7 @@ if __name__ == "__main__":file_info = files[0]# This should work - using the full absolute path- file_manager = router.get_file_manager(file_info.path)+ file_manager = router.load(file_info.path)assert file_manager is not Noneassert file_manager.is_notebook_named@@ -411,7 +411,7 @@ if __name__ == "__main__":# This currently fails but should succeed# The router should resolve the basename relative to its directorytry:- file_manager_from_basename = router.get_file_manager(basename)+ file_manager_from_basename = router.load(basename)assert file_manager_from_basename is not Noneassert file_manager_from_basename.is_notebook_namedexcept HTTPException:@@ -457,7 +457,7 @@ if __name__ == "__main__":# Simulate: marimo edit /absolute/path/to/dirabsolute_dir = str(test_dir.absolute())- router = AppFileRouter.from_directory(absolute_dir)+ router = DirectoryWorkspace(absolute_dir, include_markdown=False)# Change to a different directoryoriginal_cwd = os.getcwd()@@ -470,7 +470,7 @@ if __name__ == "__main__":relative_path = os.path.join("subdir", "notebook.py")try:- file_manager = router.get_file_manager(relative_path)+ file_manager = router.load(relative_path)assert file_manager is not Noneassert file_manager.is_notebook_namedexcept HTTPException:@@ -497,7 +497,7 @@ if __name__ == "__main__":# Test with absolute directoryabsolute_dir = str(test_dir.absolute())- router = AppFileRouter.from_directory(absolute_dir)+ router = DirectoryWorkspace(absolute_dir, include_markdown=False)files = router.filesassert len(files) == 2@@ -512,7 +512,7 @@ if __name__ == "__main__":# Verify each file can be opened using its relative pathfor file_info in files:- file_manager = router.get_file_manager(file_info.path)+ file_manager = router.load(file_info.path)assert file_manager is not Noneassert file_manager.is_notebook_named@@ -536,15 +536,15 @@ if __name__ == "__main__":# Create router for test_dirabsolute_dir = str(test_dir.absolute())- router = AppFileRouter.from_directory(absolute_dir)+ router = DirectoryWorkspace(absolute_dir, include_markdown=False)# Should be able to open file within the directory- file_manager = router.get_file_manager(str(test_file.absolute()))+ file_manager = router.load(str(test_file.absolute()))assert file_manager is not None# Should NOT be able to open file outside the directorywith pytest.raises(HTTPException) as exc_info:- router.get_file_manager(str(other_file.absolute()))+ router.load(str(other_file.absolute()))assert exc_info.value.status_code == HTTPStatus.FORBIDDENassert "Access denied" in exc_info.value.detail@@ -566,11 +566,11 @@ if __name__ == "__main__":# Create router for test_dirabsolute_dir = str(test_dir.absolute())- router = AppFileRouter.from_directory(absolute_dir)+ router = DirectoryWorkspace(absolute_dir, include_markdown=False)# Try to access the secret file using absolute pathwith pytest.raises(HTTPException) as exc_info:- router.get_file_manager(str(secret_file.absolute()))+ router.load(str(secret_file.absolute()))assert exc_info.value.status_code == HTTPStatus.FORBIDDEN@@ -596,7 +596,9 @@ class TestRelativePathsInFileListing:nested_file.write_text("import marimo\napp = marimo.App()")# Create router- router = AppFileRouter.from_directory(str(test_dir.absolute()))+ router = DirectoryWorkspace(+ str(test_dir.absolute()), include_markdown=False+ )files = router.filesfile_paths = _collect_file_paths(files)@@ -607,7 +609,7 @@ class TestRelativePathsInFileListing:# Both should be openable using their relative pathsfor path in _collect_file_paths(files):- file_manager = router.get_file_manager(path)+ file_manager = router.load(path)assert file_manager is not Noneassert file_manager.is_notebook_named@@ -627,7 +629,9 @@ class TestRelativePathsInFileListing:deep_file.write_text("import marimo\napp = marimo.App()")# Create router- router = AppFileRouter.from_directory(str(test_dir.absolute()))+ router = DirectoryWorkspace(+ str(test_dir.absolute()), include_markdown=False+ )files = router.filesfile_paths = _collect_file_paths(files)@@ -638,7 +642,7 @@ class TestRelativePathsInFileListing:# Should be openable using the actual path from the files listactual_paths = _collect_file_paths(files)- file_manager = router.get_file_manager(actual_paths[0])+ file_manager = router.load(actual_paths[0])assert file_manager is not Noneassert file_manager.filename == str(deep_file.absolute())@@ -652,7 +656,9 @@ class TestRelativePathsInFileListing:test_file = test_dir / "notebook.py"test_file.write_text("import marimo\napp = marimo.App()")- router = AppFileRouter.from_directory(str(test_dir.absolute()))+ router = DirectoryWorkspace(+ str(test_dir.absolute()), include_markdown=False+ )# Get the relative path from files listfiles = router.files@@ -661,12 +667,12 @@ class TestRelativePathsInFileListing:assert relative_path == "notebook.py"# Open with relative path- manager_from_relative = router.get_file_manager(relative_path)+ manager_from_relative = router.load(relative_path)assert manager_from_relative is not None# Open with absolute pathabsolute_path = str(test_file.absolute())- manager_from_absolute = router.get_file_manager(absolute_path)+ manager_from_absolute = router.load(absolute_path)assert manager_from_absolute is not None# Both should point to the same file@@ -683,11 +689,13 @@ class TestRelativePathsInFileListing:outside_file = tmp_path / "outside.py"outside_file.write_text("import marimo\napp = marimo.App()")- router = AppFileRouter.from_directory(str(test_dir.absolute()))+ router = DirectoryWorkspace(+ str(test_dir.absolute()), include_markdown=False+ )# Try to access file outside using path traversalwith pytest.raises(HTTPException) as exc_info:- router.get_file_manager("../outside.py")+ router.load("../outside.py")assert exc_info.value.status_code == HTTPStatus.FORBIDDEN@@ -699,7 +707,9 @@ class TestRelativePathsInFileListing:test_dir = tmp_path / "test_dir"test_dir.mkdir()- router = AppFileRouter.from_directory(str(test_dir.absolute()))+ router = DirectoryWorkspace(+ str(test_dir.absolute()), include_markdown=False+ )# Try various path traversal attemptstraversal_attempts = [@@ -710,7 +720,7 @@ class TestRelativePathsInFileListing:for attempt in traversal_attempts:with pytest.raises(HTTPException) as exc_info:- router.get_file_manager(str(attempt))+ router.load(str(attempt))assert exc_info.value.status_code == HTTPStatus.FORBIDDEN, (f"Path traversal '{attempt}' should be blocked")@@ -728,10 +738,12 @@ class TestFileManagerPathResolution:test_file = test_dir / "notebook.py"test_file.write_text("import marimo\napp = marimo.App()")- router = AppFileRouter.from_directory(str(test_dir.absolute()))+ router = DirectoryWorkspace(+ str(test_dir.absolute()), include_markdown=False+ )# Try to open with ./ prefix- file_manager = router.get_file_manager("./notebook.py")+ file_manager = router.load("./notebook.py")assert file_manager is not Noneassert file_manager.filename == str(test_file.absolute())@@ -746,10 +758,12 @@ class TestFileManagerPathResolution:test_file = subdir / "notebook.py"test_file.write_text("import marimo\napp = marimo.App()")- router = AppFileRouter.from_directory(str(test_dir.absolute()))+ router = DirectoryWorkspace(+ str(test_dir.absolute()), include_markdown=False+ )# Path normalization should handle redundant slashes- file_manager = router.get_file_manager("subdir//notebook.py")+ file_manager = router.load("subdir//notebook.py")assert file_manager is not Noneassert file_manager.filename == str(test_file.absolute())@@ -758,10 +772,12 @@ class TestFileManagerPathResolution:test_dir = tmp_path / "test_dir"test_dir.mkdir()- router = AppFileRouter.from_directory(str(test_dir.absolute()))+ router = DirectoryWorkspace(+ str(test_dir.absolute()), include_markdown=False+ )with pytest.raises(HTTPException) as exc_info:- router.get_file_manager("nonexistent.py")+ router.load("nonexistent.py")assert exc_info.value.status_code == HTTPStatus.NOT_FOUND@@ -775,7 +791,7 @@ class TestFileManagerPathResolution:os.chdir(tmp_path)# Create router with relative path- router = AppFileRouter.from_directory("test_dir")+ router = DirectoryWorkspace("test_dir", include_markdown=False)# Directory should be stored as absoluteassert router.directory is not None@@ -798,7 +814,9 @@ class TestFileManagerPathResolution:try:# Create router while in tmp_pathos.chdir(tmp_path)- router = AppFileRouter.from_directory(str(test_dir.absolute()))+ router = DirectoryWorkspace(+ str(test_dir.absolute()), include_markdown=False+ )# Get files listfiles = router.files@@ -809,7 +827,7 @@ class TestFileManagerPathResolution:os.chdir(other_dir)# Should still be able to open file using relative path- file_manager = router.get_file_manager(relative_path)+ file_manager = router.load(relative_path)assert file_manager is not Noneassert file_manager.filename == str(test_file.absolute())diff --git a/tests/_server/test_session_manager.py b/tests/_server/test_session_manager.pyindex 1d67633410..ce7f34b0ff 100644--- a/tests/_server/test_session_manager.py+++ b/tests/_server/test_session_manager.py@@ -8,11 +8,11 @@ from unittest.mock import MagicMock, Mockimport pytestfrom marimo._config.manager import get_default_config_manager-from marimo._server.file_router import AppFileRouterfrom marimo._server.lsp import LspServerfrom marimo._server.session.listeners import RecentsTrackerListenerfrom marimo._server.session_manager import SessionManagerfrom marimo._server.tokens import AuthToken, SkewProtectionToken+from marimo._server.workspace import NEW_FILE, EmptyWorkspace, infer_workspacefrom marimo._session import (KernelManager,Session,@@ -64,7 +64,7 @@ def mock_session():@pytest.fixturedef session_manager():return SessionManager(- file_router=AppFileRouter.new_file(),+ workspace=EmptyWorkspace(),mode=SessionMode.EDIT,quiet=False,include_code=True,@@ -100,7 +100,7 @@ async def test_create_session_new(session_id,mock_session_consumer,query_params={},- file_key=AppFileRouter.NEW_FILE,+ file_key=NEW_FILE,auto_instantiate=False,)assert session_id in session_manager.sessions@@ -137,7 +137,7 @@ def test_maybe_resume_session_for_new_file(# Resume the same session_id with a new file -> doesn't matchresumed_session = session_manager.maybe_resume_session(- session_id, AppFileRouter.NEW_FILE+ session_id, NEW_FILE)assert resumed_session is None@@ -150,7 +150,7 @@ def test_maybe_resume_session_for_new_file(# Resume with a different session_id -> doesn't matchresumed_session = session_manager.maybe_resume_session(- "different_session_id", AppFileRouter.NEW_FILE+ "different_session_id", NEW_FILE)assert resumed_session is None@@ -199,9 +199,7 @@ def test_any_clients_connected_new_file() -> None:add_session(session_manager, session_id, mock_session)mock_session.app_file_manager = AppFileManager(filename=None)- assert (- session_manager.any_clients_connected(AppFileRouter.NEW_FILE) is False- )+ assert session_manager.any_clients_connected(NEW_FILE) is Falseassert session_manager.any_clients_connected("different_file.py") is False@@ -212,9 +210,7 @@ def test_any_clients_connected_existing_file() -> None:add_session(session_manager, session_id, mock_session)mock_session.app_file_manager = AppFileManager(filename=temp_marimo_file)- assert (- session_manager.any_clients_connected(AppFileRouter.NEW_FILE) is False- )+ assert session_manager.any_clients_connected(NEW_FILE) is Falseassert session_manager.any_clients_connected(temp_marimo_file) is Trueassert session_manager.any_clients_connected("different_file.py") is False@@ -288,7 +284,7 @@ def test_session_manager_auth_token_edit_mode_with_provided_token():"""Test that provided auth token is used in EDIT mode"""provided_token = AuthToken("custom-edit-token")session_manager = SessionManager(- file_router=AppFileRouter.new_file(),+ workspace=EmptyWorkspace(),mode=SessionMode.EDIT,quiet=False,include_code=True,@@ -309,7 +305,7 @@ def test_session_manager_auth_token_edit_mode_with_provided_token():def test_session_manager_auth_token_edit_mode_without_provided_token():"""Test that random auth token is generated in EDIT mode when none provided"""session_manager = SessionManager(- file_router=AppFileRouter.new_file(),+ workspace=EmptyWorkspace(),mode=SessionMode.EDIT,quiet=False,include_code=True,@@ -334,7 +330,7 @@ def test_session_manager_auth_token_run_mode_with_provided_token():"""Test that provided auth token is used in RUN mode"""provided_token = AuthToken("custom-run-token")session_manager = SessionManager(- file_router=AppFileRouter.new_file(),+ workspace=EmptyWorkspace(),mode=SessionMode.RUN,quiet=False,include_code=True,@@ -376,7 +372,7 @@ def test_session_manager_auth_token_run_mode_without_provided_token(file_path.write_text(notebook_content)session_manager = SessionManager(- file_router=AppFileRouter.infer(str(file_path)),+ workspace=infer_workspace(str(file_path)),mode=SessionMode.RUN,quiet=False,include_code=True,@@ -396,7 +392,7 @@ def test_session_manager_auth_token_run_mode_without_provided_token(# Create another session manager with the same code - should have same tokensession_manager2 = SessionManager(- file_router=AppFileRouter.infer(str(file_path)),+ workspace=infer_workspace(str(file_path)),mode=SessionMode.RUN,quiet=False,include_code=True,diff --git a/tests/_server/test_sessions.py b/tests/_server/test_sessions.pyindex 1d89057efe..8d0694ecda 100644--- a/tests/_server/test_sessions.py+++ b/tests/_server/test_sessions.py@@ -35,9 +35,9 @@ from marimo._runtime.commands import (SyncGraphCommand,UpdateUIElementCommand,)-from marimo._server.file_router import AppFileRouterfrom marimo._server.session_manager import SessionManagerfrom marimo._server.utils import initialize_asyncio+from marimo._server.workspace import SingleFileWorkspacefrom marimo._session import Sessionfrom marimo._session.consumer import SessionConsumerfrom marimo._session.events import SessionEventBus@@ -457,9 +457,9 @@ def __():try:# Create a session manager with file watching enabled- file_router = AppFileRouter.from_filename(MarimoPath(tmp_file))+ workspace = SingleFileWorkspace.from_path(MarimoPath(tmp_file))session_manager = SessionManager(- file_router=file_router,+ workspace=workspace,mode=SessionMode.EDIT,quiet=True,include_code=True,@@ -605,9 +605,9 @@ def test_watch_mode_does_not_override_config(tmp_path: Path) -> None:config_reader = get_default_config_manager(current_path=None)# Create a session manager with watch mode enabled- file_router = AppFileRouter.from_filename(MarimoPath(str(tmp_file)))+ workspace = SingleFileWorkspace.from_path(MarimoPath(str(tmp_file)))session_manager = SessionManager(- file_router=file_router,+ workspace=workspace,mode=SessionMode.EDIT,quiet=True,include_code=True,@@ -622,7 +622,7 @@ def test_watch_mode_does_not_override_config(tmp_path: Path) -> None:)session_manager_no_watch = SessionManager(- file_router=file_router,+ workspace=workspace,mode=SessionMode.EDIT,quiet=True,include_code=True,@@ -678,9 +678,9 @@ async def test_watch_mode_with_watcher_on_save_autorun(tmp_path: Path) -> None:)# Create a session manager with file watching enabled- file_router = AppFileRouter.from_filename(MarimoPath(str(tmp_file)))+ workspace = SingleFileWorkspace.from_path(MarimoPath(str(tmp_file)))session_manager = SessionManager(- file_router=file_router,+ workspace=workspace,mode=SessionMode.EDIT,quiet=True,include_code=True,@@ -787,9 +787,9 @@ async def test_watch_mode_with_watcher_on_save_lazy(tmp_path: Path) -> None:)# Create a session manager with file watching enabled- file_router = AppFileRouter.from_filename(MarimoPath(str(tmp_file)))+ workspace = SingleFileWorkspace.from_path(MarimoPath(str(tmp_file)))session_manager = SessionManager(- file_router=file_router,+ workspace=workspace,mode=SessionMode.EDIT,quiet=True,include_code=True,@@ -878,9 +878,9 @@ def __():try:# Create a session manager with file watching enabled- file_router = AppFileRouter.from_filename(MarimoPath(str(tmp_path1)))+ workspace = SingleFileWorkspace.from_path(MarimoPath(str(tmp_path1)))session_manager = SessionManager(- file_router=file_router,+ workspace=workspace,mode=SessionMode.EDIT,quiet=True,include_code=True,diff --git a/tests/_server/test_file_router.py b/tests/_server/test_workspace.pysimilarity index 67%rename from tests/_server/test_file_router.pyrename to tests/_server/test_workspace.pyindex e163593595..c4b10629ea 100644--- a/tests/_server/test_file_router.py+++ b/tests/_server/test_workspace.py@@ -8,19 +8,22 @@ from pathlib import Pathimport pytest-from marimo._server.file_router import (- AppFileRouter,- FileInfo,- LazyListOfFilesAppFileRouter,- ListOfFilesAppFileRouter,- NewFileAppFileRouter,- count_files,- flatten_files,-)from marimo._server.files.directory_scanner import is_marimo_appfrom marimo._server.files.path_validator import PathValidator+from marimo._server.models.files import FileInfofrom marimo._server.models.home import MarimoFile+from marimo._server.workspace import (+ NEW_FILE,+ DirectoryWorkspace,+ EmptyWorkspace,+ FixedFilesWorkspace,+ SingleFileWorkspace,+ count_files,+ flatten_files,+ infer_workspace,+)from marimo._utils.http import HTTPException, HTTPStatus+from marimo._utils.marimo_path import MarimoPathfile_contents = """import marimo@@ -29,7 +32,16 @@ app = marimo.App()"""-class TestAppFileRouter(unittest.TestCase):+def _marimo_file(path: str, name: str = "test.py") -> MarimoFile:+ """Build a ``MarimoFile`` for a real path on disk."""+ return MarimoFile(+ name=name,+ path=path,+ last_modified=os.path.getmtime(path),+ )+++class TestNotebookWorkspace(unittest.TestCase):def setUp(self):# Create a temporary directoryself.test_dir = tempfile.mkdtemp()@@ -70,176 +82,286 @@ class TestAppFileRouter(unittest.TestCase):shutil.rmtree(self.test_dir)def test_infer_file(self):- # Test infer method with a file path- router = AppFileRouter.infer(self.test_file1.name)- assert isinstance(router, ListOfFilesAppFileRouter)+ workspace = infer_workspace(self.test_file1.name)+ assert isinstance(workspace, SingleFileWorkspace)def test_infer_directory(self):- # Test infer method with a directory path- router = AppFileRouter.infer(self.test_dir)- assert isinstance(router, LazyListOfFilesAppFileRouter)-- def test_from_files(self):- # Test creating a router from a list of files- files = [- MarimoFile(- name="test.py",- path=self.test_file1.name,- last_modified=os.path.getmtime(self.test_file1.name),- )- ]- router = AppFileRouter.from_files(files)- assert isinstance(router, ListOfFilesAppFileRouter)-- def test_new_file_router(self):- # Test the NewFileAppFileRouter- router = AppFileRouter.new_file()- assert isinstance(router, NewFileAppFileRouter)- assert router.maybe_get_single_file() is None-- def test_lazy_list_of_files(self):- # Test the lazy loading of files in a directory- router = LazyListOfFilesAppFileRouter(- self.test_dir, include_markdown=False- )- files = router.files- assert (- len(files) == 3- ) # Assuming the directory only contains the two created files+ workspace = infer_workspace(self.test_dir)+ assert isinstance(workspace, DirectoryWorkspace)++ def test_fixed_files_workspace(self):+ workspace = FixedFilesWorkspace([_marimo_file(self.test_file1.name)])+ assert workspace.single_file() is None++ def test_empty_workspace(self):+ workspace = EmptyWorkspace()+ assert workspace.single_file() is None+ assert workspace.get_unique_file_key() == NEW_FILE- def test_lazy_list_with_broken_symlinks(self):- # Test the lazy loading of files in a directory with broken symlinks- # Create a broken symlink+ def test_directory_workspace_lists_files(self):+ workspace = DirectoryWorkspace(self.test_dir, include_markdown=False)+ files = workspace.files+ assert len(files) == 3++ def test_directory_workspace_with_broken_symlinks(self):broken_symlink = os.path.join(self.test_dir, "broken_symlink.py")os.symlink("non_existent_file", broken_symlink)- router = LazyListOfFilesAppFileRouter(- self.test_dir, include_markdown=False- )- files = router.files+ workspace = DirectoryWorkspace(self.test_dir, include_markdown=False)+ files = workspace.filesassert len(files) == 3-- # Remove the broken symlinkos.unlink(broken_symlink)- def test_lazy_list_with_markdown(self):- # Test the lazy loading of files in a directory with markdown- router = LazyListOfFilesAppFileRouter(- self.test_dir, include_markdown=True- )- # Create markdown files- files = router.files- assert len(files) == 4+ def test_directory_workspace_set_include_markdown_mutates_in_place(self):+ workspace = DirectoryWorkspace(self.test_dir, include_markdown=True)+ assert len(workspace.files) == 4- # Toggling markdown- router = router.toggle_markdown(False)- files = router.files- assert len(files) == 3+ workspace.set_include_markdown(False)+ assert len(workspace.files) == 3- # Toggle markdown back- router = router.toggle_markdown(True)- files = router.files- assert len(files) == 4-- def test_list_of_files_restricts_access(self):- files = [- MarimoFile(- name="test.py",- path=self.test_file1.name,- last_modified=os.path.getmtime(self.test_file1.name),- )- ]- router = ListOfFilesAppFileRouter(files)+ workspace.set_include_markdown(True)+ assert len(workspace.files) == 4++ def test_fixed_files_restricts_access(self):+ workspace = FixedFilesWorkspace([_marimo_file(self.test_file1.name)])with pytest.raises(HTTPException) as exc:- router.get_file_manager(self.test_file2.name)+ workspace.load(self.test_file2.name)assert exc.value.status_code == HTTPStatus.NOT_FOUND- def test_list_of_files_disallows_dynamic_allowlist(self):- files = [- MarimoFile(- name="test.py",- path=self.test_file1.name,- last_modified=os.path.getmtime(self.test_file1.name),- )- ]- router = ListOfFilesAppFileRouter(files, allow_dynamic=False)- router.register_allowed_file(self.test_file2.name)+ def test_fixed_files_register_allowed_path_is_noop(self):+ workspace = FixedFilesWorkspace([_marimo_file(self.test_file1.name)])+ workspace.register_allowed_path(self.test_file2.name)with pytest.raises(HTTPException) as exc:- router.get_file_manager(self.test_file2.name)+ workspace.load(self.test_file2.name)assert exc.value.status_code == HTTPStatus.NOT_FOUND- def test_list_of_files_disallows_new_file_key(self):- files = [- MarimoFile(- name="test.py",- path=self.test_file1.name,- last_modified=os.path.getmtime(self.test_file1.name),- )- ]- router = ListOfFilesAppFileRouter(files, allow_single_file_key=False)+ def test_single_file_register_allowed_path_grows_allowlist(self):+ workspace = SingleFileWorkspace(_marimo_file(self.test_file1.name))+ workspace.register_allowed_path(self.test_file2.name)+ manager = workspace.load(self.test_file2.name)+ assert manager is not None++ def test_fixed_files_disallows_new_file_key(self):+ workspace = FixedFilesWorkspace([_marimo_file(self.test_file1.name)])with pytest.raises(HTTPException) as exc:- router.get_file_manager(AppFileRouter.NEW_FILE)+ workspace.load(NEW_FILE)assert exc.value.status_code == HTTPStatus.NOT_FOUND- def test_list_of_files_resolve_file_path_supports_relative_key(self):- files = [- MarimoFile(- name="test.py",- path=self.test_file1.name,- last_modified=os.path.getmtime(self.test_file1.name),- )- ]- router = ListOfFilesAppFileRouter(files, directory=self.test_dir)+ def test_fixed_files_resolve_supports_relative_key(self):+ workspace = FixedFilesWorkspace(+ [_marimo_file(self.test_file1.name)],+ directory=self.test_dir,+ )relative_key = str(Path(self.test_file1.name).relative_to(self.test_dir))- resolved = router.resolve_file_path(relative_key)+ resolved = workspace.resolve(relative_key)assert resolved == self.test_file1.name- def test_lazy_list_of_get_app_file_manager(self):- router = LazyListOfFilesAppFileRouter(- self.test_dir, include_markdown=False- )+ def test_directory_workspace_load(self):+ workspace = DirectoryWorkspace(self.test_dir, include_markdown=False)filename = self.test_file1.nameassert os.path.exists(filename), f"File {filename} does not exist"- file_manager = router.get_file_manager(key=filename)+ file_manager = workspace.load(key=filename)assert file_manager.filename == filename- def test_lazy_list_of_get_app_file_manager_nested(self):- router = LazyListOfFilesAppFileRouter(- self.test_dir, include_markdown=False- )+ def test_directory_workspace_load_nested(self):+ workspace = DirectoryWorkspace(self.test_dir, include_markdown=False)nested_filename = self.nested_file.name- file_manager = router.get_file_manager(key=nested_filename)+ file_manager = workspace.load(key=nested_filename)assert file_manager.filename == self.nested_file.nameassert file_manager.filename is not Noneassert os.path.exists(file_manager.filename)assert file_manager.filename.startswith(self.test_dir)assert "nested" in file_manager.filename- def test_list_of_files_resolves_dotdot_in_path(self):+ def test_single_file_resolves_dotdot_in_path(self):"""Paths with '..' components should resolve correctly.Regression test for https://github.com/marimo-team/marimo/issues/8414"""- # Build a path with '..' that resolves to test_file1- # e.g. /tmp/dir/nested/../file.py -> /tmp/dir/file.pydotdot_path = os.path.join(self.nested_dir, "..", os.path.basename(self.test_file1.name))- files = [- MarimoFile(- name="test.py",- path=dotdot_path,- last_modified=os.path.getmtime(self.test_file1.name),- )- ]- router = ListOfFilesAppFileRouter(files)- key = router.get_unique_file_key()+ workspace = SingleFileWorkspace.from_path(MarimoPath(dotdot_path))+ key = workspace.get_unique_file_key()assert key is not None- resolved = router.resolve_file_path(key)+ resolved = workspace.resolve(key)+ assert resolved is not None+ assert os.path.exists(resolved)++ def test_no_op_capabilities_default_to_inert(self):+ """All non-directory workspaces share inert defaults for capabilities."""+ workspaces = [+ EmptyWorkspace(),+ SingleFileWorkspace.from_path(MarimoPath(self.test_file1.name)),+ FixedFilesWorkspace([]),+ ]+ for workspace in workspaces:+ # No-ops shouldn't raise.+ workspace.register_temp_dir("/tmp/whatever")+ workspace.invalidate()+ workspace.set_include_markdown(True)+ assert workspace.is_in_allowed_temp_dir("/anywhere") is False++ # ----- security: SingleFileWorkspace -----++ def test_single_file_blocks_unrelated_absolute_path(self):+ """A SingleFileWorkspace must reject any path other than its file."""+ workspace = SingleFileWorkspace.from_path(+ MarimoPath(self.test_file1.name)+ )+ with pytest.raises(HTTPException) as exc:+ workspace.resolve(self.test_file2.name)+ assert exc.value.status_code == HTTPStatus.NOT_FOUND++ def test_single_file_blocks_path_traversal(self):+ """`..` segments that escape the allowed file are rejected."""+ workspace = SingleFileWorkspace.from_path(+ MarimoPath(self.test_file1.name)+ )+ # /tmp/dir/file1.py + /../../etc/passwd → /etc/passwd, not in allowlist+ traversal = os.path.join(+ self.nested_dir, "..", "..", "..", "etc", "passwd"+ )+ with pytest.raises(HTTPException) as exc:+ workspace.resolve(traversal)+ assert exc.value.status_code == HTTPStatus.NOT_FOUND++ def test_single_file_accepts_dotdot_that_normalizes_to_allowed(self):+ """`..` segments that normalize back to the allowed file are accepted."""+ workspace = SingleFileWorkspace.from_path(+ MarimoPath(self.test_file1.name)+ )+ # nested/../<basename of test_file1> resolves to test_file1+ equivalent = os.path.join(+ self.nested_dir, "..", os.path.basename(self.test_file1.name)+ )+ resolved = workspace.resolve(equivalent)+ assert resolved == self.test_file1.name++ # ----- security: FixedFilesWorkspace -----++ def test_fixed_files_blocks_path_traversal(self):+ """Relative `..` keys that escape the allowlist must 404."""+ workspace = FixedFilesWorkspace(+ [_marimo_file(self.test_file1.name)],+ directory=self.test_dir,+ )+ with pytest.raises(HTTPException) as exc:+ workspace.resolve("../../../etc/passwd")+ assert exc.value.status_code == HTTPStatus.NOT_FOUND++ def test_fixed_files_blocks_absolute_path_outside_allowlist(self):+ """Absolute paths outside the allowlist must 404 even if they exist."""+ workspace = FixedFilesWorkspace(+ [_marimo_file(self.test_file1.name)],+ directory=self.test_dir,+ )+ # test_file2 exists on disk inside the same directory but is not on the+ # allowlist — must still be denied.+ with pytest.raises(HTTPException) as exc:+ workspace.resolve(self.test_file2.name)+ assert exc.value.status_code == HTTPStatus.NOT_FOUND++ def test_fixed_files_accepts_dotdot_that_normalizes_to_allowed(self):+ """Regression test for #8414 — ``..`` paths must normalize correctly."""+ dotdot_path = os.path.join(+ self.nested_dir, "..", os.path.basename(self.test_file1.name)+ )+ workspace = FixedFilesWorkspace([_marimo_file(dotdot_path)])+ resolved = workspace.resolve(dotdot_path)assert resolved is not Noneassert os.path.exists(resolved)+ def test_fixed_files_new_file_key_is_rejected(self):+ """``__new__`` keys are not valid in run mode."""+ workspace = FixedFilesWorkspace([])+ with pytest.raises(HTTPException) as exc:+ workspace.resolve(NEW_FILE)+ assert exc.value.status_code == HTTPStatus.NOT_FOUND++ # ----- security: DirectoryWorkspace -----++ def test_directory_workspace_new_file_prefix_does_not_leak(self):+ """``__new__`` prefix returns None — does not bypass containment.++ ``startswith(NEW_FILE)`` could otherwise be coaxed into accepting+ crafted keys like ``__new__../etc/passwd``; verify those still resolve+ to ``None`` (a blank notebook), never an arbitrary file.+ """+ workspace = DirectoryWorkspace(self.test_dir, include_markdown=False)+ for key in (+ NEW_FILE,+ f"{NEW_FILE}../etc/passwd",+ f"{NEW_FILE}/etc/passwd",+ ):+ assert workspace.resolve(key) is None++ def test_directory_workspace_temp_dir_does_not_enable_traversal(self):+ """A temp-dir bypass must not let attackers escape via ``..``."""+ with (+ tempfile.TemporaryDirectory() as base_dir,+ tempfile.TemporaryDirectory() as temp_dir,+ ):+ workspace = DirectoryWorkspace(base_dir, include_markdown=False)+ workspace.register_temp_dir(temp_dir)++ # Path that traverses through the temp dir to escape entirely.+ traversal = os.path.join(temp_dir, "..", "..", "etc", "passwd")+ with pytest.raises(HTTPException) as exc:+ workspace.resolve(traversal)+ # The path normalizes to /etc/passwd (or equivalent), neither in+ # the temp dir nor in the workspace directory — must be denied.+ assert exc.value.status_code in (+ HTTPStatus.FORBIDDEN,+ HTTPStatus.NOT_FOUND,+ )++ # ----- security: EmptyWorkspace -----++ def test_empty_workspace_load_with_new_file_key_returns_blank(self):+ """Bare ``__new__`` key always yields an unbacked manager."""+ workspace = EmptyWorkspace()+ manager = workspace.load(NEW_FILE)+ assert manager.filename is None++ def test_empty_workspace_load_with_nonexistent_path_404s(self):+ """Concrete keys that don't exist on disk must 404."""+ workspace = EmptyWorkspace()+ with pytest.raises(HTTPException) as exc:+ workspace.load("/this/path/does/not/exist.py")+ assert exc.value.status_code == HTTPStatus.NOT_FOUND++ def test_empty_workspace_resolve_returns_absolute_normalized(self):+ """``resolve`` must return an absolute, normalized path so downstream+ lookups (session keys, comparisons) don't mismatch between relative+ and absolute spellings of the same file.+ """+ original_cwd = os.getcwd()+ try:+ os.chdir(self.test_dir)+ relative_key = os.path.basename(self.test_file1.name)+ workspace = EmptyWorkspace()+ resolved = workspace.resolve(relative_key)+ assert resolved is not None+ assert os.path.isabs(resolved)+ assert os.path.samefile(resolved, self.test_file1.name)+ finally:+ os.chdir(original_cwd)++ def test_empty_workspace_load_with_existing_path_falls_back(self):+ """``marimo new`` boots an EmptyWorkspace; opening a recent file must+ still work via the unconditional existence fallback.++ This is intentionally permissive — there's no allowlist, since the+ boot mode has no concept of one. Threat model: anyone able to hit+ ``marimo new``'s endpoint already has the same trust level as the+ process owner.+ """+ workspace = EmptyWorkspace()+ manager = workspace.load(self.test_file1.name)+ assert manager.filename == self.test_file1.name+def test_flatten_files() -> None:root = FileInfo(@@ -591,7 +713,7 @@ def test_error_path_returns_false_and_logs(tmp_path: Path):def test_lazy_router_respects_max_files(tmp_path: Path):- """Test that LazyListOfFilesAppFileRouter enforces MAX_FILES limit"""+ """Test that DirectoryWorkspace enforces MAX_FILES limit"""# Create a directory with more files than MAX_FILES# To make this test fast, we'll use a monkey-patch approach# by temporarily reducing MAX_FILES@@ -607,9 +729,7 @@ def test_lazy_router_respects_max_files(tmp_path: Path):f = tmp_path / f"app_{i}.py"f.write_text("import marimo\napp = marimo.App()\n")- router = LazyListOfFilesAppFileRouter(- str(tmp_path), include_markdown=False- )+ router = DirectoryWorkspace(str(tmp_path), include_markdown=False)files = router.files# Should only get MAX_FILES worth of files@@ -623,7 +743,7 @@ def test_lazy_router_respects_max_files(tmp_path: Path):def test_lazy_router_skips_common_dirs(tmp_path: Path):- """Test that LazyListOfFilesAppFileRouter skips common directories"""+ """Test that DirectoryWorkspace skips common directories"""# Create directories that should be skippedskip_dirs = [".venv",@@ -645,9 +765,7 @@ def test_lazy_router_skips_common_dirs(tmp_path: Path):root_file = tmp_path / "root_app.py"root_file.write_text("import marimo\napp = marimo.App()\n")- router = LazyListOfFilesAppFileRouter(- str(tmp_path), include_markdown=False- )+ router = DirectoryWorkspace(str(tmp_path), include_markdown=False)files = router.files# Should only find the root file, not files in skipped directories@@ -670,9 +788,7 @@ def test_lazy_router_counts_nested_files(tmp_path: Path):nested_file = nested_dir / "nested.py"nested_file.write_text("import marimo\napp = marimo.App()\n")- router = LazyListOfFilesAppFileRouter(- str(tmp_path), include_markdown=False- )+ router = DirectoryWorkspace(str(tmp_path), include_markdown=False)files = router.filestotal_files = count_files(files)@@ -698,13 +814,11 @@ def test_lazy_router_allows_temp_dir_files(tmp_path: Path):temp_file.write_text("import marimo\napp = marimo.App()\n")# Create router for base directory- router = LazyListOfFilesAppFileRouter(- str(base_dir), include_markdown=False- )+ router = DirectoryWorkspace(str(base_dir), include_markdown=False)# Without registering temp dir, accessing temp file should failwith pytest.raises(HTTPException) as exc_info:- router.get_file_manager(str(temp_file))+ router.load(str(temp_file))assert exc_info.value.status_code == HTTPStatus.FORBIDDENassert "outside the allowed directory" in exc_info.value.detail@@ -712,7 +826,7 @@ def test_lazy_router_allows_temp_dir_files(tmp_path: Path):router.register_temp_dir(str(temp_dir))# Now accessing the temp file should succeed- manager = router.get_file_manager(str(temp_file))+ manager = router.load(str(temp_file))assert manager is not Noneassert manager.path == str(temp_file)@@ -738,21 +852,19 @@ def test_lazy_router_temp_dir_doesnt_affect_normal_files(other_temp_dir.mkdir()# Create router- router = LazyListOfFilesAppFileRouter(- str(base_dir), include_markdown=False- )+ router = DirectoryWorkspace(str(base_dir), include_markdown=False)# Register a different temp directory (not containing our outside_file)router.register_temp_dir(str(other_temp_dir))# Base file should still be accessible- manager = router.get_file_manager(str(base_file))+ manager = router.load(str(base_file))assert manager is not Noneassert manager.path == str(base_file)# Outside file should still be blocked (not in registered temp dir)with pytest.raises(HTTPException) as exc_info:- router.get_file_manager(str(outside_file))+ router.load(str(outside_file))assert exc_info.value.status_code == HTTPStatus.FORBIDDEN@@ -783,8 +895,6 @@ def test_lazy_router_symlink_directory_outside_allowed(tmp_path: Path):# Symlinks are preserved (not resolved), so the path# base_dir/shared/outside.py is inside base_dir- router = LazyListOfFilesAppFileRouter(- str(base_dir), include_markdown=False- )- manager = router.get_file_manager(str(file_through_symlink))+ router = DirectoryWorkspace(str(base_dir), include_markdown=False)+ manager = router.load(str(file_through_symlink))assert manager is not None