[gauravch-code]

Description

A session retired after a blocked request could become usable again, because mark_good() lowered its error score below the limit. Retirement is now tracked separately from the error score and is permanent, including after the session pool is saved and restored. The behavior matches Crawlee JS v4.

• Session keeps a retired flag, exposed as the Session.retired property and saved in SessionModel. Saved state without the field loads with retired=False.
• is_usable checks the flag. is_blocked still depends only on the error score.
• mark_good() does nothing on a retired session, so its error score and usage count stay as they are.
• retire() adds max_error_score to the error score once. Calling it on a session that is already retired changes nothing.
• When mark_good() or mark_bad() finds a session expired, at its usage limit, or at its error score limit, it only sets the flag and adds no extra max_error_score.
• The v2 upgrade guide has a new "Session retirement is permanent" section, and the standalone session management example calls retire() last.

Issues

Closes: #2312

Testing

• New unit tests cover permanent retirement, mark_good() on a retired session, repeated retire() calls, automatic retirement at each limit, JSON round trips, loading older saved state, pool lookups, and saving and reopening the pool.
• tests/unit/sessions and tests/unit/crawlers/_basic: 211 passed, 1 existing skip.
• ruff check, ruff format --check and ty check pass.

[vdusek]

Two minor things

[vdusek]

A three more comments, regarding comparision with Crawlee JS

[gauravch-code]

Thanks for the careful review, @vdusek! I addressed the five comments in 261dab6:

• Retirement is checked in is_usable; is_blocked depends only on the error score.
• Automatic retirement sets only the retired flag, without adding a blocking penalty.
• mark_good returns immediately for retired sessions, preserving both score and usage count.
• Added the public retired property and regression coverage for expiration, usage limits, error limits, and restored retired state.
• Moved the migration section to the end and changed the legacy-state test to delete the retired field explicitly.

All 49 session tests, full repository lint, and the migration Markdown lint pass. The full type check passes targeting Linux; native Windows reports three unrelated multiprocessing fork-type errors in tests/unit/_utils/test_system.py. Both commit hooks passed using an external Linux-targeted type configuration with the same repository rules.

Happy to adjust anything further. Thanks again!

CI note: the new factory-review approval lookup failed because GitHub returned HTTP 502, while the AI review job passed. GitHub requires repository admin rights to rerun the failed job, so I could not retry it from my fork. Could you rerun that lookup when you have a chance?

[vdusek]

LGTM