mandala-computer-mcp 0.8.0 → 0.9.0

package/dist/http.js

@@ -78,7 +78,9 @@ export const DEFAULT_MAX_SESSIONS = 256;
  *
  * 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.
+ * 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;
@@ -231,6 +233,32 @@ export async function runHttp(cfg) {
     const checkTtl = cfg.bearerCheckTtlMs ?? DEFAULT_BEARER_CHECK_TTL_MS;
     const accepted = new Map();
     let checksInFlight = 0;
+    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'));
@@ -241,35 +269,46 @@ export async function runHttp(cfg) {
     /**
      * `ok`: the probe answered 2xx, and only that — the one answer that says the
      * platform authenticated this credential AND let it act. `suspended`: the
-     * same 2xx, for an account whose whoami says `status: "suspended"` — admitted
-     * as `ok` is, and held to one session. `refused`: a 401.
+     * 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`
-     * and `suspended` are cached, the standing and the account id with the
-     * acceptance. `account` is the account key the bearer counts against (see
+     * 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.
+     * 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');
         const cached = acceptance(key);
-        if (cached) {
+        // Believed only while its account has a standing to read (see above).
+        if (cached && standing.has(cached.account)) {
             return {
-                verdict: cached.suspended ? 'suspended' : 'ok',
-                account: accountKey(id, cached.account),
+                verdict: accountSuspended(cached.account) ? 'suspended' : 'ok',
+                account: cached.account,
+                workspace: cached.workspace,
             };
         }
         if (checksInFlight >= MAX_BEARER_CHECKS_IN_FLIGHT)
             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,
@@ -287,6 +326,7 @@ export async function runHttp(cfg) {
             const who = await api.json('GET', WHOAMI);
             suspended = isSuspended(who);
             confirmed = accountIdOf(who);
+            workspaceId = workspaceIdOf(who);
         }
         catch (err) {
             return { verdict: err instanceof APIError && err.status === 401 ? 'refused' : 'unknown' };
@@ -304,8 +344,11 @@ export async function runHttp(cfg) {
                 accepted.delete(accepted.keys().next().value);
             }
         }
-        accepted.set(id, { until: now + checkTtl, suspended, account: confirmed });
-        return { verdict: suspended ? 'suspended' : 'ok', account: accountKey(id, confirmed) };
+        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
@@ -404,13 +447,32 @@ export async function runHttp(cfg) {
     // 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: half the pool by
-    // default, so no one tenant can take the whole of it however many keys it
-    // holds. Normalised as the per-bearer cap is, and clamped to the pool.
+    // 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 / 2));
+        : 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.
     //
@@ -703,9 +765,23 @@ export async function runHttp(cfg) {
         return counted;
     };
     /**
-     * The sessions to close so that one more fits under both this bearer's cap
-     * and its account's ceiling (OPL-5447), or which of the two it cannot fit
-     * under.
+     * 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
@@ -716,43 +792,119 @@ export async function runHttp(cfg) {
      * 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.
+     * 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.
      *
-     * `pendingBearer`/`pendingAccount` are initializes admitted and not yet
-     * landed; at landing both are 0 (see `onsessioninitialized`). The result
-     * names sessions, so nothing that outlives the call may keep it.
+     * `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, bearerCap, pendingBearer, pendingAccount) => {
+    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 - maxPerAccount + 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)
+        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)]
+        const candidates = [
+            ...own,
+            ...counted.filter(([id, live]) => !mine.has(id) && (live.refused || suspended)),
+        ]
             .filter(([, live]) => live.active === 0)
-            .sort((a, b) => Number(b[1].refused) - Number(a[1].refused) || a[1].lastSeen - b[1].lastSeen);
+            .sort(closingOrder);
         for (const entry of candidates) {
-            if (bearerNeed <= 0 && accountNeed <= 0)
+            if (bearerNeed <= 0 && accountNeed <= 0 && workspaceNeed <= 0)
                 break;
             const ofBearer = mine.has(entry[0]);
             const ofAccount = entry[1].account === account;
-            if (!(ofBearer && bearerNeed > 0) && !(ofAccount && accountNeed > 0))
+            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
@@ -953,28 +1105,39 @@ export async function runHttp(cfg) {
                     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.
                 const request = carriesRequest(req.body);
-                const verdict = challenge && request ? (await checkBearer(key)).verdict : undefined;
+                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);
                 }
-                // An account suspended after its bearer opened sessions kept every one
-                // of them, up to the 16 an active bearer may hold, while an initialize
-                // on it was held to one (OPL-5448). Its other idle sessions go now,
-                // down to that one; this session is pinned above and one busy
-                // elsewhere is skipped, and closed on a later request once it is idle.
-                if (verdict === 'suspended')
-                    trimIdle(live.keyDigest, MAX_SESSIONS_SUSPENDED, 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), 
                 // A request keeps the session as before: it was just put to
@@ -1018,8 +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 suspended = false;
         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:
@@ -1040,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, account } = await checkBearer(key, spent
+            const { verdict, account, workspace } = await checkBearer(key, spent
                 ? () => {
                     const entry = failures.get(sourceOf(req));
                     if (entry)
@@ -1049,15 +1212,15 @@ 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));
             }
-            suspended = verdict === 'suspended';
             checkedAccount = account;
+            checkedWorkspace = workspace;
         }
         if (!initialize) {
             return badRequest(res, 'No session id, and this is not an initialize request.', rpcId(req));
@@ -1073,11 +1236,20 @@ export async function runHttp(cfg) {
         // 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 can hold more than its cap only when the cap fell under it: an
-        // account suspended after it opened sessions (OPL-5448). Those over the
-        // cap 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.
+        // 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));
@@ -1088,20 +1260,28 @@ export async function runHttp(cfg) {
         // 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. An idle session of the
-        // account's whose bearer the platform refused is the one exception (see
-        // `planRoom`). A client whose old session is gone gets 404 for it and
+        // 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.
+        // 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, bearerCap, pendingByDigest.get(keyId) ?? 0, pendingByAccount.get(account) ?? 0);
+            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(accountFullMessage(account, maxPerAccount));
+                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
@@ -1109,6 +1289,7 @@ export async function runHttp(cfg) {
                     : `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.
@@ -1120,16 +1301,44 @@ export async function runHttp(cfg) {
             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. The per-bearer
-        // and per-account counts leaking would do the same to that bearer and that
-        // account.
+        // 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) {
@@ -1145,6 +1354,13 @@ export async function runHttp(cfg) {
                     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,
@@ -1186,13 +1402,16 @@ export async function runHttp(cfg) {
                     // 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), against
+                    // 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.
-                    const room = planRoom(keyDigest, account, bearerCap, 0, 0);
+                    // 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();
@@ -1207,6 +1426,7 @@ export async function runHttp(cfg) {
                         transport: t,
                         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.
@@ -1325,7 +1545,13 @@ 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);
+            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
@@ -1514,6 +1740,21 @@ function accountIdOf(who) {
     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).
  *
@@ -1526,6 +1767,29 @@ function accountIdOf(who) {
 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';
@@ -1534,6 +1798,14 @@ function accountFullMessage(account, cap) {
         : `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;
@@ -1541,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).
  *