[nissa-seru]

Requests an MCPL server sends while its plane is paused now have a budget of 10,000, counted apart from notifications. Past it, a new request is answered at once with -32000, and notifications keep their own cap of 1,000. !Fixes #387.

Problem

While a plane is paused (a startup, a reconnect, an awareness drain, a quiesce), the connection holds what a server sends until the plane opens. #122's cap of 1,000 bounded only responder-less events. Every request was held past it, on the theory that a server times out and reconnects. A server that pipelines requests without waiting for their answers never times out, and each held request keeps its params and its responder, so the memory they took grew without bound. In a probe on main 91e70eda, all 5,000 push/event requests of 10 KB sent while the plane was paused were held, none was answered, and the heap grew by 73 MB.

The cap also counted held requests toward the notifications' 1,000. With 1,000 or more requests held, each new notification evicted an older one, or was dropped itself when none was held.

Changes

• A budget of 10,000 held requests (MAX_HELD_REQUESTS). Past it, the connection answers a new request at once with -32000, "the host is busy: 10000 of this server's requests are already waiting; send this one again later", and doesn't hold it. -32000 is the code of the host's other transient refusals, such as "the host is stopping".
• The cap of 1,000 (MAX_HELD_NOTIFICATIONS) counts held notifications only. When 1,000 are held, the oldest makes room for a new one, as before.
• A count of held requests, which both bounds read. ready() and readyControlPlane() zero it as they take what's held. What they hold again while they re-emit it counts toward the bounds like any arrival.
• Each pause's first refusal, and every hundredth after it, is logged: [mcpl] <server>: held-request budget (10000) — refused <n> request(s) with -32000 while the plane is paused, beside the drops' line. The count starts again when the planes open.
• hasResponder, the request predicate, is now a static method.
• fix(mcpl): contain inbound request handler failures #208's test of a request form held at the cap (test/mcpl-request-handler-errors.test.ts) counted the request toward the 1,000. Its request is counted apart now, so of its 1,100 notifications 100 are dropped rather than 101, and the flush holds 1,001.
• Changelog fragment 387-held-request-budget.fixed.md.

What each part is for

• The request budget bounds a server that pipelines requests without waiting, which is what Requests buffered while an MCPL data plane is paused have no bound #387 is about. Without it, held requests have no bound. Dropping a request instead would strand its server, which waits on it. Recycling the connection would free almost nothing, since what's held survives a reconnect, and it would cost a healthy, busy server its link. Its cost is that a server that doesn't send a refused request again loses it. Why the budget sits at 10,000 is below.
• Counting notifications apart keeps held requests from crowding notifications out. Without it, a pause holding 1,000 requests drops every notification.
• The count of held requests lets both bounds decide without scanning what's held. Counting by a scan would need no invariant, but each arrival would scan up to 11,000 held items, under exactly the flood the budget bounds. The cost is that every change to what's held must keep the count, as the field's comment says (Merge notes).
• The refusal log makes refusals visible without a line for each one.
• No guard for a flush. main kept what a flush holds again from being bounded a second time, with a flushDepth count. A flush takes everything held and zeroes the count first, so what it holds again was admitted within the bounds and stays within them, and the guard could change no outcome. It's gone, with its field and the try/finally that kept its count.

Why 10,000

A budget shared with notifications at 1,000 would turn a long pause over a busy Discord guild into lost messages for a healthy server. By our reading of discord-mcpl's source, it sends one request per Discord message and only logs a refused one. 10,000 still bounds a server that pipelines without waiting. Requests like the probe's took about 15 KB each in memory, so 10,000 of them come to about 150 MB.

What a deployment will notice

• A server past 10,000 held requests in one pause gets -32000 for each further request, where before it waited. A server that doesn't send a refused request again loses it. By that reading, discord-mcpl doesn't, so in a pause that long, the Discord messages past the 10,000th wouldn't reach the agent after the pause.
• Held requests no longer crowd notifications out. A pause holding many requests keeps up to 1,000 notifications too.

Tests

test/mcpl-held-request-budget.test.ts, on the connection's real routing with both planes closed and a push/event listener:

• The refusal test. 10,000 requests are held. The next 101 are each answered -32000 with the busy text, the host logs the lines for refusals 1 and 101, and ready() delivers the 10,000 in order.
• The notifications test. With 10,000 requests held, 1,001 notifications are held as 1,000, the oldest dropped and logged, nothing refused, and ready() delivers the newest 1,000.
• The control-plane flush test. 5,000 requests held again by readyControlPlane(), with the data plane still paused, count toward the budget: 5,000 more fill it, and the next is refused. After ready(), a new pause holds 10,000 with no refusal, and logs its own first refusal.
• The ready() flush test. A handler that pauses the data plane during ready()'s flush holds the rest of what was held again, and those count: with one held again, 9,999 more fill the budget.

Runs at ed499917, on Linux with Node 24.22.0:

• tsc --noEmit is clean. The budget file, test/mcpl-request-handler-errors.test.ts and test/mcpl-ws-transport.test.ts pass 96 of 96.

• Red-first. With main's src/mcpl/server-connection.ts at 0d19f7c8 and these tests, 5 fail: the budget file's 4, and fix(mcpl): contain inbound request handler failures #208's request-form test, which main passes as it was written.

• Each piece. Taking out each of nine pieces on its own fails at least one test:

  Piece taken out	Caught by
  the request budget	the refusal test, and both flush tests
  counting notifications apart	the notifications test, and fix(mcpl): contain inbound request handler failures #208's request-form test
  dropping the oldest notification	the notifications test, fix(mcpl): contain inbound request handler failures #208's request-form test, and the drop-count test in mcpl-ws-transport.test.ts
  the drops' log line	the same three
  logging every hundredth refusal, narrowed to the first	the refusal test
  zeroing the refusal count in ready()	the control-plane flush test
  zeroing the held count in ready()	both flush tests
  zeroing the held count in readyControlPlane()	the control-plane flush test
  counting a request held again during a flush	both flush tests

• The flush guard. The 15 test files that pause or ready a connection pass 315 of 315 at this head, and 315 of 315 with main's guard put back.

CI runs the typecheck, the build and the suite on this pull request.

Not verified

• No real server flood. The memory figures come from the probe on 91e70eda, not from a server under load, and we ran no MCPL server in the ecosystem against this.
• The bounds count messages, not bytes. A single huge line is bounded only by the transport (WebSocket's maxPayload; stdio has no limit), and that's outside this change.
• Dropping the oldest notification at the cap still finds it by scanning from the front of what's held, past any held requests: up to 10,000 of them for each notification when the budget is full too. Before this change held requests had no bound, so that scan had none either.

Merge notes

• feat(awareness): make Discord awareness marks an explicit, one-shot choice that never gates MCPL #250 filters what's held at a transport boundary. It already conflicts with main in src/mcpl/server-connection.ts, and with this change those conflicts also hold the held-request count, which their resolution has to recount after feat(awareness): make Discord awareness marks an explicit, one-shot choice that never gates MCPL #250's filter.

---

• Changelog fragment added — changelog.d/387-held-request-budget.fixed.md

Written by Tabitha-2696 (Claude Opus 5.5), contributing through nissa-seru. Ada-1017 made the design calls, the budget of 10,000 among them. Our internal review read the first commit, and its findings are in the second. Ansel-2428 (Claude Opus 5.5) reviewed it, and read it again after its rebase onto main, the flush guard's removal included.

🤖 Written with Claude Opus 5.5 through the Rookery's Pi tooling.

Description checked and posted by Fiona-2757 (Claude Opus 5.5).

[greptile-apps]

Required label not found on this PR.