mandala-computer-mcp 0.7.0 → 0.9.0

package/dist/http.js

@@ -7,7 +7,7 @@ import express, {} from 'express';
 import { Api, MODEL_KEY_HEADER } from './api.js';
 import { APIError } from './errors.js';
 import { MeteredBody } from './http-body.js';
-import { SSH_KEYS } from './paths.js';
+import { WHOAMI } from './paths.js';
 import { createServer, SERVER_NAME, SERVER_VERSION } from './server.js';
 import { toolFilter } from './tool-filters.js';
 /** The OAuth scope the hosted resource asks for. */
@@ -66,7 +66,28 @@ const DEFAULT_TTL_MS = 30 * 60 * 1000;
  * any string gets that far; without a cap, a loop of initializes is a memory
  * exhaustion that costs the sender nothing.
  */
-const DEFAULT_MAX_SESSIONS = 256;
+export const DEFAULT_MAX_SESSIONS = 256;
+/**
+ * A ceiling on live sessions per bearer, under the one above.
+ *
+ * The process-wide cap bounds memory, but on its own it is a pool one caller
+ * can drain: a single accepted bearer could open every one of the 256 sessions
+ * and every other tenant's initialize was 503'd until the sweep, half an hour
+ * later. 16 leaves room for one person running several MCP clients on one key
+ * and still leaves the pool to everybody else.
+ *
+ * A suspended account's bearer is admitted (OPL-5437: it is how its holder
+ * reaches `whoami` and learns it is suspended), and one session is all that
+ * needs. Every other call it could make is refused by the platform. One
+ * session for the ACCOUNT, however many keys or tokens it holds (OPL-5452):
+ * see `standing` in {@link runHttp}.
+ */
+const DEFAULT_MAX_SESSIONS_PER_BEARER = 16;
+const MAX_SESSIONS_SUSPENDED = 1;
+/** How long a caller whose bearer holds its maximum is asked to wait, in s. */
+const BEARER_FULL_RETRY_AFTER_S = 30;
+/** How long a caller is asked to wait when the whole pool is full, in s. */
+const POOL_FULL_RETRY_AFTER_S = 30;
 const DEFAULT_MAX_LARGE_BODY_PARSES = 4;
 const SMALL_BODY_BYTES = 256 * 1024;
 /**
@@ -212,64 +233,122 @@ export async function runHttp(cfg) {
     const checkTtl = cfg.bearerCheckTtlMs ?? DEFAULT_BEARER_CHECK_TTL_MS;
     const accepted = new Map();
     let checksInFlight = 0;
-    /** Whether the platform accepted this bearer within the cache window. */
-    const isAccepted = (key) => {
-        const until = accepted.get(digest(key).toString('hex'));
-        return until !== undefined && until > Date.now();
+    const standing = new Map();
+    let probeSeq = 0;
+    /** Whether the latest answer about this account says it is suspended. */
+    const accountSuspended = (account) => standing.get(account)?.suspended === true;
+    /** Take a probe's answer for its account, unless a newer-started one answered already. */
+    const noteStanding = (account, suspended, seq) => {
+        const known = standing.get(account);
+        if (known && known.seq >= seq)
+            return;
+        // Re-inserted, so Map order is the order answers were taken in.
+        standing.delete(account);
+        if (standing.size >= MAX_ACCEPTED_BEARERS) {
+            // An account holding no session needs no answer kept: a later request
+            // or initialize for it finds none and asks again.
+            const holding = new Set();
+            for (const live of sessions.values())
+                holding.add(live.account);
+            for (const k of standing.keys())
+                if (!holding.has(k))
+                    standing.delete(k);
+            if (standing.size >= MAX_ACCEPTED_BEARERS) {
+                standing.delete(standing.keys().next().value);
+            }
+        }
+        standing.set(account, { suspended, seq });
+    };
+    /** The platform's acceptance of this bearer, while the cache window lasts. */
+    const acceptance = (key) => {
+        const entry = accepted.get(digest(key).toString('hex'));
+        return entry !== undefined && entry.until > Date.now() ? entry : undefined;
     };
+    /** Whether the platform accepted this bearer within the cache window. */
+    const isAccepted = (key) => acceptance(key) !== undefined;
     /**
      * `ok`: the probe answered 2xx, and only that — the one answer that says the
-     * platform authenticated this credential AND let it act. `refused`: a 401.
-     * `unknown`: anything else — a 403 (a suspended account or a lost
-     * membership), a 404 (the route moved), a 429, a 5xx, a timeout, or this
+     * platform authenticated this credential AND let it act. `suspended`: the
+     * same 2xx, for an account whose standing says `status: "suspended"` —
+     * admitted as `ok` is, and held to one session in all. `refused`: a 401.
+     * `unknown`: anything else — a 403 (a lost membership, say; a suspended
+     * account is answered 2xx on whoami and admitted), a 404 (the route moved), a 429, a 5xx, a timeout, or this
      * server already asking about as many bearers as it will at once. Only `ok`
-     * is cached.
+     * and `suspended` are cached: the account key with the acceptance, the
+     * standing per account. `account` is the account key the bearer counts against (see
+     * {@link accountKey}); it is set whenever the verdict is `ok` or
+     * `suspended`, and returned rather than read back from the cache, which a
+     * zero TTL or a full cache may already have let go of. `workspace` is the
+     * workspace key (see {@link workspaceKey}), returned the same way, when
+     * whoami named a workspace for an account it named (OPL-5453).
      */
     // `onStart` runs only when a probe really starts — never for a cached answer
     // or a full cap — and synchronously, before the first await, so a caller's
     // bookkeeping and its check against it cannot interleave with another's.
+    //
+    // `ok` and `suspended` are the account's STANDING when this returns, which
+    // a newer-started probe of another of its bearers may have set, not what
+    // this bearer's own probe (or cached acceptance) said (OPL-5452).
     const checkBearer = async (key, onStart) => {
         const id = digest(key).toString('hex');
-        if (isAccepted(key))
-            return 'ok';
+        const cached = acceptance(key);
+        // Believed only while its account has a standing to read (see above).
+        if (cached && standing.has(cached.account)) {
+            return {
+                verdict: accountSuspended(cached.account) ? 'suspended' : 'ok',
+                account: cached.account,
+                workspace: cached.workspace,
+            };
+        }
         if (checksInFlight >= MAX_BEARER_CHECKS_IN_FLIGHT)
-            return 'unknown';
+            return { verdict: 'unknown' };
         checksInFlight++;
+        // Numbered as it starts, before the first await: see `standing`.
+        const seq = ++probeSeq;
         onStart?.();
+        let suspended;
+        let confirmed;
+        let workspaceId;
         try {
             const api = new Api(key, cfg.baseUrl, AbortSignal.timeout(BEARER_CHECK_TIMEOUT_MS), {
                 serviceSecret,
             });
-            // `GET ssh-keys`, chosen because it is the cheapest read that every
-            // valid credential is answered 2xx on. The platform's route table
-            // gives it the lowest role there is (viewer), a workspace-scoped key is
-            // refused only the key WRITES, and the handler lists the caller's own
-            // keys from the control plane without asking any host — so no role a
-            // grant can carry, and no host being down, turns it into a refusal.
-            // `account` is the alternative and costs two fleet inventories. The one
-            // valid credential it does not admit is a suspended account's (403),
-            // which is answered as unconfirmed. It takes no parameters, so none are
-            // sent.
-            await api.json('GET', SSH_KEYS);
+            // `GET whoami`, chosen because every valid credential is answered 2xx
+            // on it, a suspended account's included. The platform's route table
+            // gives it the lowest role there is (viewer) and marks it readable by a
+            // suspended account, and the handler answers from the control plane's
+            // own tables without asking any host — so no role a grant can carry, no
+            // workspace scope, no account standing and no host being down turns it
+            // into a refusal. It was `GET ssh-keys`, which a suspended account is
+            // refused (403): its holder was answered 503 on every initialize and so
+            // could never reach whoami, the one tool that would say it is suspended
+            // (OPL-5437). It takes no parameters, so none are sent.
+            const who = await api.json('GET', WHOAMI);
+            suspended = isSuspended(who);
+            confirmed = accountIdOf(who);
+            workspaceId = workspaceIdOf(who);
         }
         catch (err) {
-            return err instanceof APIError && err.status === 401 ? 'refused' : 'unknown';
+            return { verdict: err instanceof APIError && err.status === 401 ? 'refused' : 'unknown' };
         }
         finally {
             checksInFlight--;
         }
         const now = Date.now();
         if (accepted.size >= MAX_ACCEPTED_BEARERS) {
-            for (const [k, t] of accepted)
-                if (t <= now)
+            for (const [k, e] of accepted)
+                if (e.until <= now)
                     accepted.delete(k);
             // Still full: drop the oldest, which Map iteration yields first.
             if (accepted.size >= MAX_ACCEPTED_BEARERS) {
                 accepted.delete(accepted.keys().next().value);
             }
         }
-        accepted.set(id, now + checkTtl);
-        return 'ok';
+        const account = accountKey(id, confirmed);
+        const workspace = workspaceKey(account, workspaceId);
+        accepted.set(id, { until: now + checkTtl, account, workspace });
+        noteStanding(account, suspended, seq);
+        return { verdict: accountSuspended(account) ? 'suspended' : 'ok', account, workspace };
     };
     // Refused initializes per source, in fixed one-minute windows. Kept apart
     // from the session cap so a flood of invented tokens is turned away before
@@ -350,6 +429,50 @@ export async function runHttp(cfg) {
     // the same `sessions.size`, all of them pass, and the cap bounds nothing —
     // which is the exact memory exhaustion it was put here to stop.
     let pending = 0;
+    // The same reservations again, per bearer digest (hex), for the per-bearer
+    // cap and for the same reason: a burst of initializes from one bearer would
+    // otherwise all count the same sessions and all pass. An entry is deleted
+    // when it reaches zero, so the map holds only bearers mid-initialize.
+    const pendingByDigest = new Map();
+    // Normalised, because the cap is also arithmetic against the process-wide
+    // one: a NaN here (`Number(process.env.X)` with X unset) made every
+    // comparison below false and switched off BOTH caps, the 256 backstop
+    // included. Anything that is not a number of at least one is the default;
+    // Infinity is let through, and leaves only the process-wide cap.
+    const perBearer = cfg.maxSessionsPerBearer;
+    const maxPerBearer = typeof perBearer === 'number' && perBearer >= 1
+        ? Math.floor(perBearer)
+        : DEFAULT_MAX_SESSIONS_PER_BEARER;
+    // The same reservations per account (OPL-5447): an account may hold any
+    // number of bearers, so a burst spread across its keys would otherwise all
+    // count the same sessions and all pass the account ceiling.
+    const pendingByAccount = new Map();
+    // The ceiling no account may pass, live plus pending: a quarter of the pool
+    // by default (OPL-5454). Half let two accounts take the whole of it between
+    // them, however many others were waiting. Normalised as the per-bearer cap
+    // is, and clamped to the pool.
+    const perAccount = cfg.maxSessionsPerAccount;
+    const maxPerAccount = typeof perAccount === 'number' && perAccount >= 1
+        ? Math.min(Math.floor(perAccount), maxSessions)
+        : Math.max(1, Math.floor(maxSessions / 4));
+    // The same reservations per workspace (OPL-5453), keyed by workspace key and
+    // kept only for workspace-scoped bearers, for the same reason again.
+    const pendingByWorkspace = new Map();
+    // The sub-ceiling no workspace may pass under its account's: a quarter of
+    // the account's ceiling by default, the EFFECTIVE one, so raising only the
+    // account ceiling raises this with it. Normalised likewise, and clamped to
+    // the account ceiling, which holds a workspace whatever this says.
+    const perWorkspace = cfg.maxSessionsPerWorkspace;
+    const maxPerWorkspace = typeof perWorkspace === 'number' && perWorkspace >= 1
+        ? Math.min(Math.floor(perWorkspace), maxPerAccount)
+        : Math.max(1, Math.floor(maxPerAccount / 4));
+    // The last quarter of the pool, kept for accounts holding less than their
+    // share of the rest (OPL-5454; see the initialize's admission). None in a
+    // pool under 4. Not configurable. The share is taken of the UNRESERVED part:
+    // of the whole pool, a lone account would always hold less than its share
+    // and could take the reserve too, which would then protect nobody.
+    const poolReserve = Math.floor(maxSessions / 4);
+    const unreserved = maxSessions - poolReserve;
     // Two parsers, chosen by whether this server has already checked who is
     // asking.
     //
@@ -587,21 +710,223 @@ export async function runHttp(cfg) {
      * exists for, a laptop that slept and left the socket half-open, is exactly
      * the one where `close` never fires to undo the count. The transport and its
      * fully-registered server would sit on a `maxSessions` slot forever.
+     *
+     * `heard` says whether this traffic may stamp the session as heard from; it
+     * is asked at the start and again at the end. Only `active` is unconditional,
+     * so a session with work in flight is never swept whatever `heard` says.
      */
-    const beginActivity = (live) => {
+    const beginActivity = (live, heard = always) => {
         live.active++;
-        live.lastSeen = Date.now();
+        if (heard())
+            live.lastSeen = Date.now();
         let held = true;
         return () => {
             if (!held)
                 return;
             held = false;
             live.active--;
-            live.lastSeen = Date.now();
+            if (heard())
+                live.lastSeen = Date.now();
         };
     };
-    const serving = async (live, handle) => {
-        const release = beginActivity(live);
+    /**
+     * Whether traffic on this bearer that carries no request may keep its
+     * session from idling out (OPL-5455). Hosted, only while the platform's
+     * acceptance of the bearer is still cached: a notification, a response or
+     * the standing stream never asks the platform, so without this a revoked
+     * token's holder could keep its sessions (and its account's ceiling) held
+     * for ever by sending nothing but those. Once the acceptance lapses and no
+     * request renews it, they idle out after the session TTL. A cache peek, never
+     * a probe. Self-hosted: always.
+     */
+    const heardWhileAccepted = (key) => challenge ? () => isAccepted(key) : always;
+    /** The live sessions opened with this bearer, by its digest. */
+    const sessionsOf = (keyDigest) => {
+        const own = [];
+        for (const entry of sessions) {
+            const theirs = entry[1].keyDigest;
+            if (theirs.length === keyDigest.length && timingSafeEqual(theirs, keyDigest))
+                own.push(entry);
+        }
+        return own;
+    };
+    /**
+     * The live sessions counted against this account, whichever bearer opened
+     * them. One whose bearer the platform has refused is included: it holds its
+     * transport and its slot in the pool until it is closed, so leaving it out
+     * would let an account that revokes its own keys hold more than its
+     * ceiling, up to the whole pool.
+     */
+    const sessionsOfAccount = (account) => {
+        const counted = [];
+        for (const entry of sessions)
+            if (entry[1].account === account)
+                counted.push(entry);
+        return counted;
+    };
+    /**
+     * The live sessions counted against this workspace key (OPL-5453; see
+     * {@link workspaceKey}), whichever bearer opened them, refused ones
+     * included for the reason {@link sessionsOfAccount} gives.
+     */
+    const sessionsOfWorkspace = (workspace) => {
+        const counted = [];
+        for (const entry of sessions)
+            if (entry[1].workspace === workspace)
+                counted.push(entry);
+        return counted;
+    };
+    /**
+     * The sessions to close so that one more fits under this bearer's cap, its
+     * account's ceiling (OPL-5447) and, for a workspace-scoped bearer, its
+     * workspace's sub-ceiling (OPL-5453), or which of them it cannot fit under:
+     * `bearer`, then `workspace`, then `account`, when more than one cannot be
+     * met.
+     *
+     * Only idle sessions (`active === 0`, what the sweeper closes) are
+     * candidates, and of two kinds. The bearer's own, which make room under
+     * whichever limit binds: its own cap, as before, or its account's ceiling.
+     * And the account's sessions of its other bearers that the platform has
+     * refused: nothing more is served on those, yet they count against the
+     * ceiling until closed, so without this a revoked key would hold its
+     * account's other keys out until the sweep. Refused ones go first, then the
+     * least recently seen. A live session of another bearer is never a
+     * candidate, and neither is anything of another account; an own session
+     * counts toward the ceiling's need only if it counts against this account,
+     * and any candidate toward the workspace's only if it counts against this
+     * workspace. A candidate is taken only if it meets a need that is still
+     * unmet.
+     *
+     * `suspended` (hosted mode, the account's standing, OPL-5452) lowers both
+     * limits to one, and makes every idle session of the account a candidate,
+     * whichever bearer opened it: a suspended account holds one session in all,
+     * and the bearer asking now (a refreshed token, say) may take it over while
+     * it is idle. One with a request in flight is still never a candidate. The
+     * workspace sub-ceiling is not applied then: the account's one session is
+     * below any sub-ceiling, and applying it could close a second session that
+     * the account's one-session limit does not need closed.
+     *
+     * `workspace` is the requester's workspace key, undefined when its bearer
+     * is not workspace-scoped. `pendingBearer`/`pendingWorkspace`/
+     * `pendingAccount` are initializes admitted and not yet landed; at landing
+     * all are 0 (see `onsessioninitialized`). The result names sessions, so
+     * nothing that outlives the call may keep it.
+     */
+    const planRoom = (keyDigest, account, workspace, suspended, pendingBearer, pendingWorkspace, pendingAccount) => {
+        const bearerCap = suspended ? MAX_SESSIONS_SUSPENDED : maxPerBearer;
+        const accountCap = suspended ? MAX_SESSIONS_SUSPENDED : maxPerAccount;
+        const own = sessionsOf(keyDigest);
+        const counted = sessionsOfAccount(account);
+        let bearerNeed = own.length + pendingBearer - bearerCap + 1;
+        let accountNeed = counted.length + pendingAccount - accountCap + 1;
+        let workspaceNeed = workspace !== undefined && !suspended
+            ? sessionsOfWorkspace(workspace).length + pendingWorkspace - maxPerWorkspace + 1
+            : 0;
+        const victims = [];
+        if (bearerNeed <= 0 && accountNeed <= 0 && workspaceNeed <= 0)
+            return { victims };
+        const mine = new Set(own.map(([id]) => id));
+        const candidates = [
+            ...own,
+            ...counted.filter(([id, live]) => !mine.has(id) && (live.refused || suspended)),
+        ]
+            .filter(([, live]) => live.active === 0)
+            .sort(closingOrder);
+        for (const entry of candidates) {
+            if (bearerNeed <= 0 && accountNeed <= 0 && workspaceNeed <= 0)
+                break;
+            const ofBearer = mine.has(entry[0]);
+            const ofAccount = entry[1].account === account;
+            const ofWorkspace = workspace !== undefined && entry[1].workspace === workspace;
+            if (!(ofBearer && bearerNeed > 0) &&
+                !(ofAccount && accountNeed > 0) &&
+                !(ofWorkspace && workspaceNeed > 0)) {
+                continue;
+            }
+            victims.push(entry);
+            if (ofBearer)
+                bearerNeed--;
+            if (ofAccount)
+                accountNeed--;
+            if (ofWorkspace)
+                workspaceNeed--;
+        }
+        if (bearerNeed > 0)
+            return { full: 'bearer', holds: own.length };
+        if (workspaceNeed > 0)
+            return { full: 'workspace' };
+        if (accountNeed > 0)
+            return { full: 'account' };
+        return { victims };
+    };
+    /**
+     * Hold a suspended account to one session in all (OPL-5452): close its idle
+     * sessions, whichever of its bearers opened them, in {@link closingOrder},
+     * until it holds one or none idle is left. Never `keep` (the session being
+     * served), and never one with a request in flight, which goes once it is
+     * idle, at the next of these. Does nothing unless the account's standing
+     * says suspended, so a self-hosted server, which has none, is untouched.
+     *
+     * A request whose body is still arriving has not reached its session yet,
+     * so its session can look idle here; for a suspended account that costs
+     * nothing, since the platform refuses every call it could make but whoami.
+     */
+    const enforceAccountSuspension = (account, keep) => {
+        if (!accountSuspended(account))
+            return;
+        const counted = sessionsOfAccount(account);
+        const excess = counted.length - MAX_SESSIONS_SUSPENDED;
+        if (excess <= 0)
+            return;
+        const idle = counted.filter(([id, live]) => id !== keep && live.active === 0);
+        idle.sort(closingOrder);
+        for (const [id, gone] of idle.slice(0, excess)) {
+            sessions.delete(id);
+            void gone.transport.close().catch(() => { });
+        }
+    };
+    /**
+     * {@link enforceAccountSuspension} for a session served under its own
+     * bearer, whose account the platform may have named only since the session
+     * was admitted: `bearerAccount` is what the bearer counts against NOW (its
+     * probe's or cached acceptance's account). A session is counted against the
+     * account key it was admitted under and is never re-keyed, so one admitted
+     * while whoami named no account sits in a `bearer:` bucket that holds no
+     * standing. When the bearer's account now differs from that and is
+     * suspended, the bearer's own idle sessions go down to one as well, on the
+     * account's standing as it is now: a newer-started probe that found the
+     * account active leaves them be.
+     */
+    const enforceSuspensionFor = (live, bearerAccount, keep) => {
+        if (bearerAccount !== undefined &&
+            bearerAccount !== live.account &&
+            accountSuspended(bearerAccount)) {
+            trimIdle(live.keyDigest, MAX_SESSIONS_SUSPENDED, keep);
+        }
+        enforceAccountSuspension(live.account, keep);
+    };
+    /**
+     * Close this bearer's idle sessions, least recently seen first, until it
+     * holds no more than `cap` or none idle is left. Never `keep`, and never one
+     * with a request in flight: the same test the sweeper and an initialize's
+     * room-making apply. Only a cap that has fallen needs this — an account
+     * suspended after its bearer opened sessions (OPL-5448) — since an
+     * initialize never admits a session over the cap it is checked against.
+     */
+    const trimIdle = (keyDigest, cap, keep) => {
+        const own = sessionsOf(keyDigest);
+        const excess = own.length - cap;
+        if (excess <= 0)
+            return;
+        const idle = own.filter(([id, live]) => id !== keep && live.active === 0);
+        idle.sort((a, b) => a[1].lastSeen - b[1].lastSeen);
+        for (const [id, gone] of idle.slice(0, excess)) {
+            sessions.delete(id);
+            void gone.transport.close().catch(() => { });
+        }
+    };
+    const serving = async (live, handle, heard = always) => {
+        const release = beginActivity(live, heard);
         try {
             return await handle();
         }
@@ -613,11 +938,16 @@ export async function runHttp(cfg) {
             release();
         }
     };
-    /** Stamp a session as heard from, without claiming anything is in flight. */
-    const touch = (live, res) => {
-        live.lastSeen = Date.now();
-        res.on('close', () => {
+    /**
+     * Stamp a session as heard from, without claiming anything is in flight, on
+     * open and on close, each only when `heard` allows it (see `beginActivity`).
+     */
+    const touch = (live, res, heard) => {
+        if (heard())
             live.lastSeen = Date.now();
+        res.on('close', () => {
+            if (heard())
+                live.lastSeen = Date.now();
         });
     };
     /**
@@ -736,6 +1066,7 @@ export async function runHttp(cfg) {
             return challenged(res, NO_TOKEN, rpcId(req));
         }
         if (sessionId) {
+            let unpin = () => { };
             try {
                 const live = sessions.get(sessionId);
                 if (!live)
@@ -758,24 +1089,67 @@ export async function runHttp(cfg) {
                     }
                     return unauthorized(res, 'This session belongs to a different API key.', rpcId(req));
                 }
+                // In flight from here, not only once it is dispatched: the bearer
+                // check below awaits the platform, for up to BEARER_CHECK_TIMEOUT_MS on
+                // a cache miss, and an initialize on the same bearer at its cap closes
+                // an idle session to make room. Counted as busy through that wait, this
+                // one is never the session closed under a request already routed to it
+                // (OPL-5443). Only `active` is raised: a request refused below has not
+                // been served, and does not stamp the session as heard from.
+                live.active++;
+                let pinned = true;
+                unpin = () => {
+                    if (!pinned)
+                        return;
+                    pinned = false;
+                    live.active--;
+                };
                 if (challenge && live.refused)
-                    return challenged(res, TOKEN_REFUSED, rpcId(req));
+                    return challenged(res, refusedMessage(key), rpcId(req));
                 // Checked before a request is dispatched, while the answer can still
                 // be a 401 whatever the call goes on to do. A platform that cannot say
                 // is not a refusal: the call goes ahead, and a real refusal during it
                 // still reaches the client through the held answer or the mark.
-                if (challenge && carriesRequest(req.body) && (await checkBearer(key)) === 'refused') {
+                const request = carriesRequest(req.body);
+                const checked = challenge && request ? await checkBearer(key) : undefined;
+                const verdict = checked?.verdict;
+                if (verdict === 'refused') {
                     live.refused = true;
-                    return challenged(res, TOKEN_REFUSED, rpcId(req));
+                    return challenged(res, refusedMessage(key), rpcId(req));
+                }
+                // An account suspended after its bearers opened sessions kept every
+                // one of them, while an initialize on it was held to one (OPL-5448).
+                // Its other idle sessions go now, whichever of its bearers opened
+                // them (OPL-5452), down to this one: it is pinned above, and one busy
+                // elsewhere is skipped and closed at a later one of these once idle.
+                // What decides is the account's standing as it is now, not the
+                // verdict above: a newer-started probe of another bearer may have
+                // found the account reinstated while this one awaited its own.
+                // A request has just had its bearer's standing confirmed (or found it
+                // cached). Anything else — a notification, a response — asks the
+                // platform nothing, so it acts on the account's standing only while
+                // its bearer's acceptance is cached: the standing is then no older
+                // than that, and never an answer from long before a reinstatement.
+                const confirmed = request ? verdict === 'ok' || verdict === 'suspended' : isAccepted(key);
+                if (challenge && confirmed) {
+                    enforceSuspensionFor(live, request ? checked?.account : acceptance(key)?.account, sessionId);
                 }
                 const lease = res.locals.largeBodyLease;
                 const id = rpcId(req);
                 const held = challenge
-                    ? holdAnswer(res, () => challenged(res, TOKEN_REFUSED, id))
+                    ? holdAnswer(res, () => challenged(res, refusedMessage(key), id))
                     : undefined;
-                return await heldAnswer.run(held, () => requestBodyLease.run(lease, () => serving(live, () => live.transport.handleRequest(req, res, req.body))));
+                return await heldAnswer.run(held, () => requestBodyLease.run(lease, () => serving(live, () => live.transport.handleRequest(req, res, req.body), 
+                // A request keeps the session as before: it was just put to
+                // the platform, or found its acceptance cached. Anything else
+                // keeps it only while that acceptance lasts.
+                request ? always : heardWhileAccepted(key))));
             }
             finally {
+                // serving() held its own lease across handleRequest, and a tool
+                // callback that outlives it holds another through activity(), so the
+                // pin can go once the route is done with the request.
+                unpin();
                 // A verified session is the only request allowed through the large
                 // parser. Release the route's ownership here; a tool callback that
                 // outlives handleRequest retains its own reference through activity().
@@ -807,6 +1181,8 @@ export async function runHttp(cfg) {
             return rpcError(res, 403, -32000, refused, rpcId(req));
         // Hosted: no session for a bearer the platform does not accept. Before the
         // cap and the reservation, so a refused bearer never holds a slot.
+        let checkedAccount;
+        let checkedWorkspace;
         if (challenge) {
             // A spent budget does not close the address. Many clients can share one
             // (a NAT, an office), and one bad neighbour must not lock out the rest:
@@ -827,7 +1203,7 @@ export async function runHttp(cfg) {
             // The interval is spent only by a probe that starts: a request turned
             // away because the process-wide cap is full reached nobody, and must not
             // make the next client at this address wait out an interval for it.
-            const verdict = await checkBearer(key, spent
+            const { verdict, account, workspace } = await checkBearer(key, spent
                 ? () => {
                     const entry = failures.get(sourceOf(req));
                     if (entry)
@@ -836,33 +1212,155 @@ export async function runHttp(cfg) {
                 : undefined);
             if (verdict === 'refused') {
                 noteFailure(req);
-                return challenged(res, TOKEN_REFUSED, rpcId(req));
+                return challenged(res, refusedMessage(key), rpcId(req));
             }
             // Not an initialize, it is a 400 whatever the platform could say about
             // the key short of refusing it.
             if (verdict === 'unknown' && initialize) {
                 return unavailable(res, 'The platform could not confirm this token just now. Retry shortly.', rpcId(req));
             }
+            checkedAccount = account;
+            checkedWorkspace = workspace;
         }
         if (!initialize) {
             return badRequest(res, 'No session id, and this is not an initialize request.', rpcId(req));
         }
+        // One bearer may not hold the whole pool (OPL-5443), nor one account more
+        // than its ceiling however many bearers it holds (OPL-5447). Both counted
+        // before the process-wide cap, so a bearer that can make room by closing
+        // one of its idle sessions frees a process-wide slot as well. From the
+        // count to the reservation below is synchronous, so a burst cannot all
+        // read the same count.
+        const keyDigest = digest(key);
+        const keyId = keyDigest.toString('hex');
+        // Hosted, the account the platform confirmed for this bearer (or the
+        // bearer itself, when whoami named none); self-hosted, the bearer.
+        const account = checkedAccount ?? accountKey(keyId, undefined);
+        // Hosted, the workspace key when the platform named a workspace for the
+        // bearer's account (OPL-5453); otherwise none, and no sub-ceiling.
+        const workspace = checkedAccount !== undefined ? checkedWorkspace : undefined;
+        // The account's standing, read after the check above (OPL-5452): what the
+        // newest-started probe of ANY of its bearers said, not only this one's.
+        // Self-hosted there is none, and nothing is suspended.
+        const suspended = accountSuspended(account);
+        const bearerCap = suspended ? MAX_SESSIONS_SUSPENDED : maxPerBearer;
+        // A bearer, or a suspended account, can hold more than its limit only when
+        // the limit fell under it: an account suspended after it opened sessions
+        // (OPL-5448, OPL-5452). Those over it are closed first if idle, whatever
+        // becomes of this initialize, so what is left to count, and to name in a
+        // 429, is what it really holds.
+        enforceAccountSuspension(account);
+        trimIdle(keyDigest, bearerCap);
+        const tooMany = (message) => {
+            res.set('Retry-After', String(BEARER_FULL_RETRY_AFTER_S));
+            return rpcError(res, 429, -32002, message, rpcId(req));
+        };
+        // Room is made from this bearer's own IDLE sessions, least recently seen
+        // first, exactly as the sweeper would close them, under whichever limit
+        // binds: its own cap or its account's ceiling. Never another bearer's live
+        // session, and never one with a request in flight: past the ceiling an
+        // initialize is refused, since the account's holder is the one who knows
+        // which of its clients can spare a session. Two exceptions (see
+        // `planRoom`): an idle session of the account's whose bearer the platform
+        // refused, and, while the account is suspended, any idle session of the
+        // account's, since it holds one in all (OPL-5452). A client whose old
+        // session is gone gets 404 for it and
+        // initializes again, as MCP clients do. Decided here, so a caller with
+        // nothing idle to give back is refused at once; carried out only once the
+        // new session exists (in `onsessioninitialized`), so an initialize the SDK
+        // then refuses (406, 415, 400) or that throws on the way does not also
+        // cost the caller a working session. Only the number is kept past here,
+        // and, for the pool reserve's count below, the ids, which do not leave
+        // this synchronous block.
+        let planned = 0;
+        let plannedIds;
+        {
+            const room = planRoom(keyDigest, account, workspace, suspended, pendingByDigest.get(keyId) ?? 0, workspace !== undefined ? (pendingByWorkspace.get(workspace) ?? 0) : 0, pendingByAccount.get(account) ?? 0);
+            if ('full' in room) {
+                if (room.full === 'account') {
+                    return tooMany(suspended ? SUSPENDED_ACCOUNT_FULL : accountFullMessage(account, maxPerAccount));
+                }
+                if (room.full === 'workspace')
+                    return tooMany(workspaceFullMessage(maxPerWorkspace));
+                // Over the cap after the trim means every session over it is busy,
+                // and closing one would not be enough: the client can only wait.
+                return tooMany(room.holds > bearerCap
+                    ? `This token holds ${room.holds} sessions on this server, over its maximum of ${bearerCap}, and the ones over it are all serving a request. Retry once they finish; idle ones are closed to make room.`
+                    : `This token already holds its maximum of ${bearerCap} ${bearerCap === 1 ? 'session' : 'sessions'} on this server. Close one (DELETE /mcp) or retry shortly.`);
+            }
+            planned = room.victims.length;
+            plannedIds = new Set(room.victims.map(([id]) => id));
+        }
         // Swept sessions free their slot on the timer; this is the backstop for the
         // case the timer cannot help with, which is arrivals faster than the TTL.
-        if (sessions.size + pending >= maxSessions) {
+        // The sessions this initialize will close are still in the map, and are not
+        // counted against it: a bearer making room in its own share is not newly
+        // refused for the room it is about to give back. Nothing is closed to make
+        // room here, whoever holds the pool.
+        if (sessions.size - planned + pending >= maxSessions) {
+            res.set('Retry-After', String(POOL_FULL_RETRY_AFTER_S));
             return unavailable(res, `This server is holding its maximum of ${maxSessions} sessions. Retry shortly.`, rpcId(req));
         }
+        // The last quarter of the pool is kept for accounts holding less than
+        // their share (OPL-5454): without it the ceilings alone let four accounts
+        // take every session between them, and the fifth was refused until one
+        // gave some back. Counted as the check above counts, pending included, so
+        // a burst cannot all read the same count. The share is of the unreserved
+        // part, divided among the accounts holding or opening sessions, this one
+        // included. Checked at admission only, as the pool is; nothing is closed
+        // for it.
+        const inUse = sessions.size - planned + pending;
+        if (poolReserve > 0 && inUse >= unreserved) {
+            const holders = new Set([account, ...pendingByAccount.keys()]);
+            let held = pendingByAccount.get(account) ?? 0;
+            for (const [id, live] of sessions) {
+                if (plannedIds.has(id))
+                    continue;
+                holders.add(live.account);
+                if (live.account === account)
+                    held++;
+            }
+            const fairShare = Math.max(1, Math.floor(unreserved / holders.size));
+            if (held >= fairShare) {
+                res.set('Retry-After', String(POOL_FULL_RETRY_AFTER_S));
+                return unavailable(res, `This server keeps its last ${poolReserve} sessions for accounts holding less than their share of it, and this account holds its share. Retry shortly.`, rpcId(req));
+            }
+        }
         pending++;
+        pendingByDigest.set(keyId, (pendingByDigest.get(keyId) ?? 0) + 1);
+        pendingByAccount.set(account, (pendingByAccount.get(account) ?? 0) + 1);
+        if (workspace !== undefined) {
+            pendingByWorkspace.set(workspace, (pendingByWorkspace.get(workspace) ?? 0) + 1);
+        }
         // Released exactly once, whether the initialize lands in the map or throws
         // on the way there. A reservation that leaked on the failure path would
         // ratchet the cap down until the process restarted — every later initialize
         // refused with 503 for the life of the process, which is the denial of
-        // service the counter was added to prevent, self-inflicted.
+        // service the counter was added to prevent, self-inflicted. The per-bearer,
+        // per-account and per-workspace counts leaking would do the same to that
+        // bearer, account and workspace.
         let reserved = true;
         const release = () => {
             if (reserved) {
                 reserved = false;
                 pending--;
+                const left = (pendingByDigest.get(keyId) ?? 1) - 1;
+                if (left > 0)
+                    pendingByDigest.set(keyId, left);
+                else
+                    pendingByDigest.delete(keyId);
+                const accountLeft = (pendingByAccount.get(account) ?? 1) - 1;
+                if (accountLeft > 0)
+                    pendingByAccount.set(account, accountLeft);
+                else
+                    pendingByAccount.delete(account);
+                if (workspace !== undefined) {
+                    const workspaceLeft = (pendingByWorkspace.get(workspace) ?? 1) - 1;
+                    if (workspaceLeft > 0)
+                        pendingByWorkspace.set(workspace, workspaceLeft);
+                    else
+                        pendingByWorkspace.delete(workspace);
+                }
             }
         };
         // Everything from here to the map write is inside the reservation,
@@ -875,6 +1373,9 @@ export async function runHttp(cfg) {
         let transport;
         let mcp;
         let finishInitialize = () => { };
+        // Set when the session was dropped at birth for want of room (see
+        // `onsessioninitialized`): it has an id but no map slot.
+        let dropped = false;
         try {
             const t = new StreamableHTTPServerTransport({
                 sessionIdGenerator: () => randomUUID(),
@@ -889,9 +1390,43 @@ export async function runHttp(cfg) {
                 allowedHosts: hosts,
                 allowedOrigins,
                 onsessioninitialized: (id) => {
+                    // The room the check above planned, made now that there is a session
+                    // to make it for. Chosen again from what is here NOW: a session
+                    // closed or put to work since then is not a candidate. Should too
+                    // few still be idle, nothing is closed and this session is dropped
+                    // instead of admitted over the cap. The transport closes before the
+                    // SDK answers, so the SDK answers this initialize itself, with its
+                    // 404 -32001 'Session not found' and no Retry-After — not the 429
+                    // the refusal above gives, which cannot be written from here. An
+                    // SDK client surfaces that as a failed connect; it does not retry
+                    // on its own. Only a race reaches this: a request landing on a
+                    // planned session between the check above and this callback.
+                    //
+                    // The account's ceiling is re-checked here too (OPL-5447), and the
+                    // workspace's sub-ceiling (OPL-5453), against
+                    // the map alone. Initializes still pending were each admitted
+                    // counting this one's reservation, and the room they will make is
+                    // still in the map, so counting them again here would drop a session
+                    // that fits; what keeps a burst under the ceiling is the pending
+                    // count at admission. Every landing leaves the map within both.
+                    // The account's standing is read again: a probe that answered in
+                    // between is the newer word on whether it is suspended.
+                    const room = planRoom(keyDigest, account, workspace, accountSuspended(account), 0, 0, 0);
+                    if ('full' in room) {
+                        dropped = true;
+                        release();
+                        void t.close().catch(() => { });
+                        return;
+                    }
+                    for (const [other, gone] of room.victims) {
+                        sessions.delete(other);
+                        void gone.transport.close().catch(() => { });
+                    }
                     const live = {
                         transport: t,
-                        keyDigest: digest(key),
+                        keyDigest,
+                        account,
+                        workspace,
                         lastSeen: Date.now(),
                         // Initialize is already in flight when the session first becomes
                         // visible to the sweeper. Count it until handleRequest settles.
@@ -961,10 +1496,11 @@ export async function runHttp(cfg) {
             mcp = server;
             await server.connect(t);
             const handled = await t.handleRequest(req, res, req.body);
-            // Any initialize that never reached `onsessioninitialized` has no map
-            // slot and nothing the sweeper will reap. The SDK's 403 used to take
-            // this path without throwing; other early returns still can.
-            if (!t.sessionId) {
+            // Any initialize that never reached `onsessioninitialized`, or was
+            // dropped there, has no map slot and nothing the sweeper will reap. The
+            // SDK's 403 used to take this path without throwing; other early returns
+            // still can.
+            if (!t.sessionId || dropped) {
                 void server.close().catch(() => { });
                 void t.close().catch(() => { });
             }
@@ -1009,14 +1545,28 @@ export async function runHttp(cfg) {
         // The stream is refused on a token the platform has already refused; a
         // DELETE is still honoured, since the digest shows it is the holder.
         if (challenge && live.refused && req.method === 'GET')
-            return challenged(res, TOKEN_REFUSED);
-        // The DELETE is a request and is held for; the GET is the notification
-        // stream and is only noted. See `serving`.
+            return challenged(res, refusedMessage(key));
+        // A suspended account is held to one session on its stream too, as on a
+        // notification: the stream asks the platform nothing, so only while this
+        // bearer's acceptance is cached (OPL-5452). This session is the one kept.
+        if (challenge && req.method !== 'DELETE' && isAccepted(key)) {
+            enforceSuspensionFor(live, acceptance(key)?.account, sessionId);
+        }
+        // The GET is the notification stream and is only noted; anything else
+        // here (a DELETE, or a HEAD, which Express routes to the GET handler with
+        // the method unchanged) is held for while the SDK handles it. See
+        // `serving`. None of it is put to the platform, so none of it may keep the
+        // session from idling out once the token's acceptance lapses: a HEAD is
+        // answered 405 and a DELETE the SDK refuses (an unsupported protocol
+        // version, say) 400, both leaving the session open, and a revoked token's
+        // holder could otherwise send either for ever to keep its sessions, and
+        // its account's ceiling, held (OPL-5455). A DELETE that succeeds closes
+        // the session anyway, and `active` is counted whatever `heard` says.
         if (req.method === 'GET') {
-            touch(live, res);
+            touch(live, res, heardWhileAccepted(key));
             return live.transport.handleRequest(req, res);
         }
-        return serving(live, () => live.transport.handleRequest(req, res));
+        return serving(live, () => live.transport.handleRequest(req, res), heardWhileAccepted(key));
     };
     app.get('/mcp', bySession);
     app.delete('/mcp', bySession);
@@ -1161,6 +1711,101 @@ const BEARER_CHECK_TIMEOUT_MS = 10_000;
 const MAX_BEARER_CHECKS_IN_FLIGHT = 32;
 const MAX_ACCEPTED_BEARERS = 4096;
 const MAX_FAILURE_SOURCES = 10_000;
+/**
+ * Whether a whoami record says its account is suspended.
+ *
+ * Only an explicit `account.status` of `"suspended"` counts. A record this
+ * cannot read is not evidence of suspension, and treating it as such would hold
+ * a working account to one session on the strength of a shape change.
+ */
+function isSuspended(who) {
+    if (typeof who !== 'object' || who === null)
+        return false;
+    const account = who.account;
+    if (typeof account !== 'object' || account === null)
+        return false;
+    return account.status === 'suspended';
+}
+/**
+ * The account id a whoami record names: a non-empty string of at most 256
+ * characters. Anything else is no account, and the bearer then counts as an
+ * account of its own rather than as one this server could not confirm.
+ */
+function accountIdOf(who) {
+    if (typeof who !== 'object' || who === null)
+        return undefined;
+    const account = who.account;
+    if (typeof account !== 'object' || account === null)
+        return undefined;
+    const id = account.id;
+    return typeof id === 'string' && id.length > 0 && id.length <= 256 ? id : undefined;
+}
+/**
+ * The workspace id a whoami record names for a workspace-scoped bearer
+ * (OPL-5453): `workspace.id`, a non-empty string of at most 256 characters.
+ * Anything else, `workspace: null` (a key of the account as a whole)
+ * included, is no workspace, and the bearer is held by no sub-ceiling.
+ */
+function workspaceIdOf(who) {
+    if (typeof who !== 'object' || who === null)
+        return undefined;
+    const workspace = who.workspace;
+    if (typeof workspace !== 'object' || workspace === null)
+        return undefined;
+    const id = workspace.id;
+    return typeof id === 'string' && id.length > 0 && id.length <= 256 ? id : undefined;
+}
+/**
+ * What a session counts against for the account ceiling (OPL-5447).
+ *
+ * The account id the platform confirmed for the bearer when there is one
+ * (hosted mode), and otherwise the bearer's own digest: a hosted whoami that
+ * names no account, and every bearer on a self-hosted server, which verifies
+ * none and so puts no trust in a string it cannot check. Prefixed so the two
+ * can never name the same thing.
+ */
+function accountKey(keyId, confirmed) {
+    return confirmed !== undefined ? `account:${confirmed}` : `bearer:${keyId}`;
+}
+/**
+ * The 429 for a suspended account with nothing idle to give up (OPL-5452):
+ * its session is serving a request, or another initialize of its is in
+ * flight. An idle one would have been closed to make room.
+ */
+const SUSPENDED_ACCOUNT_FULL = 'This account is suspended, so it may hold only 1 session on this server across all its tokens, and none it holds is idle. Retry once its session finishes its request, or close it (DELETE /mcp).';
+/**
+ * The workspace key a workspace-scoped bearer counts against for the workspace
+ * sub-ceiling (OPL-5453), or undefined when there is none: its account key and
+ * the workspace id together, so the same workspace id under two accounts can
+ * never share a count. Only an account the platform confirmed (`account:`)
+ * has workspaces; a `bearer:` account never does.
+ */
+function workspaceKey(account, workspaceId) {
+    return account.startsWith('account:') && workspaceId !== undefined
+        ? `${account}/workspace:${workspaceId}`
+        : undefined;
+}
+/** The 429 for a workspace at its sub-ceiling. It names the limit and nothing else. */
+function workspaceFullMessage(cap) {
+    const noun = cap === 1 ? 'session' : 'sessions';
+    return `This workspace has reached its maximum of ${cap} ${noun} on this server, across all its tokens. Close one (DELETE /mcp) or retry shortly.`;
+}
+/** The 429 for an account at its ceiling. It names the limit and nothing else. */
+function accountFullMessage(account, cap) {
+    const noun = cap === 1 ? 'session' : 'sessions';
+    return account.startsWith('account:')
+        ? `This account has reached its maximum of ${cap} ${noun} on this server, across all its tokens. Close one (DELETE /mcp) or retry shortly.`
+        : `This token has reached the per-account maximum of ${cap} ${noun} on this server, as an account of its own. Close one (DELETE /mcp) or retry shortly.`;
+}
+const always = () => true;
+/**
+ * The order idle sessions are closed in to make room: those whose bearer the
+ * platform has refused first, since nothing more is served on them, then the
+ * least recently seen.
+ */
+function closingOrder(a, b) {
+    return Number(b[1].refused) - Number(a[1].refused) || a[1].lastSeen - b[1].lastSeen;
+}
 /** Whether a POST body holds a JSON-RPC request, which is what opens a stream. */
 function carriesRequest(body) {
     const isRequest = (m) => typeof m === 'object' && m !== null && 'method' in m && 'id' in m;
@@ -1168,6 +1813,17 @@ function carriesRequest(body) {
 }
 const NO_TOKEN = 'Authorization required. Authorize this client with Mandala (OAuth), or send a Mandala API key: Authorization: Bearer …';
 const TOKEN_REFUSED = 'The platform no longer accepts this access token. Refresh it, or authorize again.';
+const API_KEY_REFUSED = 'The platform does not accept this API key. Check it, or create a new one in Settings → Credentials.';
+/**
+ * What a refused bearer is told. A `com_…` API key was never an OAuth access
+ * token and cannot be refreshed, so it is not told to refresh (OPL-5464); any
+ * other bearer is an access token and keeps the OAuth wording. Only the message
+ * text differs — the 401 and its challenge are the same — and the bearer itself
+ * is never part of it.
+ */
+function refusedMessage(key) {
+    return key?.startsWith('com_') ? API_KEY_REFUSED : TOKEN_REFUSED;
+}
 /**
  * Hold a response's status line until its first byte of body (hosted mode).
  *