Skip to content

Python: fix(sessions): quarantine corrupt snapshots under a bounded file name - #10372

Open
Simin Yuan (simin-yuan) wants to merge 4 commits into
microsoft:mainfrom
simin-yuan:fix/session-quarantine-bounded-name
Open

Simin Yuan (simin-yuan) wants to merge 4 commits into
microsoft:mainfrom
simin-yuan:fix/session-quarantine-bounded-name

Conversation

@simin-yuan

@simin-yuan Simin Yuan (simin-yuan) commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Motivation & Context

FileSessionStore could not quarantine a corrupt snapshot whose own path already sits near the legacy Windows MAX_PATH limit. _quarantine_corrupt_snapshot named the destination .<full snapshot name>.<uuid>.corrupt, roughly 40 characters longer than the snapshot, so os.replace failed with WinError 3 and the corrupt file stayed in place. Every later get() failed the same way, leaving that session unreadable until someone removed the file by hand.

Reported in #9885, which was closed pending native Windows confirmation. The native reproduction is in #9885 (comment) (Windows 11 22631, LongPathsEnabled=0, CPython 3.11.15):

snapshot path 253 chars (under 260, written fine) -> quarantine dest 295 chars
get(): ValueError, cause FileNotFoundError winerror=3 (ERROR_PATH_NOT_FOUND)
corrupt snapshot remains: True, quarantine file created: False

Description & Review Guide

  • What are the major changes? _quarantine_corrupt_snapshot now names the destination .<uuid hex>.corrupt: a fixed 41-character name that no longer embeds the snapshot name. For a one-character session id the name this code produced before the change was 48 characters, so every destination that used to fit still fits, and roots where the embedded name overflowed now work. The quarantine file is internal recovery storage that callers never address by name, so nothing depends on the old name.
  • Attribution: because the bounded name drops the session id, quarantine logs a warning that carries both the original snapshot path and the quarantine path, so a file found later can still be traced to its session (test_corrupt_quarantine_logs_the_snapshot_path).
  • What is the impact of these changes? Corrupt snapshots near the legacy Windows limit are now moved aside and the documented "quarantined, retry" recovery path works. Snapshots that could already be quarantined keep behaving identically apart from the quarantine file's name and the added warning. No API change.
  • What do you want reviewers to focus on? The name shape: a bare .<uuid>.corrupt versus keeping a .maf- prefix like the sibling .maf-state- / .maf-ckpt- files. The prefix costs 4 characters and still fits every case below, so it is a preference rather than a correctness question. Coverage: test_corrupt_quarantine_name_does_not_grow_with_the_session_id, test_corrupt_quarantine_survives_legacy_windows_max_path (253-character snapshot against a simulated 260-character rename limit, so it runs on every platform) and test_corrupt_quarantine_short_id_at_deep_root_does_not_regress (one-character id under a 206-character root, which is the case raised in review).

Testing

Related Issue

Fixes #9885 (reproduction and native confirmation in the thread).

AI Assistance

  • No material AI assistance was used.
  • This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance details: implementation, tests and this description were drafted with an AI coding tool. The reproduction, mutation check, test runs and lint above were executed locally on the machine described in the issue thread, and I verified each change against the source.

