fix(libsy): preserve plan-execute sessions at capacity

[ryan-lempka]

What

Keep active Plan/Execute sessions on the efficient model. At the 4,096-session limit, new handoffs return a capacity error (HTTP 500). Marking an existing session with session_final: true frees a slot so the handoff can be retried.

Why

Adding a new session used to remove an existing session from memory. If compaction had removed its edit history, that session would restart planning.

Notes for reviewers

Final requests still work at capacity. Added regression tests and documented the limit.

All 339 library tests passed, along with formatting, workspace Clippy, and the strict docs build. No live provider calls were made.

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://NVIDIA-NeMo.github.io/Switchyard/pr-preview/pr-921/
Built to branch gh-pages at 2026-10-06 17:33 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: NVIDIA-NeMo/Switchyard/.coderabbit.yaml
• Review profile: CHILL
• Plan: Enterprise
• Run ID: becd2553-358f-44f9-ae65-0e460ed17c6e

📥 Commits

Reviewing files that changed from the base of the PR and between b9e7ccc and fa3ebb4.

📒 Files selected for processing (2)

• crates/libsy/src/algorithms/plan_execute.rs
• docs/routing_algorithms/plan_execute_routing.md

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 11 remain after this review.

---

Walkthrough

The router retains up to 4,096 identified executing sessions. It rejects a new mutation handoff at capacity without evicting an existing session. Final requests release existing session slots, and final handoffs do not consume a slot.

Changes

Session capacity handling

Layer / File(s)

Summary

Capacity-aware routing and validation crates/libsy/src/algorithms/plan_execute.rs, docs/routing_algorithms/plan_execute_routing.md

The phase logic rejects new identified-session mutation handoffs when all 4,096 slots are occupied, while preserving existing execution latches. Final requests remove existing latches, and final handoffs do not consume a slot. Routing propagates phase errors. Tests cover overflow, slot release, compaction, and final handoffs. The documentation describes identity keys, capacity, release behavior, and the final-request header.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~15 minutes

Merge Risk: ⚪ Minimal · up to fa3eb

Existing sessions remain routed to the efficient target at capacity, and final requests free or avoid session slots as documented. No identified issue prevents merging after normal checks.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 62.50% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 8 functions across 1 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: preserving plan-execute sessions when the identity limit is reached.

Full details: Docstring Coverage

Explanation

Docstring coverage is 62.50% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 8 functions across 1 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{A rabbit watched the sessions stay,
Four thousand latches held their way.
No old one hopped out at the door,
A full new handoff waited for more.
A final flag freed space to roam,
Then all the paths led safely home.}

_{Comment @coderabbitai help to get the list of available commands.}

[ayushag-nv]

interesting PR