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

[KaspaPulse]

Summary

• Add an explicit {"action":"status","generation":N} action to POST /api/v1/session-leases.
• Return the active binding's privacy-safe configured connection label and safe provider display label only after authenticating the managed API key and fencing the exact owner, key, and generation.
• Keep acquire, renew, release, inference, capacity-wait, and admin Sessions behavior backward compatible.
• Document the opt-in contract, privacy boundary, transition semantics, and the separate codex-omni client follow-up.

Example status response:

{
  "state": "ACTIVE",
  "generation": 1,
  "acquiredAt": "2026-08-28T12:00:00.000Z",
  "renewedAt": "2026-08-28T12:00:30.000Z",
  "expiresAt": "2026-08-28T12:02:30.000Z",
  "connection": {
    "displayName": "Primary Codex",
    "provider": "codex"
  }
}

Related issues

• Closes feat(api): expose owner-authenticated connection display name to managed clients #11907
• Related to [feature] Exclusive session connection leasing for long-lived client sessions #10514, feat(dashboard): surface exclusive managed sessions in Sessions view #11389, and fix(sessions): preserve legacy data when exclusive projection fails #11469

Why this server PR is needed

OmniRoute already knows which connection owns an exclusive lease, but the lease-owning client has no privacy-safe API for reading that configured label.

The authenticated Sessions dashboard added by #11389 helps administrators, but it does not allow codex-omni to truthfully display the active connection inside the user's terminal.

This PR supplies that missing authenticated server contract. It does not modify stock openai/codex or its built-in /status command.

Security and compatibility contract

• The lookup runs in one SQLite transaction after lazily expiring stale active rows.
• It joins only the exact ACTIVE lease matching the owner hash, managed API-key id, generation, and unexpired timestamp.
• Wrong key, wrong owner, stale generation, missing, expired, released, and invalidated leases return generic 409 LEASE_FENCE_STALE without connection metadata.
• A completed same-generation transition resolves only the newly active binding.
• displayName uses only the trimmed operator-configured connection name.
• Empty, email-shaped, provider-email-derived, and provider-display-name-derived fallback values are withheld as null.
• Generated compatible-provider identifiers are converted to non-sensitive provider labels.
• Serialized output excludes credentials, API keys, tokens, cookies, connection ids, API-key ids, raw owners or hashes, fencing secrets, and internal routing material.
• Existing clients retain their previous lifecycle response shape.
• The optional connection object is populated only for an explicit successful status action.
• The existing admin Sessions API remains unchanged.

Codex-omni follow-up and fastest user-visible path

If this server contract is accepted and merged, I plan to submit a separate follow-up PR for the component that owns codex-omni.

A separate PR is necessary because this contribution defines and secures the authenticated OmniRoute API, while the follow-up consumes that API and changes what the user sees in the terminal.

Fastest implementation path

The first usable integration does not require modifying stock Codex /status.

1. After codex-omni acquires or restores an exclusive lease and knows its current generation, it calls:

   {"action":"status","generation":1}

   through POST /api/v1/session-leases, using the same managed credentials and exact owner/session identity.

2. When the session starts, codex-omni prints the returned privacy-safe label:

   OmniRoute connection: Primary Codex (codex)
   

3. After a legitimate lease transition or failover, it calls the same status action again and displays the newly bound connection, never the old binding.

4. When no active binding exists, it displays a neutral state without exposing a connection label:

   OmniRoute connection: waiting for capacity
   

This is a control-plane lookup only. It sends no model prompt, consumes no model quota, and does not alter routing or exclusivity behavior.

Optional /omni-status command

A later client follow-up may also provide:

/omni-status

This is possible only if codex-omni owns or can safely intercept the command layer.

If command interception is not available, displaying the connection during session startup and after transitions remains the fastest usable solution.

Adding the connection to stock Codex's built-in /status would require a separate contribution to openai/codex. That work is not required for the initial usable codex-omni integration.

User-visible benefit of the follow-up

• Identify the exact configured OmniRoute connection directly from the current terminal.
• Confirm that the intended exclusive account is bound to the session.
• See legitimate account transitions or failover immediately.
• Distinguish an active account from capacity waiting.
• Diagnose unexpected account selection without opening the administrator dashboard.
• Avoid exposing email addresses, credentials, tokens, internal connection IDs, owner hashes, or routing secrets.
• Perform the lookup without sending a model request or consuming model quota.

Tests added or updated

tests/unit/session-leases-route.test.ts covers:

• Valid active owner receives only the configured label and safe provider label.
• Wrong key, wrong owner, and stale generation fail closed.
• Email and provider-display-name fallbacks are withheld.
• Dynamic provider ids and secret/internal fields are absent.
• Transition returns the new binding, never the old binding.
• Released, expired, invalidated, missing, and capacity-wait states expose no metadata.
• Acquire, renew, and release remain backward compatible.
• Outbound fetch is intercepted so no real provider or model call can occur.

Validation

PR-local validation completed before publication:

• Status route tests: 14 passed.
• Focused lease lifecycle, routing, authentication, and observability suites: 73 passed.
• Managed-key policy and isolation suites: 13 passed.
• Touched-file ESLint and Prettier: passed.
• OpenAPI coverage, route validation, security checks, changelog, DB, build-scope, public-credential checks, and git diff --check: passed.
• External provider/model calls: 0.

Ready-CI remediation

The first Ready-for-review CI run exposed three PR-specific integration issues.

Commit 878a0ed corrected the lifecycle OpenAPI compatibility, capacity-wait wording, and generated skills/omni-inference/SKILL.md output.

Checks directly verified on that remediation head include:

• Change Classification: passed.
• Merge integrity and generated skills: passed.
• Semgrep: passed.
• Vitest fast-path: passed.

The DAST job on that head did not reach the actual DAST tests. Its runner received a shutdown signal during Build CLI bundle, and all subsequent DAST steps were skipped. It therefore represents an infrastructure cancellation, not a product-test failure and not a successful DAST result.

The branch was subsequently refreshed onto the newer release base. The following section records the authoritative status of the current head.

Current Ready CI status

The branch is currently based on 3b752f9d4cbb79a7db3a444e3d3da75cef9b9bcf with head 8333a0d033e94e5ac22e4260ffe7802568e02504.

On this head:

• Quality Gates: passed.
• All four unit-test fast-path shards: passed.
• Docs Gates, Vitest, ESLint ratchet, Change Classification, merge integrity, and Semgrep: passed.
• Build (advisory) was cancelled because the hosted runner received a shutdown signal during npm run build; no compilation error was reported.
• No DAST check is recorded for this head, so this PR does not claim a current-head DAST pass.

The previous inherited-base failure list referred to the superseded base cab9cdc765e6d8b5a560c606ad134a154a4e3153 and no longer describes the current head. Issue #11874 remains historical upstream context.

Reviewer notes

• Ready for review of the server contract, privacy boundary, and planned client integration.
• No schema migration is included.
• No feature flag, deployment, provider dispatch, dashboard redesign, or production mutation is included.
• No external provider or model call is performed.
• This PR is independently useful as the safe server API contract.
• After this contract is accepted and merged, the planned separate codex-omni PR will provide the terminal display described above.