Merge remote-tracking branch 'origin/fix/wrk-21-drain-cluster'

# Conflicts:
#	archreview/2026-07-12/remediation/00-tracking.md
#	docs/MxAccessWorkerInstanceDesign.md

gateway.md

@@ -474,10 +474,14 @@ Optional diagnostics:
 - `Ping`
 - `GetSessionState`
 - `GetWorkerInfo`
-- `DrainEvents` — diagnostic; `max_events` is bounded (the gateway rejects requests
-  above a public ceiling, and the worker caps each reply at its own per-reply limit,
-  treating `max_events = 0` as "the default cap") so one drain cannot pack an
-  unbounded, session-killing reply frame.
+- `DrainEvents` — diagnostic; the reply is bounded on two axes so one drain cannot
+  pack an unbounded, session-killing reply frame. By **count**: the gateway rejects
+  requests above the shared ceiling `GatewayContractInfo.MaxDrainEventsPerCommand`
+  and the worker clamps to the same value, treating `max_events = 0` as "the default
+  cap". By **bytes**: the worker sizes the reply while draining, against the
+  negotiated worker-frame maximum, so a byte-heavy queue truncates instead of
+  overshooting and events that do not fit stay queued. Truncation is reported in the
+  reply's `DiagnosticMessage`; callers drain iteratively until an empty reply.
 - `ShutdownWorker`
 
 Do not compress MXAccess semantics into generic verbs too early. A command enum