Local session limit

What it is

What: One number, the local session limit, says how many agent sessions may be running on this computer at the same time. The setting is localSessionCeiling: a whole number from 0 to 2000, 150 by default, where 0 turns the limit off. A change applies to the very next start, with no restart.

What it counts: sessions whose process is running on this computer. Sessions on cloud machines or remote hosts are not counted, and neither is a session whose process was released while it sat idle (see Idle session release).

Why it exists: past a certain size a bigger fleet does not finish more work, it only makes every agent slower, because each tool call waits longer for the machine. A limit that is only written down gets ignored, above all by sessions the app starts by itself, so this one is enforced at the single place every local session start passes through. No kind of session can start around it.

Where to find it

• The number: the settings API on the local control server, GET or PATCH /settings/localSessionCeiling. There is deliberately no row for it in Settings.
• The wait: a session that is waiting shows one note in its own thread: "Waiting for a free place. Sessions running now: N. Limit: M. This one starts on its own as soon as a place frees up." The note is translated into every language the app ships in.
• The readout: GET /perf/status carries a localSessionCeiling block, and the text readout has a session-cap row. It shows the limit, the live count plus the places held for starts not yet counted, how many are waiting (the oldest wait, and by lane and by producer), and what has happened since the app started. See Performance Monitor.

How it behaves

• Who waits. Only a session the app starts without you asking for it: a session an agent starts for a helper, a recipe or scheduled job, a code review, the command line, and the restart of sessions after a crash or an app restart.
• Who never waits. Your own New Session, Send and Restart; your message to a session that is already waiting (it starts at once); a crew lead's session; and any session on a cloud machine or remote host. They still count toward the total.
• One line, first come first served. Every waiting start shares one line, in the order it arrived. A waiting start has no time limit and is never failed, dropped or timed out. A place frees when a running session ends or its idle process is released, and the next in line starts by itself within about a second.
• The restart spacing still holds. When many starts leave the line together (you raise the number, switch the limit off, or a crash-restart queue clears), they still begin one at a time at your restart spacing, never in one burst.
• A place is kept for a start that was let through. It stays reserved until that session's process shows in the count, however long the start is parked in another hold, so two starts cannot both take the last place.
• A fault never stops a start. If the limit cannot read its number or the live count, the start goes ahead and the fault is counted on the readout.
• It is not a memory or CPU check. The memory, box-load and capacity holds keep running on their own, as before.

For agents

• Read the number with GET /settings/localSessionCeiling. Change it only when the person asked you to, with PATCH /settings/localSessionCeiling and a whole number from 0 to 2000.
• Switch it off for a run with AMC_DISABLE_LOCAL_SESSION_CEILING=1; the switch is read at every start.
• The queue and the reserved places live in src/main/process/local-session-ceiling.ts. The check is the first rung of acquireSpawnSlot in src/main/process/spawn-concurrency-gate.ts, and which origins are held is the ceilingHeld flag of each plan in src/main/process/spawn-admission-policy.ts.
• To see whether the limit is the reason a session has not started, read the session-cap row: a non-zero waiting count with the live count at the limit means the line is working, not that the session is stuck.

Related

• Concurrent multi-session orchestration — running many sessions at once.
• Idle session release — how an idle session gives its place back.
• Performance Monitor — where the live count, the limit and the line are shown.