feat(sse): reserve the Antigravity account for the request's stream lifecycle (re-land of #10011)

[diegosouzapw]

Credit

The design and the original implementation are @Ardem2025's, from #10011. This is a
re-land of the piece of that PR that survives on the current release branch — the account
lease — rebuilt on release/v3.8.51. #10011 itself was closed because its exact-model-scoping
half had already shipped in #8050 and its quota half lost to the tip's different design.

Problem

Antigravity account selection has no notion of "this account is already busy with a live
stream". A request picks an account; a concurrent retry — or the credential handoff inside
getProviderCredentialsWithQuotaPreflight — can pick the same account again while the first
request is still streaming from it. The pool then piles onto one account instead of spreading
across the ones that are actually free.

Design

A process-local account lease, acquired during credential selection and released by the
terminal lifecycle of the response it was reserved for.

• Scope is (connection, callable upstream model) — not the whole account. An Antigravity
  account can serve two different upstream models concurrently; fencing the whole account would
  needlessly serialize unrelated traffic. Catalog ids that resolve to the same callable
  upstream id share one lease (the three gemini-3.7-flash-{high,medium,low} tiers are all
  gemini-3.7-flash-tiered).
• Released by lifecycle, never by a timer. EOF, cancel, reader error, client abort,
  pre-dispatch failure, non-streaming response, dispatch throw — each frees it exactly once.
  The stored timestamp is a bounded Retry-After hint, never an expiry; nothing compares it
  against the clock to free a lease.
• Release is fenced by lease id. A stale finally cannot free a newer lease that has since
  claimed the same slot (covered by a test).
• Pool saturation gets its own answer. When every eligible account is already leased for
  that model, the request returns a structured 503 with code: "antigravity_pool_busy" and a
  bounded Retry-After, instead of being reported as an upstream error. antigravity_pool_busy
  had to be added to SAFE_PUBLIC_ERROR_IDENTIFIERS in open-sse/utils/error.ts — without it
  buildErrorBody projects the code onto the status fallback and POOL_BUSY becomes
  indistinguishable from a generic upstream service_unavailable.

Orthogonal to quota, deliberately. This is a concurrency reservation. It never reads or
writes quota state. selectAntigravityQuotaWindowNames, antigravityQuotaFamily.ts,
quotaPreflight.ts and quotaCache.ts are untouched; #10011's competing exact-model quota
logic is not reintroduced.

Resolving #10011's known defect

