Session Concurrency: sessionKey / lane / queue

This chapter covers the queueing system. When it’s wrong, you get cross-talk, disorder, and context corruption.

Entry points:

• Queue + lanes
• Sessions
• Session tool

Two-level queueing: session ordering + global limits

• session lanes keep a single sessionKey ordered (serial)
• global lanes cap concurrent work across sessions (resource protection)

Lane state: concurrency, warnings, and restart recovery

Useful mechanics to keep explicit:

• maxConcurrent per lane
• enqueue wait warnings (warnAfterMs / onWait) as observability signals
• generation increments on resets to ignore stale callbacks after in-process restarts

Clear vs reset

• clear cancels queued-but-not-started work
• reset clears active state, bumps generation, and drains backlog again

Code entry points (optional)

• src/agents/pi-embedded-runner/lanes.ts
• src/process/command-queue.ts
• src/gateway/server-lanes.ts
• src/gateway/server-session-key.ts
• src/config/sessions/session-key.ts