Files
kandev/docs/specs/agents/system-design/session-concurrency-ceiling.md
T
2026-09-17 22:28:25 +01:00

5.1 KiB

status, system, requirements
status system requirements
current agents
REQ-AGENTS-SESSION-CEILING-001

Session Concurrency Ceiling System Design

Purpose and boundaries

The orchestrator owns one admission controller shared by manual starts, resumes, workflow starts, queue drains, and dynamic relaunches. The controller does not own task metadata or provider execution. It returns a reservation or a typed refusal. The task repository owns the durable deferred-launch record.

Requirement mapping

Requirement Design section
REQ-AGENTS-SESSION-CEILING-001 Admission and replay, Failure and recovery

Components and responsibilities

Component Responsibility
sessionCeilingController Counts persisted STARTING/RUNNING sessions and process-local reservations. It admits, refuses, confirms, and releases launches.
Orchestrator launch seams Pass the launch origin and complete replay payload to the controller. They consume a reservation only after launch success.
deferCeilingRefusal Merges the ceiling-owned keys into task deferred_launch with compare-and-set semantics.
Ceiling sweep Lists tasks with ceiling records, validates eligibility, and dispatches the stored launch kind.
Task repository and service Store and update the shared deferred record. Prompt edits update both legacy top-level data and the nested ceiling payload.
Executor callbacks Confirm or release only when the callback execution still owns the session row.

Data and contracts

The shared record uses ceiling_deferred, ceiling_launch_kind, ceiling_launch_payload, ceiling_launch_origin, ceiling_reason_code, and ceiling_queued_at. The payload is nested so replay does not confuse a resume, prompt ensure, or dynamic relaunch with a task start. A different pending payload returns ErrCeilingLaunchConflict; the existing record stays unchanged.

The controller resolves KANDEV_MAX_CONCURRENT_SESSIONS once at startup. An unset or invalid value uses half the host CPU count, with a minimum of two. Zero means unlimited. The value is an environment-only startup setting.

Admission and replay

The flow is:

launch request
  -> orchestrator seam
  -> sessionCeilingController.admit
  -> reservation, or typed refusal
  -> deferCeilingRefusal(task CAS) when automatic refusal
  -> executor launch and callback
  -> confirm/release reservation
  -> ceiling sweep replays the stored kind when capacity is available

Manual origins bypass refusal and write a manual-override audit entry. Automatic origins never become manual during replay. The sweep clears a record only after successful dispatch. A repeated refusal leaves the original timestamp and payload in place.

The task admission lock protects bounded record and route operations. Replay releases this lock after validation, before session-guard waits and provider dispatch. The dispatch context retains the workflow binding, but not ownership of the released lock. The durable claim excludes competing replay consumers. Launch and prompt boundaries revalidate the binding before provider work.

Task-state reconciliation acquires task admission before the global task-state mutex. A task-local admission wait cannot hold the global mutex. Provider callbacks can complete while replay waits for agent readiness.

The task-owned queued session ownership design plans explicit passive-inspection classification at the caller boundary. Opening a conversation is not a manual override. Actual explicit execution retains this design's manual admission rule; workflow parking eligibility remains task-owned.

Failure and recovery

Reservation ownership is session-keyed. A stale process-start callback first checks the persisted session execution identity; it cannot release a successor's reservation. A dynamic relaunch reports three outcomes: succeeded, deferred, or failed. A deferred detached relaunch leaves the automation run and its durable record for the sweep. Queue dispatch treats a seam-3 refusal as retryable so the original message remains in the queue.

Office automatic starts do not use workflow-step auto-start eligibility when the sweep evaluates a start record. This keeps Office scheduling ownership in the Office path.

Persistence

deferred_launch is updated with a read-compare-write retry loop. The ceiling keys share the task record with other launch intents and are removed as a group after replay or a terminal drop. A prompt edit preserves unrelated keys and updates the nested replay payload.

Security

The controller receives launch data from trusted backend paths. The nested payload is excluded from plugin host data. No prompt or environment value is executed during replay; it is passed to the same existing launch seam after task and session eligibility checks.

Observability

Admission decisions, refusal reasons, reservation expiry, replay drops, and manual overrides use the existing orchestrator logs and task status messages. The stored reason and population snapshot make a refusal diagnosable after a restart.