#10011's tests/unit/antigravity-routing-state.test.ts → "release is fenced and explicit
release restores availability" failed deterministically on its own head: it asserted family
semantics (a sibling model fenced by another model's lease) against an implementation that was
exact-model scoped. On top of that the model ids it used — gemini-3.5-flash and
gemini-3-flash-agent — no longer exist in this branch's catalog, and the hardcoded
gemini-3.5-flash → gemini-3-flash-agent bridge in its canonicalizer is dead code here.

Resolved in favour of one coherent semantic: the exact callable upstream model, and the
tests assert that against the alias tables as they actually are on this branch. Canonicalization
consults ANTIGRAVITY_MODEL_ALIASES before the generic catalog alias, because
gemini-3.1-pro-high is callable only as gemini-pro-agent while resolveModelAlias would
collapse it onto plain gemini-3.1-pro.

Feature flag

ANTIGRAVITY_ACCOUNT_LEASE_ENABLED — category runtime, defaultValue: "false",
requiresRestart: false. Read through isAntigravityAccountLeaseEnabled() in
src/shared/utils/featureFlags.ts, which fails closed (an unreadable flag store keeps the
pre-flag behaviour), and is short-circuited by a provider === "antigravity" check so the flag
store is not read for any other provider.

With the flag off: no reservation is taken, credentials carry no routing descriptor, every
release/hold is a no-op on an undefined lease id, leaseUnavailable can never be produced
so its branch is dead, and excludedConnectionIds / the preselected-credentials fast path start
exactly as they do today. The only structural change on the flag-off path is three .catch()
handlers whose callback only releases an undefined lease and rethrows — all three wrapped
calls (applyConnectionReasoningRule, checkAndRefreshToken, safeResolveProxy) are
async functions, so they always return a promise and the rejection value is unchanged.

Files

Added

• src/sse/services/antigravityRoutingState.ts — the lease registry (acquire / release / query,
  canonicalization, id-fenced release with an O(1) reverse index)
• src/sse/services/antigravityLeaseLifecycle.ts — lifecycle glue: SSE hold-through-response,
  releasingRethrow, POOL_BUSY builder, per-request state
• src/sse/services/antigravityLeaseSelection.ts — selection glue: reserve, routing descriptor,
  release-from-credentials
• tests/unit/antigravity-routing-state.test.ts, tests/unit/antigravity-lease-lifecycle.test.ts,
  tests/unit/antigravity-account-lease-flag.test.ts
• changelog.d/fixes/10011-antigravity-account-lease.md

Modified

• src/sse/services/auth.ts — acquire on selection, release on every path that abandons the
  selected connection (+20 lines)
• src/sse/handlers/chat.ts — opt-in option, POOL_BUSY handling, hold-through-stream (+35 lines)
• src/shared/utils/featureFlags.ts, src/shared/constants/featureFlagDefinitions.ts — the flag
• open-sse/utils/error.ts — antigravity_pool_busy added to SAFE_PUBLIC_ERROR_IDENTIFIERS
• docs/reference/FEATURE_FLAGS.md — catalog row + counts (72 → 73, Runtime 32 → 33)
• tests/unit/feature-flags-settings.test.ts, tests/unit/server-owned-tool-loop-flag.test.ts —
  flag-count assertions 72 → 73
• config/quality/file-size-baseline.json — see "Honest reds" below

Fail-on-tip proof

Every new test file was copied into a throwaway detached worktree at the pristine tip
(origin/release/v3.8.51, a2c6f71) and run there.

$ git worktree add --detach .claude/worktrees/uplift-agy-lease-probe origin/release/v3.8.51
HEAD is now at a2c6f7188d71 fix(antigravity): keep unreported quota fraction unknown (#7138)
$ cp tests/unit/antigravity-{routing-state,lease-lifecycle,account-lease-flag}.test.ts \
     ../uplift-agy-lease-probe/tests/unit/
$ cd ../uplift-agy-lease-probe
$ DATA_DIR=$(mktemp -d) node --import tsx/esm --test --test-force-exit \
    tests/unit/antigravity-routing-state.test.ts \
    tests/unit/antigravity-lease-lifecycle.test.ts \
    tests/unit/antigravity-account-lease-flag.test.ts

✖ ANTIGRAVITY_ACCOUNT_LEASE_ENABLED is a runtime boolean flag that defaults to OFF (4.204845ms)
  AssertionError [ERR_ASSERTION]: ANTIGRAVITY_ACCOUNT_LEASE_ENABLED should exist
    actual: undefined,
    expected: true,
✖ the flag reader is off by default and fails closed (0.682659ms)
  TypeError: isAntigravityAccountLeaseEnabled is not a function
✖ POOL_BUSY is a structured, sanitized 503 with a bounded positive Retry-After (0.933257ms)
  TypeError: chat.buildAntigravityPoolBusyResponse is not a function
✖ antigravity_pool_busy survives the public error-identifier projection (3.457112ms)
  AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
    actual: 'service_unavailable',
    expected: 'antigravity_pool_busy'
✖ tests/unit/antigravity-lease-lifecycle.test.ts (507.992476ms)
✖ tests/unit/antigravity-routing-state.test.ts (504.310104ms)
ℹ tests 5   ℹ pass 0   ℹ fail 5

Being explicit about what kind of failure each one is, because it matters:

• antigravity_pool_busy survives the public error-identifier projection is a behavioural
  failure against a module that already exists on the tip: buildErrorBody in
  open-sse/utils/error.ts returns service_unavailable there and
  antigravity_pool_busy here. This is the one that proves a real behaviour change.
• ANTIGRAVITY_ACCOUNT_LEASE_ENABLED is a runtime boolean flag that defaults to OFF is also
  behavioural against an existing module — the key is absent from the tip's
  FEATURE_FLAG_DEFINITIONS.
• The other four fail because the symbol or the module does not exist on the tip
  (TypeError: … is not a function, and two whole files failing at import). These are
  import/missing-export failures, not behavioural ones — the modules under test are the
  feature, so no behavioural assertion against them is possible on the tip. Stating that
  plainly rather than counting them as behavioural proof.

On this branch all three files pass: ℹ tests 18 · ℹ pass 18 · ℹ fail 0.

Gate results

All run inside the worktree with DATA_DIR=$(mktemp -d).

Gate	Result
npm run typecheck:core	PASS — no output, exit 0
node scripts/check/check-api-typecheck.mjs	FAIL — inherited base-red, verified on the pristine tip. See below.
npm run check:open-sse-typecheck	PASS — openSseTypecheckErrors=0, all within frozen baseline
scoped tsc (strictNullChecks) over the 6 touched src/sse + src/shared files	PASS — 50 pre-existing errors, byte-identical error set to the pristine tip; 0 new
npm run lint	no lint errors, but exit 2: There are suppressions left that do not occur anymore. See "Honest reds".
node scripts/check/check-file-size.mjs	3 violations, all inherited base-reds (see below)
node scripts/check/check-complexity.mjs	PASS — 2841 violations vs baseline 3218
node scripts/check/check-cognitive-complexity.mjs	PASS — 1284 violations vs baseline 1437
node scripts/check/check-changelog-integrity.mjs	PASS — no base bullets lost vs origin/release/v3.8.51
npm run check:cycles	PASS — no cycles across 434 files
npm run check:docs-all	PASS — doc-links 1123 links, no broken; fabricated-docs clean. (The 89 "potential drift" warnings are pre-existing stale-date/stale-version notices in unrelated docs.)
new tests	PASS — 18/18
feature-flags-settings + feature-flags-doc-sync-static + server-owned-tool-loop-flag + auth-antigravity-account-retry-v2 + antigravity-model-aliases + pii-opt-in-default	PASS — 91/91
rule12-error-sanitization-sweep + error-sanitizer-sk-key-qv45 + route-error-sanitization-v382	PASS — 19/19
antigravity-quota-skipping + antigravity-byop-account-rotation + combo-antigravity-missing-project-reset-8486 + antigravity-missing-project-chat + repro-antigravity-404-family-cooldown-hijack	PASS — 13/13

npx prettier --check is clean on every file this PR touches.

Honest reds and one rebaseline

check-file-size — 3 inherited base-reds, unchanged by this PR:

✗ open-sse/handlers/imageGeneration.ts: 3304 > congelado 3293
✗ open-sse/services/combo/roundRobinCombo.ts: 1221 > congelado 1213
✗ open-sse/utils/stream.ts: 3115 > congelado 3098

None of those files is touched here.

check-file-size — one rebaseline I did make, deliberately: src/sse/handlers/chat.ts
2498 → 2533 (+35) and src/sse/services/auth.ts 3557 → 3577 (+20), with a
_rebaseline_2026_09_16_10011_antigravity_account_lease justification key next to the existing
_rebaseline_* entries. The lease registry, its lifecycle glue and its selection glue were all
extracted into three new modules precisely to keep the growth down to the call sites; what
remains in chat.ts and auth.ts is the wiring itself, which cannot be lifted out of the
selection loop and the dispatch path. Every added hunk there is inert unless the flag is on.
Flagging this prominently rather than burying it — it is a ratchet loosening and reviewers
should weigh it.

Base-green at the time of writing: no open 🔴 Release branch not green: release/v3.8.51 issue,
and no open release-freeze.

---

CI follow-up (first run on this PR)

Two red checks landed on the first CI run. Both investigated; one was mine and is fixed, the
other is an inherited base-red proven on the pristine tip.

1. API Route Typecheck — one real regression, fixed in f288786

✗ src/lib/providerModels/modelDiscovery.ts TS2345 (baseline 0, live 1)
✗ src/sse/services/auth.ts TS2339 (baseline 0, live 1)

src/sse/services/auth.ts was mine. The discriminated-union return type of
reserveAntigravityLeaseForSelection did not narrow under tsconfig.typecheck-api.json, so
reserved.lease after the reserved.busy early return raised
TS2339: Property 'lease' does not exist on type …. Fixed by flattening the return type to a
single optional-property shape ({ busy?: …; lease?: … }), which carries the same information
and type-checks everywhere. Verified gone locally.

src/lib/providerModels/modelDiscovery.ts is not mine — and neither is the gate's red
overall. Run on a throwaway detached worktree at the pristine tip:

$ git worktree add --detach .claude/worktrees/agy-probe2 origin/release/v3.8.51
$ cd .claude/worktrees/agy-probe2
$ DATA_DIR=$(mktemp -d) node scripts/check/check-api-typecheck.mjs
apiTypecheckErrors=289
[api-typecheck] 1 baselined error(s) no longer present …
  - src/app/api/combos/test/route.ts TS2339 (baseline 1 -> live 0)
[api-typecheck] FAIL — 1 new/regressed TypeScript error(s) under src/app/api/ not covered by the frozen baseline:
  ✗ src/lib/providerModels/modelDiscovery.ts TS2345 (baseline 0, live 1)

So API Route Typecheck is red on release/v3.8.51 itself. Not fixed here — a base-red fix is
its own freeze-gated PR.

2. All four Unit Tests fast-path shards + Fast Quality Gates — inherited base-reds

The base branch fails these five jobs on its own, with no PR involved. release/v3.8.51's
most recent quality.yml run before this PR existed — run 35127867599, commit 6f26cf27b,
2026-09-16 17:23Z — fails on exactly:

$ gh api repos/diegosouzapw/OmniRoute/actions/runs/35127867599/jobs --paginate \
    --jq '.jobs[] | select(.conclusion=="failure") | .name'
Fast Quality Gates
Unit Tests fast-path (4/4)
Unit Tests fast-path (3/4)
Unit Tests fast-path (2/4)
Unit Tests fast-path (1/4)

The same five jobs, and the last five quality.yml runs on that branch (back to 2026-09-15) are
all failure. The 15 distinct failing tests on the base include reasoning-effort clamping, the
context_management 400 retries, the authz pipeline, the raw-NUL-byte scan, the budget card and
the shared-set-size case — none of which this PR touches.

Test-by-test, and the three-test gap

This PR's shards fail 18 distinct tests; the base run failed 15. The three extra are:

#2331 codex.ts still prioritizes modelEffort first in rawEffort chain
OAuthModal renders the structured panel instead of the generic error step
direct translation calls have English messages

They are not from this PR — the base moved on. The base run above is commit 6f26cf27b,
while this PR is tested against the newer tip (5acac80, #13328), which picked these up in
between. Run on a pristine detached worktree at that current tip:

$ git worktree add --detach .claude/worktrees/agy-probe4 origin/release/v3.8.51
5acac8021d18 fix(redis): namespace warmup circuit-breaker keys with REDIS_KEY_PREFIX (#13328)
$ DATA_DIR=$(mktemp -d) node --import tsx/esm --import ./open-sse/utils/setupPolyfill.ts \
    --import ./tests/_setup/isolateDataDir.ts --test --test-force-exit \
    tests/unit/codex-effort-alias-priority.test.ts tests/unit/settings-i18n-keys.test.ts \
    tests/unit/oauth-lan-loopback-guidance.test.ts
✖ #2331 codex.ts still prioritizes modelEffort first in rawEffort chain (8.68071ms)
✖ OAuthModal renders the structured panel instead of the generic error step (11.405301ms)
✖ direct translation calls have English messages (822.370523ms)
ℹ tests 27 · ℹ pass 24 · ℹ fail 3

All three fail on the pristine tip, with no change of mine present. Every one of the 18 is
inherited; this PR adds none.

The one I dug into individually

✖ getProviderCredentials refuses a forced pin outside allowedConnections instead of falling back (#12080)
  AssertionError: actual: { blockedByKeyPolicy: true, blockedCount: 1 }, expected: null
  at tests/unit/sse-auth.test.ts:772

Nothing to do with the lease (no Antigravity, no lease code on that path). Same file, run on
both trees:

Tree	Result
pristine tip (agy-probe2, origin/release/v3.8.51)	ℹ tests 67 · ℹ pass 66 · ℹ fail 1 — same test, same assertion
this branch	ℹ tests 67 · ℹ pass 66 · ℹ fail 1 — identical

Byte-identical failure on both. Inherited — and it is one of the 15 already failing on the base.

3. npm run lint — zero errors, exit 2 on unused suppressions

The full local run reports no lint violations but exits 2 with:

There are suppressions left that do not occur anymore. To resolve this, re-run the command
with `--prune-suppressions` to remove unused suppressions.

Targeted npx eslint over every file this PR touches is clean:
src/sse/services/antigravityRoutingState.ts, antigravityLeaseLifecycle.ts,
antigravityLeaseSelection.ts, the three new test files, src/shared/utils/featureFlags.ts and
src/shared/constants/featureFlagDefinitions.ts produce no output at all;
src/sse/handlers/chat.ts, src/sse/services/auth.ts and open-sse/utils/error.ts produce only
pre-existing no-unused-vars errors on imports this PR never touched (lines 17/24/42/96/148/152
of chat.ts, etc.) — all frozen in eslint-suppressions.json, which is why npm run lint reports
zero.

Resolved by CI: the No new ESLint warnings job passed (41m26s,
actions/runs/35166430414/job/105028667750). The local exit 2 is stale-suppression drift
inherited from the base, not anything this diff introduced.

Base-red note

⚠️ base-red inherited — API Route Typecheck and the sse-auth.test.ts #12080 case are both
red on release/v3.8.51 itself, verified above. There is no open
🔴 Release branch not green: release/v3.8.51 issue to reference at the time of writing, so no
issue number is cited; the nightly has not caught these yet.

[diegosouzapw]

Validated in local merge-train /tmp/mt-train3b.log on 192.168.0.113 @ train tip 408e2128791696a18966681953136fc96aeb99b0 (32 PRs boarded): static gates green; full test:unit 40694 tests, 17 failing — every one reproduces on the pure release tip (base-red sweep list), zero new reds. Merged --admin per merge-gates §4/§7.

[diegosouzapw]

Validated in local merge-train /tmp/mt-train3b.log on 192.168.0.113 @ 408e2128 (full test:unit 40694, 17 failing all inherited). Re-synced afterwards: the only delta is config/quality/file-size-baseline.json (JSON merge + ceilings re-derived: auth.ts 3582 own growth; base.ts 1754 absorbs the train-3b tip drift). Merged --admin per merge-gates §5 (one-green-run rule, baseline-only re-sync).

[Ardem2025]

Thanks for carrying this forward and for the credit, @diegosouzapw! Glad to see the Antigravity account stream leasing landed in release/v3.8.51. Appreciate the smooth integration.