From cd5c576b87e5832f6bd5901f5528c7af271dbb1d Mon Sep 17 00:00:00 2001 From: Simin Yuan <281164480+simin-yuan@users.noreply.github.com> Date: Sun, 15 Nov 2026 18:46:48 +0800 Subject: [PATCH 1/4] fix(sessions): quarantine corrupt snapshots under a bounded file name The quarantine destination embedded the snapshot name, so a 128-character session id near the legacy Windows MAX_PATH limit produced a rename target ~40 characters longer than the snapshot itself: os.replace failed with WinError 3 and the corrupt file stayed in place, leaving the session permanently unreadable. Name the destination .maf-session-.corrupt, the way the write path is heading (and like the .maf-state/.maf-ckpt siblings), and cover both the bounded name and a simulated 260-character rename limit. --- .../core/agent_framework/_sessions.py | 2 +- .../packages/core/tests/core/test_sessions.py | 57 +++++++++++++++++++ 2 files changed, 58 insertions(+), 1 deletion(-) diff --git a/python/packages/core/agent_framework/_sessions.py b/python/packages/core/agent_framework/_sessions.py index 1e43f0ca1d9..a586c4a68bc 100644 --- a/python/packages/core/agent_framework/_sessions.py +++ b/python/packages/core/agent_framework/_sessions.py @@ -2465,7 +2465,7 @@ def _quarantine_corrupt_snapshot(file_path: Path, serialized: bytes) -> Path | N return None if current_serialized != serialized: return None - quarantine_path = file_path.with_name(f".{file_path.name}.{uuid.uuid4().hex}.corrupt") + quarantine_path = file_path.with_name(f".maf-session-{uuid.uuid4().hex}.corrupt") os.replace(file_path, quarantine_path) return quarantine_path diff --git a/python/packages/core/tests/core/test_sessions.py b/python/packages/core/tests/core/test_sessions.py index 6ffdbb36511..4c9c91c9cd3 100644 --- a/python/packages/core/tests/core/test_sessions.py +++ b/python/packages/core/tests/core/test_sessions.py @@ -1361,6 +1361,63 @@ async def test_corrupt_session_file_is_quarantined_and_retry_returns_none(self, assert len(quarantined_files) == 1 assert await store.get("session-1") is None + async def test_corrupt_quarantine_name_does_not_grow_with_the_session_id(self, tmp_path: Path) -> None: + """The quarantine destination must not embed the snapshot name. + + On Windows with legacy MAX_PATH handling, a 128-character session id already puts the + snapshot near the limit; adding the full snapshot name plus a UUID to the quarantine + destination makes the rename fail and leaves the corrupt file in place (#9885). + """ + store = FileSessionStore(tmp_path) + session_id = "x" * FileSessionStore.MAX_SESSION_ID_LENGTH + session_file = store._session_file_path(session_id) + await asyncio.to_thread(session_file.write_bytes, b"not-json") + + with pytest.raises(ValueError, match="quarantined.*retry"): + await store.get(session_id) + + assert not session_file.exists() + quarantined_files = await asyncio.to_thread(lambda: list(tmp_path.glob(".maf-session-*.corrupt"))) + assert len(quarantined_files) == 1 + assert len(quarantined_files[0].name) <= 64 + + async def test_corrupt_quarantine_survives_legacy_windows_max_path( + self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch + ) -> None: + """A 253-character snapshot path must still be quarantined when rename is capped at 260. + + Simulates the Windows legacy limit on the destination of ``os.replace`` so the case runs + on every platform; with the snapshot name embedded in the quarantine name the destination + is ~295 characters and the rename raises, which is the reported failure. + """ + store = FileSessionStore(tmp_path) + session_id = "x" * FileSessionStore.MAX_SESSION_ID_LENGTH + sample_path = store._session_file_path(session_id) + padding = 252 - len(str(tmp_path)) - 1 - len(sample_path.name) + assert padding > 0 + deep_root = tmp_path / ("d" * padding) + deep_root.mkdir() + deep_store = FileSessionStore(deep_root) + session_file = deep_store._session_file_path(session_id) + assert len(str(session_file)) == 253 + await asyncio.to_thread(session_file.write_bytes, b"not-json") + + real_replace = os.replace + + def limited_replace(src: str | os.PathLike[str], dst: str | os.PathLike[str]) -> None: + if len(str(dst)) >= 260: + raise FileNotFoundError(3, "The system cannot find the path specified", str(dst)) + real_replace(src, dst) + + monkeypatch.setattr(os, "replace", limited_replace) + + with pytest.raises(ValueError, match="quarantined.*retry"): + await deep_store.get(session_id) + + assert not session_file.exists() + quarantined_files = await asyncio.to_thread(lambda: list(deep_root.glob(".maf-session-*.corrupt"))) + assert len(quarantined_files) == 1 + async def test_invalid_registered_payload_preserves_snapshot(self, tmp_path: Path) -> None: store = FileSessionStore(tmp_path) session_file = store._session_file_path("session-1") From 34c12ff2cdf6124fb77b96a2946270e95d7ee1a0 Mon Sep 17 00:00:00 2001 From: Simin Yuan <281164480+simin-yuan@users.noreply.github.com> Date: Sun, 15 Nov 2026 19:10:58 +0800 Subject: [PATCH 2/4] fix(sessions): shorten the bounded quarantine name and guard the deep-root case The .maf-session-.corrupt name was 54 characters, longer than the 48-character minimum of the name it replaced, so a one-character session id at a deep root could regress from a working quarantine to a failed rename. Use .maf-.corrupt (45 characters) instead, add a short-id/deep-root regression case that fails with the longer name, and skip the near-MAX_PATH test when the pytest root leaves no room. --- .../core/agent_framework/_sessions.py | 2 +- .../packages/core/tests/core/test_sessions.py | 45 +++++++++++++++++-- 2 files changed, 42 insertions(+), 5 deletions(-) diff --git a/python/packages/core/agent_framework/_sessions.py b/python/packages/core/agent_framework/_sessions.py index a586c4a68bc..80703ee2eb4 100644 --- a/python/packages/core/agent_framework/_sessions.py +++ b/python/packages/core/agent_framework/_sessions.py @@ -2465,7 +2465,7 @@ def _quarantine_corrupt_snapshot(file_path: Path, serialized: bytes) -> Path | N return None if current_serialized != serialized: return None - quarantine_path = file_path.with_name(f".maf-session-{uuid.uuid4().hex}.corrupt") + quarantine_path = file_path.with_name(f".maf-{uuid.uuid4().hex}.corrupt") os.replace(file_path, quarantine_path) return quarantine_path diff --git a/python/packages/core/tests/core/test_sessions.py b/python/packages/core/tests/core/test_sessions.py index 4c9c91c9cd3..25f9fc79610 100644 --- a/python/packages/core/tests/core/test_sessions.py +++ b/python/packages/core/tests/core/test_sessions.py @@ -1377,9 +1377,9 @@ async def test_corrupt_quarantine_name_does_not_grow_with_the_session_id(self, t await store.get(session_id) assert not session_file.exists() - quarantined_files = await asyncio.to_thread(lambda: list(tmp_path.glob(".maf-session-*.corrupt"))) + quarantined_files = await asyncio.to_thread(lambda: list(tmp_path.glob(".maf-*.corrupt"))) assert len(quarantined_files) == 1 - assert len(quarantined_files[0].name) <= 64 + assert len(quarantined_files[0].name) <= 48 async def test_corrupt_quarantine_survives_legacy_windows_max_path( self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch @@ -1394,7 +1394,8 @@ async def test_corrupt_quarantine_survives_legacy_windows_max_path( session_id = "x" * FileSessionStore.MAX_SESSION_ID_LENGTH sample_path = store._session_file_path(session_id) padding = 252 - len(str(tmp_path)) - 1 - len(sample_path.name) - assert padding > 0 + if padding <= 0: + pytest.skip("pytest temporary root is too long to build a near-MAX_PATH case") deep_root = tmp_path / ("d" * padding) deep_root.mkdir() deep_store = FileSessionStore(deep_root) @@ -1415,9 +1416,45 @@ def limited_replace(src: str | os.PathLike[str], dst: str | os.PathLike[str]) -> await deep_store.get(session_id) assert not session_file.exists() - quarantined_files = await asyncio.to_thread(lambda: list(deep_root.glob(".maf-session-*.corrupt"))) + quarantined_files = await asyncio.to_thread(lambda: list(deep_root.glob(".maf-*.corrupt"))) assert len(quarantined_files) == 1 + async def test_corrupt_quarantine_short_id_at_deep_root_does_not_regress( + self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch + ) -> None: + """A short session id at a deep root must keep the quarantine path it had before. + + The previous destination embedded the snapshot name, so for a one-character id it was 48 + characters long. The bounded name must not be longer than that, otherwise a root where the + quarantine used to fit would start failing. + """ + padding = 206 - len(str(tmp_path)) - 1 + if padding <= 1: + pytest.skip("pytest temporary root is too long to build the 206-character root") + deep_root = tmp_path / ("d" * padding) + deep_root.mkdir() + assert len(str(deep_root)) == 206 + store = FileSessionStore(deep_root) + session_file = store._session_file_path("x") + await asyncio.to_thread(session_file.write_bytes, b"not-json") + + real_replace = os.replace + + def limited_replace(src: str | os.PathLike[str], dst: str | os.PathLike[str]) -> None: + if len(str(dst)) >= 260: + raise FileNotFoundError(3, "The system cannot find the path specified", str(dst)) + real_replace(src, dst) + + monkeypatch.setattr(os, "replace", limited_replace) + + with pytest.raises(ValueError, match="quarantined.*retry"): + await store.get("x") + + assert not session_file.exists() + quarantined_files = await asyncio.to_thread(lambda: list(deep_root.glob(".maf-*.corrupt"))) + assert len(quarantined_files) == 1 + assert len(str(quarantined_files[0])) < 260 + async def test_invalid_registered_payload_preserves_snapshot(self, tmp_path: Path) -> None: store = FileSessionStore(tmp_path) session_file = store._session_file_path("session-1") From d22589a8ac340851244bb7faca6a00cb68056804 Mon Sep 17 00:00:00 2001 From: Simin Yuan <281164480+simin-yuan@users.noreply.github.com> Date: Sun, 15 Nov 2026 20:53:55 +0800 Subject: [PATCH 3/4] fix(sessions): log the snapshot path when quarantining a corrupt snapshot The bounded quarantine name no longer carries the session id, so an operator finding a .maf-.corrupt file could not tell which session it came from. Log the snapshot path (which carries the session-derived file name) alongside the quarantine destination, mirroring the memory store's quarantine warning. Reviewed-by: surlymochan (non-binding review on PR #10372) --- .../core/agent_framework/_sessions.py | 7 +++++++ .../packages/core/tests/core/test_sessions.py | 20 +++++++++++++++++++ 2 files changed, 27 insertions(+) diff --git a/python/packages/core/agent_framework/_sessions.py b/python/packages/core/agent_framework/_sessions.py index 80703ee2eb4..a0ba7cea57a 100644 --- a/python/packages/core/agent_framework/_sessions.py +++ b/python/packages/core/agent_framework/_sessions.py @@ -2467,6 +2467,13 @@ def _quarantine_corrupt_snapshot(file_path: Path, serialized: bytes) -> Path | N return None quarantine_path = file_path.with_name(f".maf-{uuid.uuid4().hex}.corrupt") os.replace(file_path, quarantine_path) + # The bounded name no longer carries the session id, so log the snapshot path here: the + # quarantine file is otherwise unattributable to the session it came from. + logger.warning( + "Session snapshot %s was corrupt; moved it aside to %s so the session can be created again.", + file_path, + quarantine_path, + ) return quarantine_path @classmethod diff --git a/python/packages/core/tests/core/test_sessions.py b/python/packages/core/tests/core/test_sessions.py index 25f9fc79610..0246c3f5a19 100644 --- a/python/packages/core/tests/core/test_sessions.py +++ b/python/packages/core/tests/core/test_sessions.py @@ -2,6 +2,7 @@ import asyncio import json +import logging import math import os import threading @@ -1381,6 +1382,25 @@ async def test_corrupt_quarantine_name_does_not_grow_with_the_session_id(self, t assert len(quarantined_files) == 1 assert len(quarantined_files[0].name) <= 48 + async def test_corrupt_quarantine_logs_the_snapshot_path( + self, tmp_path: Path, caplog: pytest.LogCaptureFixture + ) -> None: + """The bounded quarantine name drops the session id, so the warning must keep it attributable.""" + store = FileSessionStore(tmp_path) + session_file = store._session_file_path("session-1") + await asyncio.to_thread(session_file.write_bytes, b"not-json") + + with ( + caplog.at_level(logging.WARNING, logger="agent_framework"), + pytest.raises(ValueError, match="quarantined.*retry"), + ): + await store.get("session-1") + + messages = [record.getMessage() for record in caplog.records] + assert any( + session_file.name in message and ".maf-" in message and ".corrupt" in message for message in messages + ), messages + async def test_corrupt_quarantine_survives_legacy_windows_max_path( self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch ) -> None: From b1bc614a81529cc6a238a9b5824688469c72e472 Mon Sep 17 00:00:00 2001 From: Simin Yuan <281164480+simin-yuan@users.noreply.github.com> Date: Sun, 15 Nov 2026 21:00:43 +0800 Subject: [PATCH 4/4] fix(sessions): use a bare UUID name for quarantined snapshots The quarantine destination is now '..corrupt' (41 characters) instead of '.maf-.corrupt' (45), matching the name suggested in review and leaving more headroom under the legacy Windows MAX_PATH limit. Test globs and the length bound follow the new name. --- .../packages/core/agent_framework/_sessions.py | 2 +- python/packages/core/tests/core/test_sessions.py | 16 +++++++--------- 2 files changed, 8 insertions(+), 10 deletions(-) diff --git a/python/packages/core/agent_framework/_sessions.py b/python/packages/core/agent_framework/_sessions.py index a0ba7cea57a..14217892811 100644 --- a/python/packages/core/agent_framework/_sessions.py +++ b/python/packages/core/agent_framework/_sessions.py @@ -2465,7 +2465,7 @@ def _quarantine_corrupt_snapshot(file_path: Path, serialized: bytes) -> Path | N return None if current_serialized != serialized: return None - quarantine_path = file_path.with_name(f".maf-{uuid.uuid4().hex}.corrupt") + quarantine_path = file_path.with_name(f".{uuid.uuid4().hex}.corrupt") os.replace(file_path, quarantine_path) # The bounded name no longer carries the session id, so log the snapshot path here: the # quarantine file is otherwise unattributable to the session it came from. diff --git a/python/packages/core/tests/core/test_sessions.py b/python/packages/core/tests/core/test_sessions.py index 0246c3f5a19..60b8eff9504 100644 --- a/python/packages/core/tests/core/test_sessions.py +++ b/python/packages/core/tests/core/test_sessions.py @@ -1378,9 +1378,9 @@ async def test_corrupt_quarantine_name_does_not_grow_with_the_session_id(self, t await store.get(session_id) assert not session_file.exists() - quarantined_files = await asyncio.to_thread(lambda: list(tmp_path.glob(".maf-*.corrupt"))) + quarantined_files = await asyncio.to_thread(lambda: list(tmp_path.glob(".*.corrupt"))) assert len(quarantined_files) == 1 - assert len(quarantined_files[0].name) <= 48 + assert len(quarantined_files[0].name) <= 41 # "." + 32 hex chars + ".corrupt" async def test_corrupt_quarantine_logs_the_snapshot_path( self, tmp_path: Path, caplog: pytest.LogCaptureFixture @@ -1397,9 +1397,7 @@ async def test_corrupt_quarantine_logs_the_snapshot_path( await store.get("session-1") messages = [record.getMessage() for record in caplog.records] - assert any( - session_file.name in message and ".maf-" in message and ".corrupt" in message for message in messages - ), messages + assert any(session_file.name in message and ".corrupt" in message for message in messages), messages async def test_corrupt_quarantine_survives_legacy_windows_max_path( self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch @@ -1436,7 +1434,7 @@ def limited_replace(src: str | os.PathLike[str], dst: str | os.PathLike[str]) -> await deep_store.get(session_id) assert not session_file.exists() - quarantined_files = await asyncio.to_thread(lambda: list(deep_root.glob(".maf-*.corrupt"))) + quarantined_files = await asyncio.to_thread(lambda: list(deep_root.glob(".*.corrupt"))) assert len(quarantined_files) == 1 async def test_corrupt_quarantine_short_id_at_deep_root_does_not_regress( @@ -1445,8 +1443,8 @@ async def test_corrupt_quarantine_short_id_at_deep_root_does_not_regress( """A short session id at a deep root must keep the quarantine path it had before. The previous destination embedded the snapshot name, so for a one-character id it was 48 - characters long. The bounded name must not be longer than that, otherwise a root where the - quarantine used to fit would start failing. + characters long. The bounded name is 41 characters, so a root where the quarantine used to + fit keeps fitting. """ padding = 206 - len(str(tmp_path)) - 1 if padding <= 1: @@ -1471,7 +1469,7 @@ def limited_replace(src: str | os.PathLike[str], dst: str | os.PathLike[str]) -> await store.get("x") assert not session_file.exists() - quarantined_files = await asyncio.to_thread(lambda: list(deep_root.glob(".maf-*.corrupt"))) + quarantined_files = await asyncio.to_thread(lambda: list(deep_root.glob(".*.corrupt"))) assert len(quarantined_files) == 1 assert len(str(quarantined_files[0])) < 260