perf: skip contended retention housekeeping

[codeforester]

Retention now acquires its maintenance lock without waiting on both POSIX and Windows. Contending invocations skip the pass; subsequent successful passes enforce the existing bounds. Teardown acquires the lock before scanning, and lock cleanup never unlocks an unacquired lock.

Fixes #386.

Branch maintenance

Refs #426. Targets the branch for #417. Retarget and refresh after that parent is squash-merged; preserve the ordered stack.

The branch was refreshed without rewriting history to include main at a576cc279739eae5e4cfc33ffab2a7fb56de24de.

Current-head validation

At c4af745a971534dd8ccb13fe51da250ece0d36d7: uv lock freshness and baseline, runtime, strict typing, style, and contracts passed locally with all declared extras. Runtime result: 621 passed, 1 warning, 262 subtests passed in 8.67s.

Hosted checks: 7/7 required checks passed; 0 checks pending; 0 unsuccessful checks at 2026-10-04T14:19:40.760978+00:00. See the PR Checks tab and #426 for subsequent results.

[codeforester]

Reviewed against #386's acceptance criteria. Switching to a non-blocking lock with skip-on-contention is the right fix. Moving _discover_run_bundles under the lock in refresh_run_bundle_index is a good catch, and the locked flag avoids unlocking a lock we never took. CI is green.

Acceptance gap: #386 requires "a test that runs N invocations past the cap asserts the bound is eventually enforced even though individual passes are skipped." This PR has no such test. test_contended_retention_returns_without_waiting only proves the probe doesn't hang, and it runs against an empty root. The concurrency benchmark gate lives in #422, which is stacked on this PR, so that criterion is satisfied only when the stack lands together.

[codeforester]

Re-verified at 2f96072: both threads addressed ✅. 311c280 adds the multi-process convergence test that #386 required (8 passes past the cap, then a serial pass asserting the bound), and refresh_run_bundle_index now treats BlockingIOError as an expected skip instead of a refresh failure. Full suite passes at the tip. The threads can be resolved.

[codeforester]

Resolved the merge conflicts by merging current (including #417) into this branch in commit .\n\nResolution preserves:\n- #386 concurrent-retention documentation and behavior\n- current #416 logging sidecar recovery\n- both branches' logging hot-path coverage, including deleted-sidecar reopening\n\nLocal validation passed:\n- full pytest suite\n- targeted retention/logging suites (37 tests)\n- Ruff check and format\n- strict mypy\n- documentation validation\n\nThe PR remains open and unmerged. GitHub checks are running on the new head.

[codeforester]

Resolved the merge conflicts by merging current main (including #417) into this branch in commit b8feb66. Preserved the #386 concurrent-retention documentation and behavior, current #416 logging sidecar recovery, and both branches logging hot-path coverage including deleted-sidecar reopening. Local validation passed: full pytest, targeted retention/logging tests (37), Ruff check and format, strict mypy, and documentation validation. The PR remains open and unmerged; GitHub checks are running on the new head.