A full pytest -m "not integration" -n auto --dist worksteal run on Windows shows the same seven failures before and after the change (two aiohttp-dependent function-invocation cases, two telemetry package-presence checks, the #9682 write-path case, two openai-pickle cases), so the change introduces no new failures.

Contribution Checklist

  • The code builds clean without any errors or warnings
  • All unit tests pass, and I have added new tests where possible

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-<uuid>.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.
Copilot AI balanced review requested due to automatic review settings November 15, 2026 10:48
@agent-framework-automation agent-framework-automation Bot added the python Usage: [Issues, PRs], Target: Python label Nov 15, 2026
@github-actions github-actions Bot changed the title fix(sessions): quarantine corrupt snapshots under a bounded file name Python: fix(sessions): quarantine corrupt snapshots under a bounded file name Nov 15, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The longer quarantine path can break renaming on legacy Windows and leave corrupt snapshots in place, while the regression test fails under valid longer temporary roots.

2 open issues
What changed in this PR

This PR addresses #9885 by giving Python’s FileSessionStore a bounded quarantine filename, enabling recovery of corrupt long-ID snapshots near the legacy Windows path limit.

Changes:

  • Replaces snapshot-derived quarantine names with .maf-session-<uuid hex>.corrupt.
  • Adds regression tests for bounded filename length and quarantine under a simulated Windows path limit.
  • Leaves the public API and write-time temporary naming unchanged; the latter is handled separately by #9739.
File Description
python/​packages/​core/​tests/​core/​test_sessions.py Adds quarantine filename and simulated path-limit regression tests.
python/​packages/​core/​agent_framework/​_sessions.py Makes quarantine filenames independent of session ID length.

Review effort: Balanced

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")

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adopted. The quarantine destination is now .<uuid hex>.corrupt (41 characters) instead of .maf-<uuid hex>.corrupt (45), and the new test's glob and length bound follow it.

The short-id/deep-root case you described is covered by test_corrupt_quarantine_short_id_at_deep_root_does_not_regress: a one-character session id under a 206-character root with os.replace capped at 260 characters. With the original .maf-session-<uuid>.corrupt name the destination came out at 260 and the rename failed; it now lands at 248 and succeeds.

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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed. Both boundary tests now skip instead of failing when the pytest temporary root leaves too little room: test_corrupt_quarantine_survives_legacy_windows_max_path skips when padding <= 0, and the 206-character-root test skips when padding <= 1.

Checked on a machine with a long temporary root, which is the case you described: the two MAX_PATH tests still run there, and with a short --basetemp the whole file is green (198 passed).

…-root case

The .maf-session-<uuid>.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-<uuid>.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.
@simin-yuan

Copy link
Copy Markdown
Contributor Author

Addressed both review points in 34c12ff:

  • The bounded name is now .maf-<uuid>.corrupt (45 characters) instead of .maf-session-<uuid>.corrupt (54). The name it replaces was at least 48 characters (.<stem>.json.<uuid>.corrupt for a one-character id), so the new name is always shorter and cannot turn a working quarantine into a failing one.
  • Added test_corrupt_quarantine_short_id_at_deep_root_does_not_regress: a one-character session id under a 206-character root must still quarantine within the simulated 260-character limit. It fails with the 54-character name and passes with the 45-character one.
  • The near-MAX_PATH test now skips when the pytest temporary root leaves no room for the 253-character case instead of asserting a non-negative padding.

Re-verified natively on the same Windows box (LongPathsEnabled=0): at a 253-character snapshot path the corrupt file is moved to .maf-<uuid>.corrupt and the session recovers. pytest tests/core/test_sessions.py is clean apart from the known #9682 write-path case, and ruff format/check are clean.

@surlymochan Nick (surlymochan) left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-binding review (read the diff; not an approval).

What I verified:

  • The fix is a one-line change: the quarantine destination no longer embeds the snapshot file name, so its length is bounded at .maf-<32 hex>.corrupt = 45 characters. The first new test's <= 48 bound holds, and the third test's regression bound (previous 48-character name for a one-character session id) also holds since 45 < 48.
  • The two MAX_PATH simulation tests pin the reported failure precisely: with the snapshot name embedded, the destination is ~295 characters and the rename raises; with the bounded name it fits.

One question:

  • The old quarantine name carried the session id, so an operator finding a .maf-*.corrupt file could tell which session it came from. The new name drops that. Is the original session/file name logged anywhere at quarantine time? If not, consider logging it (or keeping the session id in the quarantine record) so a quarantined file stays attributable.

…shot

The bounded quarantine name no longer carries the session id, so an operator
finding a .maf-<uuid>.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 microsoft#10372)
@simin-yuan

Copy link
Copy Markdown
Contributor Author

Good catch on attribution — that is a real loss of operator information. Fixed in d22589a: _quarantine_corrupt_snapshot now logs a warning with the snapshot path and the quarantine destination before returning:

Session snapshot <...>/<session file>.json was corrupt; moved it aside to <...>/.maf-<uuid>.corrupt so the session can be created again.

That mirrors the memory store, which already warns with both paths when it quarantines a state file. The exception the caller sees still carries both paths too, so the log is a durable record rather than the only one. Added test_corrupt_quarantine_logs_the_snapshot_path (asserts the warning names the snapshot file); it fails without the log line, and ruff is clean again after combining the nested with blocks the linter flagged.

The quarantine destination is now '.<uuid hex>.corrupt' (41 characters)
instead of '.maf-<uuid hex>.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.
@simin-yuan

Simin Yuan (simin-yuan) commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor Author

Nick (@surlymochan) one further change since the reply above, so the log line stays accurate: the destination is now .<uuid hex>.corrupt (41 characters) instead of .maf-<uuid hex>.corrupt, following the other review thread. The warning still carries the original snapshot path and the quarantine path, so a quarantined file stays traceable to its session.

That reply also offered the trade-off: the log keeps recovery a single rename, while a metadata sidecar next to the file would be a second write that can itself fail mid-recovery. If you would rather have the durable record on disk, tell me and I will add it.

This branch was successfully deployed

1 active deployment
github-app-auth — b1bc614a Deployed Nov 15, 2026 by simin-yuan via add_label #27893
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

python Usage: [Issues, PRs], Target: Python

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Python: [Bug]: FileSessionStore cannot quarantine corrupt snapshots near Windows MAX_PATH

3 participants