Queue Manager — Product Spec (Contract)

Virtual waiting room / traffic management, CrowdHandler & Queue-it class.

Stack (fixed — do not change)

• Node.js >= 18. The runtime is zero-dependency: nothing under server.js, lib/, snippet/ or public/ may import a package from node_modules — node builtins only (node:http, node:crypto, node:fs, …). dependencies in package.json stays empty.
• Vitest is the dev-only test runner (devDependencies, the single permitted npm package). npm test → vitest run, npm run test:watch → vitest. Config in vitest.config.js; suites in test/*.test.js use the Vitest globals (describe/it/expect/beforeAll/afterAll), so no test file imports it either. Shipping or deploying the product never installs it.
• Single process: node server.js. Port 8080 (env PORT).
• Realtime: Server-Sent Events (SSE). No websockets.
• Persistence: STORE=valkey + SIDESTORE=pg in production (NODE_ENV=production refuses anything else): the live queue in Valkey, every change journaled per room to Postgres, everything else in Postgres. Survives restart. STORE=memory (development and tests) is in-process and diskless: nothing is written to disk, and every boot starts empty. The file journal (data/) was removed in step 5.
• Event ordering (QM-449, normative for the port): every room's events MUST carry a monotonic per-room sequence number so replay can detect a gap or a reordering. The Valkey store does: every row of the Postgres journal carries its room's seq, and a rebuild detects a gap. The memory store keeps no journal.
• Admin auth: ADMIN_KEY env (default admin-dev), sent as Authorization: Bearer <key>. With the default key the server binds 127.0.0.1 when HOST is unset and refuses to start when HOST is not loopback. Other admin credentials: named operator keys (qmo_…, role owner | operator | viewer, 403 insufficient_role when the role is short), the read-only monitor token, and the console session cookie qm_console (below). Wrong credentials count against ADMIN_AUTH_FAIL_PER_MIN; a locked-out address gets 429 too_many_auth_failures before any credential is read. See OPERATIONS.md, Two keys, two blast radii, and Operators, roles and the audit trail. A query-string credential lands in access logs, in Referer headers, and — on an inline host, where /__qm/* is rewritten before auth runs — in the CUSTOMER's access and CDN logs. So no key is ever accepted from a URL. The SSE route is the one place EventSource cannot send a header: POST /api/admin/sse-ticket (Bearer) returns a single-use ticket, valid 30s, spent on first use, scoped to the minting credential, redeemed as GET /api/admin/events?ticket=<t>. The shareable monitor link carries its viewer token in the URL fragment, which no browser sends to any server.
• Tokens: base64url(JSON) "." base64url(HMAC-SHA256), root secret from SECRET env (default random per boot; required with SIDESTORE=pg). QM-352, two forms, both always verified. Legacy (signed by default): HMAC key SECRET, no kid, accepted for any purpose whose payload checks pass. v2 (signed when TOKEN_SIGN_V2=1): key per purpose = HKDF-SHA256(SECRET, salt empty, info qm:visitor | qm:monitor | qm:session | qm:operator, 32 bytes), payload carries kid = hex(HKDF-SHA256(SECRET, salt empty, qm:kid, 4 bytes)), unknown kid refused, never valid for another purpose. SECRET_PREVIOUS keeps the previous SECRET verifying (either form) during a rotation; new tokens use SECRET. Operator verifiers follow the same rule and are never downgraded from v2. See OPERATIONS.md, Signing keys and rotating SECRET.
• Visitor token payload (purpose visitor): {r, n, g, iat} for a place in line, or {r, q, g, iat} for a pre-queue entry — exactly one of n/q, never both; v2 adds kid. r room id; n ticket number (integer >= 0, 0 = bypass pass holding no slot); q pre-queue handle (integer >= 1, not a position); g room generation (integer >= 1; a deleted and re-created room gets a new one, so an old ticket cannot claim a place in the new line); iat issued-at epoch ms. Refused past TOKEN_MAX_AGE_SEC (default 86400, minimum 60) after iat, or with iat more than 60 s in the future. The token carries no waiting/passed status: that lives in the engine, keyed by r+n. Other purposes (monitor, session, operator) have their own payloads and are never accepted as a visitor token under v2.

File ownership (builders stay in their lane)

Core concepts

• Room (waiting room): id, name, target URL, ratePerMinute (outflow), maxConcurrent (optional), configured state: active | paused | bypass (bypass = queue off, all pass). A room whose opensAt is still in the future reports the effective state scheduled on the visitor wire while its configured state remains one of the three; admin listings carry both, plus opensAt and a preQueue count.
• Visitor token: signed; holds room id, ticket number or pre-queue handle, room generation and issued-at (payload above). Whether that ticket is waiting or has passed is engine state, not token state.
• Ownership cookie qms_<roomId>: an opaque random session id (16–128 chars), set HttpOnly beside the token on /api/join and bound to the ticket engine-side (only its hash is stored). A token presented without the browser that queued for it does not carry the place; a join without the cookie mints a fresh one. See OPERATIONS.md, How a pass is bound to a visitor.
• Queue cookie scope (QM-504, QM-526, normative): the per-room cookies qm_<roomId>, qms_<roomId> and qm_dk_<roomId> stay Path=/. Path is not narrowed: connectors on the customer origin read them on Path=/, and narrowing would leave duplicate cookies beside the old Path=/ ones. Instead the queue host keeps at most 8 rooms' cookies per browser (ROOM_COOKIE_CAP); setting a room's cookies when more are present expires the oldest rooms' cookies in the same response. Accepted residual risk (QM-539): a page that walks a visitor through more than 8 rooms can evict that visitor's older rooms' cookies.
• Generation g: bumped when a room is deleted and re-created. A token from an earlier generation is not honoured by /api/join (the caller gets a new place), /api/notify answers 409 stale_ticket, and /api/status and the event stream answer {expired:true, reason:"room_reset"}.
• Fairness: strict FIFO by ticket number. Re-visits keep position (token in cookie/localStorage, plus the ownership cookie). Lost token = back of line.
• Token refresh (QM-391): a wait may outlast the token (TOKEN_MAX_AGE_SEC) and the queue cookies (QUEUE_COOKIE_MAX_AGE_SEC) — above all a pre-queue for an opensAt days away. Once a presented visitor token is at least half the shorter of the two old, /api/status and the event stream re-sign the same place ({r, n|q, g} with a new iat, signed with the keyring in force, so v2 and kid follow TOKEN_SIGN_V2) and re-set both qm_<roomId> and qms_<roomId> (same session id), only when all hold: the room exists and g is its generation; the place is still waiting (status neither expired nor passed; a pre-queue handle counts); and the request's qms_<roomId> proves the place engine-side. A fingerprint match never earns one. /api/status returns the new token as token; a stream opened with a due token carries it as token in every frame and sets the cookies on its response, and an open stream whose token falls due is ended so the browser reconnects and refreshes. The waiting page stores a token only when it names the place it already holds. A token already past TOKEN_MAX_AGE_SEC is refused as before: the refresh cannot resurrect one.
• Outflow: engine promotes ratePerMinute waiting→passed per minute, smooth (per-second slices, not bursts). A passed ticket is valid passedTtlSec (default 600) to enter the target site.
• Scheduled drop: a room may carry opensAt. Before it there is no line at all — joiners are held in a pre-queue and issued an opaque handle, not a ticket number. At opensAt the pre-queue is drawn into FIFO order using a crypto-grade random permutation, round-robin across identities so a second entry from one identity never outranks any other identity's first. The permutation is recorded, so a restart across the open instant replays it instead of drawing again. preQueueMaxPerIp (default 16, null = unlimited, 1..100000) caps entries per identity; a join over it is 429 prequeue_identity_limit with no token, handle or cookie returned, and a pre-queue at its hard ceiling is 503 prequeue_full. Invariant: arrival order within the pre-queue must not correlate with drawn position — arriving early buys nothing.
• Ghost tickets (QM-345): a pass reserves a maxConcurrent slot only for a holder seen (join, /api/status, or the /events heartbeat) within presenceSec (default 30, null = rule off). An absent holder's ticket is still promoted in FIFO order, but its pass owns no slot (a pass past its claim window: usable at the door within passedTtlSec), and on the clock it costs no outflow; a pass whose holder was never told they are through gives its slot back after presenceSec unseen. The pass log event lists those tickets in ns so replay restores them slotless. queueMaxPerIp (default 16, null = unlimited, 1..100000) caps waiting-line places per client address; a new join over it is 429 queue_identity_limit with nothing spendable returned. Tickets with no recorded holder (engine-internal callers) are exempt from both.

HTTP API (contract — UI builders code against this)

Versioning policy

Every route below is served at /api/v1/<route> (canonical, pinned) and at the unversioned /api/<route> (permanent alias, same handler, byte-identical response). The snippet is deployed on third-party origins that cannot be upgraded in lockstep with this server, so it asks for /api/v1/* and falls back to /api/* once per page if the server 404s the prefix.

• Breaking changes ship as /api/v2/*; v1 keeps its shapes. Additive optional fields stay in v1.
• The unversioned aliases are not deprecated and are never removed; they track the newest contract, which is why pinned integrations must not use them.
• Unversioned surface (not part of the contract): /healthz, /w/:roomId, /snippet/*, /, /progress, /metrics, /events (the permanent bare alias of the contract route /api/events — see Visitor below; listed here so a build generating its path set from this section does not drop it), /docs (+ /docs/:name, which renders INTEGRATION.md, OPERATIONS.md and this file for readers who only ever see the running server), /docs/th (+ /docs/th/:name, the same guides in Thai from docs/th/<file>).
• Wrong verb on a contract path → 405 + Allow header + {"code":"method_not_allowed"}.
• OPTIONS preflight runs the same CORS decision as the real method: it must never advertise an origin the actual response would refuse.

Visitor

• POST /api/join {roomId, token?} → {token, position, ahead, etaSec, state} (sets cookie qm_<roomId> with the token and the HttpOnly ownership cookie qms_<roomId>). A same-generation token in the body or cookie keeps its place (a pre-queue handle is exchanged for its drawn ticket once the doors open). Refusals: 429 rate_limited (JOIN_LIMIT_PER_MIN), 400 invalid_room_id / invalid_token_field, 404 room_not_found, 403 blocked_by_protection (room protection in enforce mode), 429 queue_identity_limit, 429 prequeue_identity_limit, 503 prequeue_full, 503 storage_unavailable (the join could not be flushed to disk, so no ticket is handed out).
• GET /api/status?token= → {position, ahead, etaSec, state, passed, redirectUrl?}. Token from ?token= (not on an inline host) or the qm_<roomId> cookie; none valid → 401 invalid_token.
• GET /api/events?token= → SSE: event status with same JSON as /api/status, pushed on change + every 5s heartbeat. Versioned like every other contract route (/api/v1/events), and also served at the bare /events, which the shipped waiting page asks for. That alias is permanent, not legacy: every waiting page currently open in a browser holds an EventSource on it, and those reconnect by themselves after a restart or a deploy — removing the path would break the visitors who are in the queue at that moment, which is the one population this product exists for. Stream limits: 503 sse_capacity at SSE_MAX_TOTAL streams, 429 sse_per_ip_limit at SSE_PER_IP per address, both with Retry-After: 5.
• Refresh frame (QM-469). When the stream's token is due to be re-signed (TOKEN_REFRESH_AFTER_MS after its iat: half the shorter of TOKEN_MAX_AGE_SEC and QUEUE_COOKIE_MAX_AGE_SEC) and the refresh would be granted, the server sends event: refresh with data {} and ends the stream. A stream cannot set cookies once its headers are sent. The page reopens the stream itself, once, and the new stream's response re-signs the place and re-sets both cookies. Its status frames then carry the fresh token. The end is delayed past the due time by a jitter fixed per place: uint32_be(sha256("r|n|q|g|iat")[0..4]) % (floor(TOKEN_REFRESH_AFTER_MS / 10) + 1) ms, over the token payload's fields (a field the token does not carry, such as q on a ticket, is the literal text undefined, as JavaScript renders it), so at most +10% of the window, and a burst of joins with one iat does not reconnect together. A port must send the same frame and use the same jitter. A stream whose due refresh would not be granted is never ended for it.
• GET /w/:roomId → serves waiting.html (injects roomId + branding JSON as window.QM_CONFIG). A qm_return that the room's return policy refuses is stripped, not honoured.
• The page's style and main script are linked, not inline (QM-467): GET /assets/waiting-<hash>.css and /assets/waiting-<hash>.js, also under /__qm/assets/… on an inline host. <hash> is the first 22 characters of the base64url SHA-256 of the file. They are served with Cache-Control: public, max-age=31536000, immutable. A process serves only its own build's hashes, so with more than one instance, or during a rolling deploy, every instance must serve every hash that any instance is still handing out. See OPERATIONS.md, Waiting-page assets and live streams across a deploy.
• A visitor arriving with a token that is no longer a place gets lapsed in that config — "expired" when their own entry window ran out, "reset" when it was our doing (eject, purge, room reset), absent when nothing was lost. Both deployments derive it from the engine's own word for the refusal, and the page has the sentence for each in every locale; without it the visitor is told their ticket "could not be verified", which names a fault that did not happen. A token known to have lapsed is also treated as no token, so the replacement place the page promises is actually minted — including for a visitor with no JavaScript, who has no second way to recover.
• POST /api/notify {token?, email?} → registers (or, with an empty/omitted email, withdraws) the visitor's turn notification. Ticket comes from the body token or the queue cookie, never the URL.
• A turn notification is filed against the ticket, so wherever the server replaces a ticket it carries the record over — the pre-queue draw, and a rejoin presenting a ticket the engine will not honour. The client sends the dead token on that rejoin for exactly this reason. A purge or an eject deletes it instead: the operator discarded that place in line.
• POST /api/join therefore also answers notify — {emailMasked, requestedAt, delivery} or null — stating what is held against the place it just named. Absent entirely when EMAIL_NOTIFY is off; the page reads absence as "no statement" and null as "nothing stored", and stops claiming a save the server does not have.
• Before opensAt, /api/join and /api/status answer {state:"scheduled", scheduled:true, preQueued:true, preCount, opensAt, now} with position and ahead null, and the token carries a pre-queue handle q instead of a ticket n.
• Every visitor error is {error, code}; branch on code. The full visitor-facing list is INTEGRATION.md, Error codes.
• Any frame carrying a server instant carries now (server epoch ms) beside it — opensAt on a scheduled drop, messageAt when an operator message is set. Server instants are the only times on the visitor's wire that are not device-relative, and the page renders every clock time it shows in the DEVICE's frame (instant - (now - clientNow)), because that is the clock the visitor compares it against. Without now a skewed device reads a skew-corrected countdown beside an uncorrected "doors open at", and the two disagree. A frame that names no server instant needs no now.

Edge check (used by snippet)

• GET /api/check?roomId=&token=&url= → {action: "pass"|"queue", reason?, waitingRoomUrl?, clearToken?, sess?, targeting?, …} — pass if room bypass/inactive or the token's ticket has passed and is unexpired. An unknown room answers 200 {action:"pass", reason:"no_room"} (fail open), counted for the operator in /api/admin/health and /metrics. A pass that admits somebody is answered only once the admission is on disk; 503 storage_unavailable if it could not be written, and the admission is taken back so a retry is admitted.
• Door-session key sess: returned on the pass that opens (or reclaims) a door session, and replayed on every later check as the X-QM-Session header (what the snippet sends: a header keeps the credential out of URLs and logs), ?sess=, or on an inline host the HttpOnly qm_dk_<roomId> cookie. clearToken: true means drop the stored token and key before redirecting. Because the body can carry sess, on a room with an origin policy /api/check (and its OPTIONS) sends Access-Control-Allow-Origin only to a browser origin in the room's tag origins (tagOrigins, else returnOrigins, plus the targetUrl origin). See INTEGRATION.md, The door-session key.
• ?ip=&agent= vouches for the real client (server-side and edge connectors) and needs Authorization: Bearer <PUBLIC_API_KEY> (or ADMIN_KEY); without it 401 unauthorized, or 401 credential_in_query when the key was sent as ?key=. A vouched check is rate-limited per vouched address, not per calling colo.
• url= is the page being visited. It decides scope: whether this page belongs to the room at all. Absent, the Referer header is used; absent both, the check is unknown and fails open into the queue (never silently unprotected). ?targeting=1 adds the room's full rule list to the response.
• A page the room's rules exclude answers {action:"pass", reason:"out_of_scope"} without minting a place in line.
• targeting is present only on scoped rooms: {rev, rules, scope:"in"|"out"|"unknown", rule, action}. A room with no rules omits the key entirely and behaves exactly as it did before URL targeting existed.

Targeting (public, used by edge connectors)

• GET /api/targeting?roomId= → {roomId, rev, scoped, updatedAt, patterns:[{pattern, action}]} — the room's URL scope, so a Worker/Lambda/nginx connector pulls the rules at runtime instead of hard-coding them. ETag + 304 so it is cheap to poll.

Install checks and connector registry (public)

• GET /api/verify?roomId=&url=&origin=&connector=&version= → {ok, checks:[{id, status:"pass"|"fail"|"warn"|"info", title, detail?, fix?}], …} — the pre-deploy check every connector's CLI or settings screen runs. origin falls back to the origin of url, then the request's Origin header. A Bearer Public API key makes the report privileged (it also checks the key); a key in ?key= is reported as a failing check. 400 invalid_room_id without roomId. Checks are recorded for the console's "connectors that checked in" list. See INTEGRATION.md, Installable connectors.
• GET /api/verify.gif?roomId=&origin=&connector= → the same verdict as a status code, for the GTM sandbox, which can only see whether an image loaded: 200 image/gif when ok, else 424 {ok:false, error:"verify_failed", checks}. X-QM-Verify names the failing check ids; Cache-Control: no-store.
• GET /api/connectors → the registry: each connector's version, install/upgrade/verify commands, download URL and SHA-256 integrity, as served by this server. GET /api/connectors/wordpress/update → the same for WordPress's plugin-updater shape. The artifacts themselves are under /connectors/<name>/latest.{js,tgz,zip} (unversioned).
• /api/verify, /api/verify.gif and /api/connectors share the CHECK_LIMIT_PER_MIN budget (429 rate_limited).

Health (public, unauthenticated)

• GET /healthz, GET /api/health → readiness payload; 503 when the instance is not ready (for example it cannot persist a join), 200 otherwise. GET /api/version → the same payload, always 200. Exempt from connection-ceiling shedding. See OPERATIONS.md, Readiness.

Admin (all under /api/admin/*; Bearer, or the console session cookie)

• POST /api/admin/session {key} with header X-QM-CSRF: 1 → signs the console in: sets qm_console (HttpOnly, SameSite=Strict, Path=/api/admin, 12 h), a signed session reference that never contains the key; answers {ok, name, role, expiresInSec}. DELETE /api/admin/session (same header) clears it and revokes the session server-side. A request carrying the cookie and no Authorization header must send X-QM-CSRF on every non-GET, or 403 csrf_required; a request with Authorization is judged on that alone. See OPERATIONS.md, Two keys, two blast radii.
• Grants: viewer and the monitor token read (rooms, events, metrics, health, security, reports, alerts status, audit; the monitor token is refused audit, visitors and targeting); operator also changes queue state and room settings; owner/ADMIN_KEY also manage operators, delete rooms and shut down.
• GET /api/admin/operators, POST /api/admin/operators {name, role} → key returned once; DELETE /api/admin/operators/:id revokes. No route changes an existing operator's role.
• GET /api/admin/audit → who did what, when and from where. GET /api/admin/security → bot-protection scoring and refusals. GET /api/admin/reports?roomId=&bucket=hour|day → historical rows (CSV available for BI).
• GET /api/admin/alerts → alert state; POST /api/admin/alerts fires a test page (400 alerts_disabled without ALERT_WEBHOOK_URL, 502 webhook_failed if the webhook refuses).
• POST /api/admin/shutdown → {ok, stopping, uptimeSec} then a clean stop (the documented way to stop it on Windows). owner only.
• POST /api/admin/sse-ticket → single-use 30 s ticket for GET /api/admin/events?ticket=.
• GET /api/admin/rooms → list with live stats {waiting, passedLastMin, rate, state, oldestWaitSec}
• estWaitSec is the wait for a visitor joining now, and it is only ever a number the room can back. A room admitting nobody — paused, ratePerMinute: 0, or measured outflow of zero — reports null (unbounded), whether or not anyone is queued. A room whose doors are still shut reports the time left on the clock plus the drain of anyone already holding a ticket, the same sum /api/status quotes a waiting visitor, with estWaitFloor: true: the draw decides how much longer than that a pre-queue entry waits, so nothing is added for it. 0 means the room would admit immediately.
• POST /api/admin/rooms create/update room. The writable set is exactly: {id, name, targetUrl, proxyOrigin?, ratePerMinute, maxConcurrent?, passedTtlSec?, sessionTtlSec?, sessionMaxSec?, branding?, returnOrigins?, tagOrigins?, autotune?, protection?, autoActivate?, urlPatterns?, opensAt?, preQueueMaxPerIp?, queueMaxPerIp?, presenceSec?, state?, onBackendDown?}
• The nine beyond the obvious ones, because each is a whole feature reachable only through this body: proxyOrigin is inline mode (the internal address this server forwards an admitted visitor to); sessionTtlSec / sessionMaxSec bound a door session; autotune is the automatic rate controller; protection is the bot-scoring mode ({mode:"off"|"monitor"|"enforce"}); autoActivate is threshold activation; opensAt and preQueueMaxPerIp are the scheduled drop and its per-identity pre-queue cap; queueMaxPerIp and presenceSec are the live line's per-address ceiling and presence window (see Core concepts, Ghost tickets); state sets active/paused/bypass in the same write as everything else.
• onBackendDown ("closed", the default, or "open") is what an inline room's gate does while the backend is down (Valkey unreachable, or the room being rebuilt from the journal): closed answers a browser navigation with the waiting page in retry mode (503 + Retry-After, no place taken) and any other request with 503 storage_unavailable; open forwards to proxyOrigin unqueued. Anything else is 400 invalid_on_backend_down. Stored but without effect on STORE=memory, which has no backend to lose.
• redacted: true is refused with 400 redacted_shape rather than treated as an unknown field. A room read through a shared monitor link comes back with its internal address, origin allowlists and URL rules blanked, so posting that body straight back would wipe all of them; the error says so instead of naming a field.
• rate is accepted as an alias for ratePerMinute — it is what GET /api/admin/rooms calls the same field, so a read-edit-write round trip does not have to rename it. Sending both is fine if they agree; sending both with different values is 400 conflicting_field. Any field name outside the documented set is 400 unknown_field, not a silent no-op — a typo here used to look exactly like a successful edit that did nothing.
• returnOrigins is where a promoted visitor may be sent; tagOrigins is which pages may read a door check (the browser CORS allowlist). The room's targetUrl origin is always on both. tagOrigins: null (the default) inherits returnOrigins, so a room configured before the split is unchanged. They are separate because they fail in opposite directions: a wrong return policy is an open redirect, while a missing tag origin serves that page completely unqueued in silence.
• urlPatterns is the room's scope, as runtime config: at most 25 rules, each at most 300 characters and at most 10 * wildcards. A rule starts with / (path), * (anywhere) or a full https://host/path (pins the origin); a leading ! makes it an exception. Matching is case-insensitive; a rule with no ? is matched against the path only. Exceptions always win, whatever order they are listed in — order-dependent rules are an operator footgun, not a feature. [] means unscoped: every page carrying the tag is queued.
• branding.message is the operator's message to queued visitors; the server stamps branding.messageAt when the text changes, and the waiting page shows it in a timestamped pane in every state, including a scheduled drop's countdown.
• DELETE /api/admin/rooms/:id
• POST /api/admin/rooms/:id/state {state} (active/paused/bypass)
• POST /api/admin/rooms/:id/rate {ratePerMinute} (rate accepted as an alias, same rule as above) — takes effect immediately
• POST /api/admin/rooms/:id/flush — promote N now {count}
• POST /api/admin/rooms/:id/schedule {opensAt?, preQueueMaxPerIp?} — set/clear the doors-open instant. Each field is applied only if present: sending preQueueMaxPerIp alone adjusts the cap and leaves the drop scheduled. Cancelling a drop takes an explicit {"opensAt": null}. A body with neither field is 400 nothing_to_change, not a silent no-op.
• POST /api/admin/rooms/:id/eject {ticket} — revoke the pass, drop any live session, back of the line
• POST /api/admin/rooms/:id/purge — discard the whole waiting backlog without admitting anybody. For a room that has outlived its event: durability keeps its line across every restart, and deleting the room used to be the only way out. No passes are minted and no outflow is recorded, so the chart gains no spike that never happened; purged tickets read as expired, and the room, its settings and its history are kept. A scheduled room's pre-queue is emptied too. Answers {purged, stats} once the purge is on disk (503 storage_unavailable if it could not be written); purged counts pre-queue entries, which are also given as preQueue.
• GET /api/admin/rooms/:id/visitors?ticket= or ?ref= → per-visitor lookup for support (state, position, TTLs, session, binding — one-way digests only, never raw identifiers). ref= resolves the short code the waiting page shows the visitor, so the string they read down the phone is the string that goes in the box; an ambiguous code returns the candidate tickets rather than guessing.
• GET /api/admin/rooms/:id/targeting?url= → the room's rules with {matchCount, lastMatchedAt} per rule, plus counts of checks that matched nothing and checks that arrived with no URL. Optional url= is a dry run: which rule would win, without touching the counters. A rule that has never fired is the visible symptom of a room pointed at the wrong pages.
• GET /api/admin/events → SSE stats every 2s for all rooms {rooms:[...], totals, sparkline data}
• Delta frames (QM-468). A full frame (no delta key) is sent on connect and again on the next tick. After that each tick is {delta:true, rooms:[changed rooms], removed:[ids], totals, …}: only the rooms whose stats changed since the previous tick, plus the ids of rooms that are gone, with the same other keys as a full frame. Changed rooms replace theirs, new ones are appended (server order is creation order), and removed ones are dropped. A tick where rooms changed order is sent as a full frame (QM-480). A client that receives a delta with no full frame under it must reconnect, which is the resync.
• GET /api/admin/metrics?roomId=&range= → time series (joins/min, passes/min, queue depth) for charts
• GET /api/admin/health → effective config, storage state, misconfiguration warnings
• POST /api/admin/monitor-token → mints the read-only monitor credential (observe only; never ADMIN_KEY). GET lists live share links (a read, but not open to a monitor token itself); DELETE ?id= revokes one (?all=1 every one).
• GET /metrics → Prometheus exposition, a read credential required (monitor token, viewer or above; room ids and depths are commercially sensitive)
• GET / → admin.html. GET /progress → PROGRESS.html. GET /docs → the guides.

Quality bar (what critics judge)

• Waiting page: calm, branded, live position + honest ETA, progress bar, accessible (reduced-motion, aria-live), works on mobile, survives refresh/tab-close, auto-redirects on pass, no layout jank, offline/reconnect handling.
• Dashboard: live queue depth graphs, per-room controls that apply instantly, surge visible at a glance, keyboard accessible, dark UI acceptable, no fake data.
• Engine: 10k joins burst must not crash or reorder; FIFO invariant; rate change mid-surge honored; restart mid-surge loses nothing (STORE=valkey).
• Everything: no console errors, no dead buttons, no lorem ipsum.