Skip to content

CL-7007: Give retained sessions their own retention cap - #628

Merged
TheGreatAxios merged 1 commit into
mainfrom
cl-7007-retained-sessions-are-evictable-at-maxcompleted20-so
Aug 24, 2026
Merged

CL-7007: Give retained sessions their own retention cap#628
TheGreatAxios merged 1 commit into
mainfrom
cl-7007-retained-sessions-are-evictable-at-maxcompleted20-so

Conversation

@TheGreatAxios

Copy link
Copy Markdown
Collaborator

Summary

  • Retained worker sessions (spawn_agent, resumable via resume_agent/followup_task) were sharing pruneCompleted's maxCompleted (a TUI display cap, default 20) with every other finished session, a side effect of CL-7002's correct removal of their previous unbounded exemption. Past 20 spawned workers, resume_agent on an early one failed with a bare not_found.
  • Adds maxRetained (default 50), a separate cap sized for fan-out, governing only open retained sessions (retained:true, lifecycleStatus completed/interrupted). maxCompleted now excludes these and continues to bound every ordinary finished session exactly as before.
  • Eviction under maxRetained picks least-recently-used, never evicts a running session, and still calls releaseHandles (sidecars/reactor/lock entry) exactly like pruneCompleted's eviction.
  • An evicted session is tombstoned (bounded to 500 entries) so resume_agent/followup_task/close_agent report an actionable terminal status plus a read_agent_trace pointer instead of not_found.
  • Fixed the stale comment on SubAgentSession.retained claiming an exemption from pruneCompleted's cap that no longer exists.
  • maxRetained resolution guards non-finite/undefined config (including a JSON round-trip turning a configured Infinity into null) so it can never silently collapse to 0.

Tests changed and why

Three existing tests encoded "retained sessions share the display cap" as correct behavior — that was exactly this ticket's defect, so they were updated rather than left to falsely pass:

  • session-store.test.ts: pruneCompleted evicts a retained, still-open session past maxCompleted...pruneRetained evicts a retained, still-open session past maxRetained.... Added a companion asserting maxCompleted still evicts an ordinary (non-retained) session.
  • agent-fleet.test.ts: reports survive well past the session store's display cap (20)... previously asserted the earliest of 25 spawned retained sessions was evicted from the store; now asserts it is not (25 < default maxRetained 50).
  • retain-salvage.test.ts: retained completed sessions are exempt from the display cap without bound...bounded by maxRetained, not the display cap, now configuring maxRetained instead of relying on maxCompleted.

New tests added (session-store.test.ts): resume_agent on an evicted session returns actionable status + hint; a running session is never evicted by maxRetained; maxRetained bounds memory across 50 spawned-and-completed retained sessions.

Test plan

  • bun test src/subagent/session-store.test.ts src/subagent/agent-fleet.test.ts src/subagent/lifecycle-tools.test.ts src/subagent/retain-salvage.test.ts — all pass
  • bun run check (lint, typecheck, build, full test suite) — 5294 pass, 0 fail

pruneCompleted's maxCompleted is a TUI display cap (default 20); CL-7002
correctly removed retained sessions' unbounded exemption from it, but that
folded reusable-session retention into the same 20-item cap, so resume_agent
on an early worker failed with a bare not_found past 20 spawned workers.

Open retained sessions (retained:true, lifecycleStatus completed/interrupted)
are now excluded from maxCompleted and bounded instead by a separate
maxRetained cap (default 50, sized for fan-out), evicting least-recently-used
first and never evicting a running session. Eviction still releases sidecars/
reactor/lock entry via releaseHandles, and leaves a tombstone so resume_agent/
followup_task/close_agent report an actionable terminal status plus a
read_agent_trace pointer instead of not_found.

Updated three CL-7001/CL-7002 tests that had encoded "retained sessions share
the display cap" as correct behavior to instead assert the new maxRetained
bound.
@linear-code

linear-code Bot commented Aug 24, 2026

Copy link
Copy Markdown

CL-7007

@TheGreatAxios
TheGreatAxios enabled auto-merge (squash) August 24, 2026 15:34
@TheGreatAxios
TheGreatAxios merged commit a0c72ad into main Aug 24, 2026
5 checks passed
TheGreatAxios added a commit that referenced this pull request Aug 27, 2026
pruneCompleted's maxCompleted is a TUI display cap (default 20); CL-7002
correctly removed retained sessions' unbounded exemption from it, but that
folded reusable-session retention into the same 20-item cap, so resume_agent
on an early worker failed with a bare not_found past 20 spawned workers.

Open retained sessions (retained:true, lifecycleStatus completed/interrupted)
are now excluded from maxCompleted and bounded instead by a separate
maxRetained cap (default 50, sized for fan-out), evicting least-recently-used
first and never evicting a running session. Eviction still releases sidecars/
reactor/lock entry via releaseHandles, and leaves a tombstone so resume_agent/
followup_task/close_agent report an actionable terminal status plus a
read_agent_trace pointer instead of not_found.

Updated three CL-7001/CL-7002 tests that had encoded "retained sessions share
the display cap" as correct behavior to instead assert the new maxRetained
bound.
TheGreatAxios added a commit that referenced this pull request Aug 27, 2026
pruneCompleted's maxCompleted is a TUI display cap (default 20); CL-7002
correctly removed retained sessions' unbounded exemption from it, but that
folded reusable-session retention into the same 20-item cap, so resume_agent
on an early worker failed with a bare not_found past 20 spawned workers.

Open retained sessions (retained:true, lifecycleStatus completed/interrupted)
are now excluded from maxCompleted and bounded instead by a separate
maxRetained cap (default 50, sized for fan-out), evicting least-recently-used
first and never evicting a running session. Eviction still releases sidecars/
reactor/lock entry via releaseHandles, and leaves a tombstone so resume_agent/
followup_task/close_agent report an actionable terminal status plus a
read_agent_trace pointer instead of not_found.

Updated three CL-7001/CL-7002 tests that had encoded "retained sessions share
the display cap" as correct behavior to instead assert the new maxRetained
bound.
@TheGreatAxios
TheGreatAxios deleted the cl-7007-retained-sessions-are-evictable-at-maxcompleted20-so branch August 28, 2026 00:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant