feat(routing): add exclusive managed session connection leases by KaspaPulse · Pull Request #10362 · diegosouzapw/OmniRoute

KaspaPulse · 2026-08-14T08:47:24Z

Summary

Adds opt-in Exclusive Managed Session Leasing for API keys with lease:exclusive and an
explicit non-empty allowedConnections.
Gives one active managed client/session exclusive ownership of one eligible OmniRoute
connection for its lease lifecycle using SQLite-backed atomic ownership and exact generation
fencing.
Reuses OmniRoute's existing eligibility, allowedConnections, quota/health/cooldown logic,
routing strategy, retry/fallback, and session affinity.
Returns 429 LEASE_CAPACITY_UNAVAILABLE with WAITING_FOR_CAPACITY and Retry-After only
when ordinary eligible candidates exist but every one is occupied by a foreign active lease.
Core is client-neutral, provider-neutral, and model-neutral. No client-specific launcher
integration is included.

Why

Session affinity provides soft locality and continuity, but not exclusive lifetime ownership.
OAuth occupancy and the account semaphore address different request- or process-local concerns.
Long-lived managed clients sometimes need hard one-session/one-connection ownership across idle,
tool, and build periods. This change adds that opt-in authority without creating a second router
or account pool.

Contract

The API key must have the lease:exclusive scope and an explicit non-empty
allowedConnections list.
POST /api/v1/session-leases provides the acquire, renew, and release lifecycle endpoint.
Managed traffic supplies X-OmniRoute-Lease-Owner and
X-OmniRoute-Lease-Generation.
The raw owner is hashed before persistence.
The final fence binds the owner hash, exact generation, connection, and authenticated API-key
ID.
Global ACTIVE uniqueness applies to both owner and connection.
The default lease TTL is 120 seconds.
Acquire, renew, and release use exact ownership and generation semantics.
429 LEASE_CAPACITY_UNAVAILABLE, WAITING_FOR_CAPACITY, and Retry-After indicate that
ordinary eligible candidates exist but all are occupied by foreign active leases.
Unmanaged behavior is unchanged.

Related Work

Architecture precedents include #7650 for generic session affinity across providers, #8940 for
active OAuth-session occupancy and account availability, and #10149 for account-scoped
concurrency. This PR is a distinct opt-in hard lifecycle-ownership primitive.

Validation

The current-upstream typecheck:noimplicit:core findings remain only in unchanged
open-sse/utils/usageTracking.ts and src/shared/services/cliRuntime.ts; no feature file is
implicated.

Tests Added Or Updated

tests/unit/api-key-scope-validation.test.ts
tests/unit/chat-managed-lease-routing.test.ts
tests/unit/chatcore-executor-client-headers.test.ts
tests/unit/chatcore-translation-paths.test.ts
tests/unit/codex-ws-policy-enforcement-6564.test.ts
tests/unit/cors/origins.test.ts
tests/unit/exclusive-connection-leases.test.ts
tests/unit/exclusive-lease-api-key-policy.test.ts
tests/unit/exclusive-lease-auxiliary-isolation.test.ts
tests/unit/exclusive-lease-connection-test-isolation.test.ts
tests/unit/exclusive-lease-managed-set.test.ts
tests/unit/hard-session-lease-bypass-inventory.test.ts
tests/unit/hard-session-lease-zero-model-gates.test.ts
tests/unit/lease-context.test.ts
tests/unit/pick-internal-api-key-6372.test.ts
tests/unit/quota-auto-ping.test.ts
tests/unit/request-logger-endpoints.test.ts
tests/unit/session-leases-route.test.ts
tests/unit/sse-auth-exclusive-leases.test.ts
tests/unit/warmupScheduler.test.ts

Coverage Notes

The focused tests cover DB and migration lease authority; the API-key policy mutation invariant;
acquire, renew, and release; exact generation fencing and cross-key replay prevention; routing,
foreign-top skip, and next-free selection; capacity waiting with zero dispatch; client, provider,
and model neutrality; CORS and privacy; and auxiliary/bypass inventory. PR CI supplies broad
coverage.

Reviewer Notes

Adds the additive 154_exclusive_connection_leases.sql migration; its number was
collision-free at publication preflight.
Production true gross is 1,612 additions + 169 deletions = 1,781.
Adds no second router, quota/health/cooldown store, waiter table, daemon, or fixed mapping.
The lease-only managed set is derived from current active keys and is not independently cached.
The raw owner is not persisted, logged, or forwarded.
Client-specific launcher integration is intentionally excluded.
There is no dashboard or UI scope.

diegosouzapw · 2026-08-15T09:55:56Z

Thanks for this — it's a substantial, well-designed feature. The DB-level design (SQLite partial unique indexes for atomic global ownership fencing) is a solid approach to the "hard exclusive ownership" gap you identified relative to session affinity and OAuth occupancy, and the auth/scope gating, error sanitization, and test coverage are all in good shape. I ran tests/unit/exclusive-connection-leases.test.ts directly and all 11 tests pass, including the cross-process contention check.

Two things need fixing before this can merge, both stemming from the branch being a bit stale against release/v3.8.50:

Migration number collision: 153_exclusive_connection_leases.sql collides with 153_radar_local_model_state.sql, which landed on the release branch after this PR was opened. Could you renumber to the next free slot (154 as of now, but please re-check at rebase time) and update the hardcoded "153" references in tests/unit/exclusive-connection-leases.test.ts?
Rebase needed: a real merge conflict currently exists against release/v3.8.50 tip — but only in auto-generated doc/count files (AGENTS.md, README.md, llm.txt + all docs/i18n/*/llm.txt, docs/reference/API_REFERENCE.md). The actual feature code (auth.ts, chat.ts, chatCore.ts) merges cleanly. Please rebase and regenerate those files rather than hand-editing the counts.

Optional/non-blocking: the outer catch in session-leases/route.ts currently swallows the failure cause into a generic 503 with no log line — worth adding one for production debuggability. Also, since this is currently API-only (no dashboard surface for lease:exclusive + allowedConnections), a follow-up dashboard UI would help operators who don't want to hand-craft raw API calls — not required for this PR though, given the intended managed-client use case.

Once the migration number and rebase are sorted, this looks ready to go.

…ate docs Resolves migration-number collision (153 taken by 153_radar_local_model_state.sql): renumber src/lib/db/migrations/153_exclusive_connection_leases.sql -> 154 and update the hardcoded 153 path/assertion in tests/unit/exclusive-connection-leases.test.ts. Merges current release/v3.8.50 tip and regenerates auto-generated doc/count files (AGENTS.md, README.md, llm.txt, docs/i18n/*/llm.txt, docs/reference/API_REFERENCE.md) so migration/tool/scope counts reflect the live tree. Co-authored-by: diegosouzapw <8016841+diegosouzapw@users.noreply.github.com>

KaspaPulse · 2026-08-15T16:03:29Z

Thanks for the review and for pushing the sync commit.

I confirmed that the two blocking items are resolved:

the lease migration is now 154_exclusive_connection_leases.sql, with the corresponding test reference updated;
the branch is synced with the current release/v3.8.50 base and GitHub reports no merge conflicts.

I also updated the PR description to reflect migration 154.

I’ll keep the optional route logging and dashboard UI items as follow-up work so this PR stays focused on the generic lease core.

Marking this ready for review. Thanks again.

…sive-managed-session-leases Resolves conflicts against the release tip: renumbers the new 154_exclusive_connection_leases migration to 155 (collided with 154_call_logs_response_id from release), merges the api_keys insert statement to set both allowed_combos and allowed_connections, routes the chat dispatch through dispatchChatWithAffinityEviction while keeping managedLease plumbed through, and keeps both planSessionAffinityConnection and evictSessionAffinityOnComboTimeout in sessionAffinityPin.ts (independent additive functions). Regenerates the docs/i18n llm.txt mirrors from the merged root llm.txt via scripts/i18n/sync-llm-mirrors.mjs. Co-authored-by: diegosouzapw <8016841+diegosouzapw@users.noreply.github.com>

…sive-managed-session-leases # Conflicts: # src/lib/usage/providerLimits.ts # src/sse/handlers/chat.ts # src/sse/services/auth.ts

Two independently-merged PRs (#10263 agentic-conversation-tracking-v4 and #10362 exclusive-managed-session-leases) each picked migration slot 155 against different base states, landing a real collision on release/v3.8.50 (155_agentic_conversations.sql vs 155_exclusive_connection_leases.sql; #10263 also claimed 156 via 156_conversation_turn_nodes.sql). Renumbered #10362's migration to the next free slot (157) and updated its own regression test (exclusive-connection-leases.test.ts) that asserted the literal filename/slot. No retroactive guard needed: CREATE TABLE IF NOT EXISTS is idempotent under either number. Confirmed via check-migration-numbering.mjs (154 migrations, 0 duplicates) and the full exclusive-connection-leases test suite (11/11 pass).

…souzapw#10362) Co-authored-by: diegosouzapw <8016841+diegosouzapw@users.noreply.github.com>

Two independently-merged PRs (diegosouzapw#10263 agentic-conversation-tracking-v4 and diegosouzapw#10362 exclusive-managed-session-leases) each picked migration slot 155 against different base states, landing a real collision on release/v3.8.50 (155_agentic_conversations.sql vs 155_exclusive_connection_leases.sql; diegosouzapw#10263 also claimed 156 via 156_conversation_turn_nodes.sql). Renumbered diegosouzapw#10362's migration to the next free slot (157) and updated its own regression test (exclusive-connection-leases.test.ts) that asserted the literal filename/slot. No retroactive guard needed: CREATE TABLE IF NOT EXISTS is idempotent under either number. Confirmed via check-migration-numbering.mjs (154 migrations, 0 duplicates) and the full exclusive-connection-leases test suite (11/11 pass).

…souzapw#10362) Co-authored-by: diegosouzapw <8016841+diegosouzapw@users.noreply.github.com>

Two independently-merged PRs (diegosouzapw#10263 agentic-conversation-tracking-v4 and diegosouzapw#10362 exclusive-managed-session-leases) each picked migration slot 155 against different base states, landing a real collision on release/v3.8.50 (155_agentic_conversations.sql vs 155_exclusive_connection_leases.sql; diegosouzapw#10263 also claimed 156 via 156_conversation_turn_nodes.sql). Renumbered diegosouzapw#10362's migration to the next free slot (157) and updated its own regression test (exclusive-connection-leases.test.ts) that asserted the literal filename/slot. No retroactive guard needed: CREATE TABLE IF NOT EXISTS is idempotent under either number. Confirmed via check-migration-numbering.mjs (154 migrations, 0 duplicates) and the full exclusive-connection-leases test suite (11/11 pass).

Reuse the official managed lease authority for dashboard observability. Keep every active hard lease visible across idle/tool/build gaps, decorate it ACTIVE only while the bound connection has in-flight work, and preserve legacy session-fingerprint rows for unmanaged traffic. No lease/routing semantics, schema, quota, or client integration changes. Dashboard payloads intentionally exclude owner hashes, API-key ids, and fencing generations. Follow-up to diegosouzapw#10362; related to diegosouzapw#10514.

Summary Complete the dashboard/observability side of the exclusive managed session lease feature merged in diegosouzapw#10362. The existing Usage -> Active Sessions view now treats durable exclusive leases as first-class managed sessions: - every currently held exclusive lease remains visible while the client is idle, using tools, or doing local build work; - a leased session is decorated ACTIVE only while its bound connection has one or more in-flight requests; - an open lease with zero in-flight requests remains visible as IDLE; - releasing or expiring the lease removes it from the durable-session view; - legacy/unmanaged request-fingerprint sessions remain available, while a fingerprint row on a currently leased connection is de-duplicated in the UI so one managed client is not rendered twice. The lease table remains the lifecycle authority. Existing pending-request accounting is used only as an activity signal; it never creates, renews, releases, or extends a lease. Duplicate / prior-art check Before preparing this change, the public OmniRoute issues and PR history were searched for combinations of: exclusive lease, exclusive managed session, session leases, lease occupancy, SessionsTab, active sessions, dashboard, UI, and observability. The core request diegosouzapw#10514 and merged implementation diegosouzapw#10362 were found, but no public issue or PR requesting or implementing this dashboard binding. diegosouzapw#10362 explicitly states: "There is no dashboard or UI scope." This is therefore a follow-up to the merged core, not a second lease implementation. If maintainers have an internal/private backlog item for the same UI gap, it can be linked and this PR can be reconciled to that scope. Architecture Reuse existing OmniRoute authorities only: 1. getExclusiveLeaseConnectionIds() derives the managed candidate set from active API-key policy. 2. getExclusiveLeaseOccupancy() reads current durable lease occupancy from the official SQLite lease authority. 3. getPendingRequests().byAccount provides the existing in-flight request count per connection. 4. /api/sessions returns exclusiveCount and exclusiveSessions additively while preserving count, sessions, and byApiKey. 5. SessionsTab renders exclusive rows first and suppresses an older fingerprint row only when it refers to the same currently leased connection. No raw lease SQL is added to the route. No new store, table, cache, daemon, router, or account pool is introduced. ACTIVE vs IDLE ACTIVE means the durable lease exists and the bound connection currently has in-flight work. IDLE means the durable lease still exists, but no request is in flight right now. Request activity may come and go while exclusive ownership remains held for the client lifecycle. Privacy / fencing hygiene The dashboard projection intentionally does not expose lease_owner_hash, API-key IDs, lease generations, credentials, or tokens. It exposes only the connection binding, display activity state, recent request telemetry, and lease expiry. Scope In scope: - additive exclusive-session observability in /api/sessions; - ACTIVE/IDLE rendering in the existing Sessions UI; - de-duplication of legacy fingerprint rows on leased connections; - focused zero-model regression coverage. Out of scope: - lease acquisition/renew/release semantics; - routing, retry/fallback, health/cooldown, quota, or affinity behavior; - database schema or migrations; - API-key policy semantics; - client/launcher-specific integration; - provider-topology semantics. Validation Focused Node tests cover idle lease visibility, ACTIVE decoration from in-flight work, privacy of owner/fencing material, reuse of existing lease/pending authorities without raw lease SQL, and UI de-duplication. EXTERNAL_PROVIDER_MODEL_CALLS=0 by design. Broad build/unit validation is intentionally left to PR CI for the draft. Related: follow-up to diegosouzapw#10362; background diegosouzapw#10514.

Complete the dashboard observability follow-up for Exclusive Managed Session Leasing from diegosouzapw#10362 without changing lease or routing semantics. Behavior: - every currently valid exclusive lease remains visible in the existing Sessions view across idle, tool, and build gaps; - a leased connection with in-flight work receives the existing localized Active label; - an idle lease remains visible but is not mislabeled inactive; - release or TTL expiry removes the durable lease row through the official lease authority; - legacy/unmanaged session-fingerprint rows remain visible, with duplicate rows suppressed when the same connection is currently leased. Upstream alignment: - diegosouzapw#10362 deliberately excluded dashboard/UI scope; - the maintainer review on diegosouzapw#10362 explicitly identified dashboard UI as a useful follow-up; - public issue/PR searches found no separate implementation of this Sessions/lease integration. Architecture: - reuse getExclusiveLeaseConnectionIds() for the managed candidate set; - reuse getExclusiveLeaseOccupancy() as the durable lease authority; - reuse existing pending-request accounting only to decorate a valid lease as active; - extend the existing /api/sessions response and SessionsTab rather than adding a new store, route family, router, pool, daemon, or migration; - never expose lease owner hashes, API-key IDs, generations, credentials, or tokens. UI/i18n: - use the existing common.active translation instead of hardcoded status text; - keep idle lease rows present without inventing a new untranslated IDLE label across the 43-locale UI surface. Validation included: - pure projection tests for ACTIVE versus idle visibility; - real SQLite lease acquire/occupancy/release lifecycle coverage with zero model calls; - privacy/fencing-material assertions; - a jsdom rendering regression proving idle rows remain visible, duplicate legacy rows are removed, and only in-flight leases receive the localized Active badge; - a changelog fragment for PR diegosouzapw#11389. EXTERNAL_PROVIDER_MODEL_CALLS=0 by design. Refs diegosouzapw#10514 Follow-up to diegosouzapw#10362

Reuse the official exclusive-lease authority for durable idle visibility, and use pending-request accounting only for the localized active indication. Preserve legacy session fields and rows while de-duplicating leased connections and withholding lease ownership and fencing data. Refs diegosouzapw#10514 Follow-up to diegosouzapw#10362

@KaspaPulse

…11389) Merged into release/v3.8.51 via batch validation: exclusive-session-observability unit+UI suites green on the combined tree, static gates green. Nice additive observability layer over the #10362 lease backend — thanks @KaspaPulse!

…souzapw#10362) Co-authored-by: diegosouzapw <8016841+diegosouzapw@users.noreply.github.com>

Two independently-merged PRs (diegosouzapw#10263 agentic-conversation-tracking-v4 and diegosouzapw#10362 exclusive-managed-session-leases) each picked migration slot 155 against different base states, landing a real collision on release/v3.8.50 (155_agentic_conversations.sql vs 155_exclusive_connection_leases.sql; diegosouzapw#10263 also claimed 156 via 156_conversation_turn_nodes.sql). Renumbered diegosouzapw#10362's migration to the next free slot (157) and updated its own regression test (exclusive-connection-leases.test.ts) that asserted the literal filename/slot. No retroactive guard needed: CREATE TABLE IF NOT EXISTS is idempotent under either number. Confirmed via check-migration-numbering.mjs (154 migrations, 0 duplicates) and the full exclusive-connection-leases test suite (11/11 pass).

@KaspaPulse

…iegosouzapw#11389) Merged into release/v3.8.51 via batch validation: exclusive-session-observability unit+UI suites green on the combined tree, static gates green. Nice additive observability layer over the diegosouzapw#10362 lease backend — thanks @KaspaPulse!

feat(routing): add exclusive managed session connection leases

51cce4f

KaspaPulse marked this pull request as ready for review August 15, 2026 16:03

KaspaPulse requested a review from diegosouzapw as a code owner August 15, 2026 16:03

KaspaPulse mentioned this pull request Aug 16, 2026

[feature] Exclusive session connection leasing for long-lived client sessions #10514

Closed

This was referenced Aug 17, 2026

cherry-pick(pr-10362): feat(routing): add exclusive managed session connection leases thinh0704hcm/OmniRoute#6

Merged

cherry-pick(pr-10571): fix(opencode): session stability, free-tier routing, and CLI defaults thinh0704hcm/OmniRoute#12

Merged

KaspaPulse and others added 2 commits August 18, 2026 08:10

Merge remote-tracking branch 'origin/release/v3.8.50' into feat/exclu…

313ee96

…sive-managed-session-leases # Conflicts: # src/lib/usage/providerLimits.ts # src/sse/handlers/chat.ts # src/sse/services/auth.ts

diegosouzapw merged commit 8acd799 into diegosouzapw:release/v3.8.50 Aug 18, 2026
1 of 3 checks passed

HouMinXi pushed a commit to HouMinXi/OmniRoute that referenced this pull request Aug 20, 2026

feat(routing): add exclusive managed session connection leases (diego…

9030e79

…souzapw#10362) Co-authored-by: diegosouzapw <8016841+diegosouzapw@users.noreply.github.com>

giauphan pushed a commit to giauphan/OmniRoute that referenced this pull request Aug 20, 2026

feat(routing): add exclusive managed session connection leases (diego…

f9c352c

…souzapw#10362) Co-authored-by: diegosouzapw <8016841+diegosouzapw@users.noreply.github.com>

diegosouzapw mentioned this pull request Aug 23, 2026

Release v3.8.50 #8875

Merged

KaspaPulse mentioned this pull request Aug 24, 2026

feat(dashboard): surface exclusive managed sessions in Sessions view #11389

Merged

This was referenced Aug 27, 2026

fix(usage): allow quota refresh for FREE lease-reserved connections #11758

Merged

fix(lease): remove global static reservation and gate routing on live active lease occupancy #11775

Merged

KaspaPulse mentioned this pull request Aug 30, 2026

feat(leases): expose owner-authenticated connection display name #11910

Merged

Navigation Menu

Repository navigation

feat(routing): add exclusive managed session connection leases - #10362

feat(routing): add exclusive managed session connection leases#10362
diegosouzapw merged 4 commits into
diegosouzapw:release/v3.8.50from
KaspaPulse:feat/exclusive-managed-session-leases

KaspaPulse commented Aug 14, 2026 •

edited

Loading

Uh oh!

diegosouzapw commented Aug 15, 2026

Uh oh!

KaspaPulse commented Aug 15, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

KaspaPulse commented Aug 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Why

Contract

Related Work

Validation

Tests Added Or Updated

Coverage Notes

Reviewer Notes

Uh oh!

diegosouzapw commented Aug 15, 2026

Uh oh!

KaspaPulse commented Aug 15, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

KaspaPulse commented Aug 14, 2026 •

edited

Loading