Skip to content

fix(mcp-gateway): cap the initialize-deadline reap memory and key it by a digest - #39878

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
crew/slack/deadline-reaps-cap
Nov 20, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
crew/slack/deadline-reaps-cap

Conversation

@buluoray

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: The gateway's memory of initialize-deadline reaps stays bounded, whatever pool keys callers send.

#39546 added Admission._deadline_reaps, a dict keyed by the raw pool key. A key that is reaped and never becomes ready is never removed. The pool key comes from the stub's register frame, so a caller chooses both how many keys there are and how large each one is. A review lane on the 0.13 pick (#39598) flagged this as unbounded growth.

Why it matters

The gateway is a long-lived daemon. A leak that only grows, keyed by caller input, slowly costs memory for the life of the process.

Not a goal

What changed (motivation → approach → change)

Admission._deadline_reaps now stores a fixed-size SHA-256 digest of the pool key instead of the key itself. It holds at most INIT_DEADLINE_REAP_KEYS_MAX (256) keys. A new reap moves its key to the newest place; past the cap the key reaped longest ago is dropped first. A dropped key just gets the configured deadline again on its next spawn, as if it had never been reaped.

Backwards compatibility

Compatible: under 256 reaped keys nothing changes. Past that, the oldest key falls back to today's first-spawn deadline.

Removes nothing: no setting, field or output goes away.

Tests

test/test_mcp_gateway_spawn_gate.py::TestAcquireBackendOrder::test_reaped_keys_that_never_come_back_ready_are_capped reaps 261 keys of over 4 KB each that never become ready. The dict ends at 256 entries, each a 64-character digest; the 5 oldest keys are back at the configured deadline and the newer ones are still stretched.

Proof: not provable -- other: prove.py reverts the admission.py hunks together, which removes the new constant and errors the test before any assertion; turning only the eviction loop into while False: turns the test red on assert len(admission._deadline_reaps) == cap.

Determinism: the new test passed 20 of 20 runs alone with -n0, and the whole file passes with -n4. All 84 test/test_mcp_gateway*.py files pass (2461 passed). test/test_flake_pattern_ratchet.py, flake8, isort, mypy and the repo semgrep rules pass.

Manual verification

N/A -- the change is an in-memory bound inside Admission; the unit test drives the real track_initialize and initialize_timeout_for.

Real-machine verification

N/A -- no user-visible behavior changes below 256 reaped keys, and reaching the cap on a real machine needs 256 distinct slow servers; the unit test covers the bound directly.

Related Issues

Part of #30915

Sibling sweep

Swept: git grep -n "_deadline_reaps" -- src/
Sibling: src/kiro_crew/mcp_gateway/admission.py:609 -- changed here

Pattern harvest

Not generalizable: other per-key gateway state (the pool's backends, spawn locks) is already bounded by the pool's capacity and reaped with the backend; this dict was the one that outlived its backend.

Checklist

  • A Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...); PR Hygiene does not count commits
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@buluoray
buluoray requested review from a team and KiroCrewCaptain as code owners November 20, 2026 08:40
@buluoray
buluoray requested a review from bolichen97 November 20, 2026 08:40
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 20, 2026
@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision a50fdf393362ee23b3bafa4dfcb207c0bbb9945b touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of a50fdf393362ee23b3bafa4dfcb207c0bbb9945b — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing to check.

What this change ships

Inventory (4 items) — 4 justified

Intent: keep the long-lived gateway's memory of initialize-deadline reaps from growing with caller-chosen pool keys. FIX.

  1. The gateway remembers at most 256 reaped pool keys and forgets the one reaped longest ago first — justified
  2. Reaped keys are stored as fixed-size SHA-256 digests, not the raw caller-supplied key — justified
  3. A key reaped again moves to the newest position, so it is evicted last — justified
  4. A test that reaps 261 keys over 4 KB each and checks the cap, the digest size and the eviction order — justified

[FIRST-PRINCIPLES-REVIEWED] a50fdf3

Description read

[DESCRIPTION-READ] 0aa1612e724149086b02dd2d95c46880809199777e36179ea3d3a824517f6c5e

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of a50fdf393362ee23b3bafa4dfcb207c0bbb9945b — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks. The change is a small, reversible in-memory cap with LRU-by-reap eviction, and it takes nothing away.

Notes

  • Once the 256-entry cap is in place, the SHA-256 digest only matters if a single register frame can carry an arbitrarily large key. If the frame size is already bounded, keying by the raw key under the cap would be enough, and initialize_timeout_for would no longer need to hash repr(key) on every call.

[DESIGN-REVIEWED] a50fdf3

Description read

[DESCRIPTION-READ] 918523760333078ca6653da9fd7ccb429d5c33e564e9f4bbee424ac3eeb6046c

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed a50fdf393362ee23b3bafa4dfcb207c0bbb9945b — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] a50fdf3

Verdict parsed from the review's SHA-scoped output markers for commit a50fdf393362ee23b3bafa4dfcb207c0bbb9945b.

False positive or not applicable? A repository writer can comment:
/ai-review override fable a50fdf393362ee23b3bafa4dfcb207c0bbb9945b false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of a50fdf393362ee23b3bafa4dfcb207c0bbb9945b and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] a50fdf3

False positive or not applicable? A repository writer can comment:
/ai-review override gpt a50fdf393362ee23b3bafa4dfcb207c0bbb9945b false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 20, 2026
@buluoray
buluoray force-pushed the crew/slack/deadline-reaps-cap branch from 906cba2 to a50fdf3 Compare November 20, 2026 10:16
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention labels Nov 20, 2026
@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) November 20, 2026 11:41

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved. On this head the review checked these things. Both gateway callers hand the same PoolKey to track_initialize and initialize_timeout_for. PoolKey is a frozen dataclass, so its repr digest is stable and equal keys share one slot. The pop and reinsert, the eviction and the ready clear run with no await between them. The 256 cap and the 64-character digest also bound per-entry size, which matters because a register frame can be up to 64 MiB. Mutations of the digest, the eviction bound and the ready arm each turn a test red. PR Readiness is green.

Done well: one pop and reinsert makes dict order equal reap order, so the oldest-first eviction is a two-line loop with no new structure. The test drives the real seams with 4 KB keys.

Optional:

  • Pin the move-to-newest step. Reap keys[0] a second time before the overflow, then assert it stays stretched while keys[1] is forgotten. Today a .get() in place of .pop() at admission.py:643 keeps every test green.
  • Look up with a freshly built equal key (for example, a new PoolKey.from_register(...)). That pins value equality of the slot, not object identity.
  • Consider keying by the existing PoolKey.stable_hash() instead of a second digest helper. Also consider one log line when an entry is evicted past the cap.

Note: release/0.13.0's pick #39598 still carries the unbounded dict, so it needs its own pick of this bound.

@KiroCrewCaptain
KiroCrewCaptain merged commit e77a3e5 into main Nov 20, 2026
98 of 101 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the crew/slack/deadline-reaps-cap branch November 20, 2026 11:41
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 20, 2026
buluoray added a commit that referenced this pull request Nov 20, 2026
buluoray added a commit that referenced this pull request Nov 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants