Optional cap on concurrent live provider sessions per environment, to bound RAM when threads never go idle

[Ali-Al1]

Summary

We'd like to propose an optional, opt-in limit on how many provider sessions (for example claude processes and their MCP servers) can be live at once in one T3 environment. When the limit is reached, the oldest session that has no turn in progress would be released first. If every session is mid-turn, T3 would start the new session anyway rather than block (fail open).

This is meant to work alongside the open work on idle timeouts and releasing sessions when a task finishes, which we support (see "Support for related open work" below). It covers a case those changes can't: threads that stay busy enough never to reach an idle timeout.

Per CONTRIBUTING, we're posting this as an Ideas discussion. We're asking for maintainer direction and scope before anyone opens a PR.

Problem: what one operator saw in production

We run T3 nightly on a 16 GB Windows laptop and use delegate_task heavily. Our own host memory monitor raised a critical low-RAM alert twice in three days. The monitor only observes, so nothing was killed. These figures come from one machine. They're not a benchmark.

9 Nov 2026 (main incident)

• Available memory fell to 1.18 GiB of 15.41 GiB (92% memory load). Commit charge was only 41%, so the trigger was physical memory, not commit.

• claude.exe count and total private bytes, every one a child of one nightly t3.exe (started 04:12):

  Snapshot	claude.exe processes	Total private bytes
  07:32	23	10.51 GiB
  09:23	36	15.91 GiB
  09:26	37	16.43 GiB

• That works out to about 0.44–0.46 GiB per claude.exe, and the figure stayed steady as the count grew.

• The three oldest claude.exe processes had started between 04:12 and 04:20, so they were about five hours old by the last snapshot. New claude.exe processes kept appearing from 07:11 to 09:23.

• Between the first and last snapshots, system-wide processes went 443 → 564, handles 154k → 176k and threads 4,949 → 5,540.

7 Nov 2026 (milder, same pattern)

• 9 claude.exe processes, 3.75 GiB private bytes. The process tree and growth looked the same, just smaller.

Caveat: we count claude.exe processes. We haven't mapped each process to a T3 thread or session, and we haven't split them into finished delegate children, parents and long-running threads. With the default 30-minute idle timeout, processes that are about five hours old must have had a turn at least every 30 minutes, or must still be held for some reason we haven't found.

Why the existing levers aren't enough

#26413 diagnoses the root cause: ProviderSessionManager uses a fixed DEFAULT_IDLE_TIMEOUT_MS of 30 minutes, no caller passes idleTimeoutMs, and "there is no cap on how many idle sessions may stay live". Sessions are otherwise released only on settle or detach.

The proposals so far address part of this:

• A shorter or configurable idle timeout (#25624, and options (a) and (b) in Finished Claude delegate_task sessions keep their claude process and MCP servers for 30 minutes, so delegate-heavy runs exhaust RAM #26413) frees sessions that have been idle for at least N minutes. A thread that takes a turn more often than every N minutes keeps its session forever. If K threads behave like that, K sessions stay live, whatever N is. Lowering N to catch them would add cold starts to every thread on the machine, and it still wouldn't put a ceiling on K.
• Releasing on completion (#31466, #29868, and option (c) in Finished Claude delegate_task sessions keep their claude process and MCP servers for 30 minutes, so delegate-heavy runs exhaust RAM #26413) frees finished delegated children straight away. That's the right default. It doesn't apply to threads that never finish, such as coordinators, monitors and recurring work.

What's missing is a limit on the number of live sessions. Each live session costs a roughly fixed amount of RAM, about 0.44 GiB on our machine, so a count limit is the only one of these levers that limits worst-case memory directly.

Proposal (a starting point for maintainers)

• Setting: an optional maximum number of concurrent live provider sessions per environment. Unset means today's behaviour.
• At the limit: before starting a new session, release the oldest session with no turn in progress. Here "idle" means no turn is running right now, however briefly. It doesn't mean idle for 30 minutes. Ideally this would use the same release path as the idle timeout, so a released thread resumes on its next turn exactly as it does after a timeout.
• If no session is idle: start the new session anyway (fail open) and log or surface a warning. Blocking or queueing could deadlock a parent that is waiting on its own delegated child.
• Result: the number of live sessions stays at or below the larger of the cap and the number of turns actually running at once. Memory then follows real concurrency rather than accumulated history.

Open questions we'd defer to maintainers:

• Should the limit be per environment, per provider, or both?
• Should eviction prefer finished delegate children before other idle sessions?
• Should eviction be visible in the UI?
• Should there be a recommended default for low-RAM machines?

Justification

1. It limits the resource that actually runs out. On our laptop the failure was physical RAM exhaustion across the whole machine. The OS and every other application suffered, not just T3. Because each session uses a stable amount of memory, a session limit becomes a memory limit operators can calculate: roughly the cap × about 0.44 GiB on our hardware.
2. It covers the case timeouts can't. Threads with frequent turns never reach any idle timeout. On 9 Nov the count went from 23 to 37 claude.exe processes in under two hours, with three processes about five hours old. A timeout alone never stops that kind of growth.
3. It adds to the other fixes and replaces none of them. Releasing on completion should remain the first line of defence, and a configurable timeout the second. The cap is a backstop that only acts when those haven't kept the session count low enough.
4. The trade-off is explicit and opt-in. An evicted thread pays a cold start on its next turn, which is the same cost as an idle-timeout release today. Operators with plenty of RAM leave it unset and see no change. Operators on 16 GB machines get a predictable ceiling.
5. Failing open keeps it safe. The cap never blocks a turn, and a parent waiting on its delegated child can't be starved. At worst, behaviour is the same as today.
6. The change should be small. It's a count check plus "release oldest idle" at session start. It could presumably reuse the existing release path, without needing a new session lifecycle.
7. This isn't covered anywhere yet. We searched issues, PRs and Ideas discussions and found no existing request for a concurrent-session cap or a RAM-related session limit.

Support for related open work

We support all four of these. Merging them would cut our session count before a cap ever needed to act:

• Finished Claude delegate_task sessions keep their claude process and MCP servers for 30 minutes, so delegate-heavy runs exhaust RAM #26413 (finished delegate_task Claude sessions keep the process and MCP servers for 30 minutes): its diagnosis matches what we saw, including the point that nothing limits how many idle sessions stay live. 👍
• feat(server): make idle agent release configurable #25624 (configurable idle release, 1–1440 minutes or Never): this lets us choose a shorter timeout on a memory-constrained machine. 👍
• fix(server): release a finished delegated child's provider session at once #31466 (release a finished delegated child's session at once): this targets the largest likely source of our accumulation, given how heavily we use delegate_task. 👍
• fix(codex): archive finished delegated sessions after result delivery #29868 (archive finished delegated Codex sessions after delivering the result): our incident involved the Claude provider, but we support applying the same "release when finished" rule to every provider. 👍

Environment

• T3 Code nightly desktop build (t3.exe) on Windows 11 Pro for Workstations (build 26200)
• 16 GB RAM (15.41 GiB usable)
• Claude provider (claude.exe) with MCP servers; heavy delegate_task use, with long-running coordinator threads plus delegated children

Requested next step

Following CONTRIBUTING, we're asking whether maintainers would accept this direction and scope: the cap, how eviction works, and what happens when no session is idle. If so, a PR would link to that approval. We haven't opened one yet.

[Ali-Al1]

Follow-up with measured evidence from the same machine, taken today after our earlier reports — it strengthens the case for release-on-completion (#31466, #29868) and for a cap (#33413's proposal):

• Since 04:12 today, of 179 stopped delegate sessions, 173 were released 25–35 minutes after their last run completed — exactly the hardcoded 30-minute idle timer. None lasted beyond 35 minutes.
• Delegate sessions spent 42.6 session-hours working vs an estimated 89.5 session-hours idle after finishing — about 68% of their alive time was post-completion residency.
• 0 of 283 delegate threads created today were settled by their parents.
• At an 18:42 snapshot: 37 live claude.exe / 16.3 GiB private under one t3.exe = 20 finished-but-held delegates + 4 idle top-level threads + 13 actually active. So the accumulation was dominated by completed work waiting out the timer, not by never-idle threads.

Why this matters for the open PRs: #31466 (release a finished delegated child's session at once) would have removed roughly two-thirds of delegate residency on this machine today — at the peak it would have cut 37 sessions to about 17 (~8.5 GiB). A configurable timeout (#25624) helps only by shortening the same window; a cap bounds the remainder.

Interim measure on our side (no product change): we're building a small Foreman sweeper that settles delegated children a few minutes after their result is delivered, as local behaviour until the upstream fixes land. Happy to adjust the cap proposal in light of any direction maintainers prefer.