Add waiting-queue UI and session-queue proxy

When the compute pool is busy the load balancer now hands back a queue ticket
instead of a grant. The Space relays it end to end:

- /api/session returns a grant or a ticket; /api/queue/{id} polls position and
reserves the daily budget only at claim (re-checking it there), so waiting in
line never costs usage time. Leave endpoints (DELETE + sendBeacon) drop the
ticket; a full queue relays 503 {state:"at_capacity"}.
- The client waits in the queue polling position, and uses a hybrid mic flow:
permission is primed in the tap gesture, but the capture stream is acquired
only once a slot is granted, so the mic indicator never glows while waiting.
- New calm "queued" orb state with a "Leave queue" button; queue-full and
ticket-expired land on a friendly retry state, not an error.

CONTEXT.md gains the queue vocabulary (Queue, Ticket, Position, Claim, At
capacity).

CONTEXT.md

@@ -79,3 +79,30 @@ than hidden behind a click.
 The popup opened from the (i) icon to the right of the identity block. Holds the
 general introduction to the speech-to-speech project (with a repo link) and the
 pipeline. Identity itself now lives in the corner, not here.
+
+## Queue
+The line of users waiting for a free conversation slot when every compute is
+busy. You join the queue instead of being turned away; you leave it by reaching
+the front or by giving up. Distinct from a *session* (an actual live
+conversation) — being in the queue is not yet talking, and time spent waiting
+never counts against your usage limit.
+
+## Ticket
+Your held place in the queue. Created when you join, it is what the demo checks
+to tell you your position and to notice if you have left. A ticket is not a
+session: it only promises a spot in line, not a compute.
+
+## Position
+How many people are ahead of you in the queue, shown while you wait ("You're #3
+in line"). It only ever counts down. Distinct from an *estimated wait* — the
+demo shows position, never a time, because wait time is unpredictable.
+
+## Claim
+The moment you reach the front and a free slot becomes yours — the queue hands
+off to a real session and the conversation begins. This is also the point where
+your usage limit first starts to matter (never while waiting).
+
+## At capacity
+The state where the queue itself is full, so new users can't even join the line
+and are asked to try again shortly. Distinct from simply *busy* (all computes
+taken but the queue still has room to wait in).

index.html

@@ -131,6 +131,10 @@
         </div>
 
         <p id="circle-caption" class="circle-caption" role="status">Tap to start</p>
+
+        <button id="leave-queue-btn" class="leave-queue-btn" type="button" hidden>
+          Leave queue
+        </button>
       </main>
 
       <footer class="footer">

main.js

@@ -13,7 +13,7 @@
  * client owns its own AudioContext (no `attachOutputTrack`), so we hand
  * it the MediaStream directly.
  *
- * @typedef {"idle" | "connecting" | "listening" | "user-speaking" | "processing" | "ai-speaking" | "error"} AppState
+ * @typedef {"idle" | "connecting" | "queued" | "listening" | "user-speaking" | "processing" | "ai-speaking" | "error"} AppState
  */
 
 import { S2sWsRealtimeClient } from "./ws/s2s-ws-client.js";
@@ -151,6 +151,7 @@ function saveTools() {
 const STATE_VIEWS = {
   idle:            { caption: "Tap to start",  disabled: false },
   connecting:      { caption: "Connecting",    disabled: true  },
+  queued:          { caption: "Waiting…",       disabled: true  },
   listening:       { caption: "",              disabled: false },
   "user-speaking": { caption: "",              disabled: false },
   processing:      { caption: "",              disabled: false },
@@ -162,6 +163,7 @@ const STATE_VIEWS = {
 const STATE_CLASS = {
   idle: "state-idle",
   connecting: "state-connecting",
+  queued: "state-queued",
   listening: "state-listening",
   "user-speaking": "state-user-speaking",
   processing: "state-processing",
@@ -182,6 +184,8 @@ const orbWrap = $(".orb-wrap");
 const micBtn = $("#mic-btn");
 /** @type {HTMLButtonElement} */
 const stopBtn = $("#stop-btn");
+/** @type {HTMLButtonElement} */
+const leaveQueueBtn = $("#leave-queue-btn");
 
 /** @type {HTMLButtonElement} */
 const settingsBtn = $("#settings-btn");
@@ -314,6 +318,9 @@ let limiterOn = false;
 let heartbeatTimer = 0;
 let trackedSessionId = "";
 let trackedTier = "";
+// The waiting-queue ticket id while we're in line (else ""). Used to leave the
+// queue on teardown / tab-close so we don't hold a phantom place.
+let queuedTicketId = "";
 
 /** @type {S2sWsRealtimeClient | null} */
 let client = null;
@@ -336,13 +343,19 @@ function setState(next) {
   micBtn.tabIndex = live ? 0 : -1;
   stopBtn.tabIndex = live ? 0 : -1;
 
+  // The "Leave queue" button shows only while waiting in line.
+  const queued = next === "queued";
+  leaveQueueBtn.hidden = !queued;
+  leaveQueueBtn.tabIndex = queued ? 0 : -1;
+
   updateRestartAvailability();
 }
 
 function updateRestartAvailability() {
   // Restart works from any settled state — it tears down a live call (if any)
-  // and reconnects with the current settings. Only block while mid-connect.
-  restartBtn.disabled = currentState === "connecting";
+  // and reconnects with the current settings. Only block while mid-connect or
+  // while waiting in the queue (restarting from there would just re-queue).
+  restartBtn.disabled = currentState === "connecting" || currentState === "queued";
   restartHint.hidden = false;
   restartHint.textContent = LIVE_STATES.has(currentState)
     ? "Reconnects now with the settings above."
@@ -973,6 +986,20 @@ async function handleStartError(err) {
     account.showLimit(err.tier);
     return;
   }
+  // The user left the queue (close() aborted the wait): teardown already reset
+  // the UI to idle, so there's nothing to report.
+  if (err && err.code === "aborted") return;
+  // The queue was full or our ticket timed out — recoverable, not a fault. Land
+  // on the retry state with a plain-language reason instead of an error dump.
+  if (err && (err.code === "queue-full" || err.code === "queue-expired")) {
+    await teardown();
+    setState("error");
+    setCaption(
+      err.code === "queue-full" ? "All lines busy — tap to retry" : "Queue timed out — tap to retry",
+      "error",
+    );
+    return;
+  }
   onFatalError(err);
 }
 
@@ -992,6 +1019,43 @@ stopBtn.addEventListener("click", async () => {
   await teardown();
 });
 
+// "Leave queue": tear down the pending connect (aborts the poll wait) and drop
+// our place in line. Same teardown path as stopping a live call.
+leaveQueueBtn.addEventListener("click", async () => {
+  await teardown();
+});
+
+const MIC_CONSTRAINTS = {
+  audio: { echoCancellation: true, noiseSuppression: true, autoGainControl: true },
+};
+
+/** Prompt for mic permission up front, then immediately release the tracks so no
+ *  recording indicator lingers during a queue wait. Throws a friendly error if the
+ *  user denies. */
+async function primeMicPermission() {
+  try {
+    const s = await navigator.mediaDevices.getUserMedia(MIC_CONSTRAINTS);
+    for (const track of s.getTracks()) track.stop();
+  } catch (err) {
+    throw new Error(
+      `Microphone access denied${err instanceof Error ? `: ${err.message}` : ""}`,
+    );
+  }
+}
+
+/** Acquire the live capture stream once a slot is granted. Permission was primed
+ *  in the tap gesture, so this is silent. Stored module-side for mute + teardown. */
+async function acquireMicStream() {
+  micStream = await navigator.mediaDevices.getUserMedia(MIC_CONSTRAINTS);
+  return micStream;
+}
+
+/** @param {number} position Update the queued caption ("You're #N in line"). */
+function onQueuePosition(position) {
+  const n = Number(position) || 0;
+  setCaption(n > 0 ? `You're #${n} in line` : "Waiting for a free slot…", "muted");
+}
+
 /**
  * Start a conversation. Pass a pre-created AudioContext when the caller already
  * made one inside the tap/click gesture (required on iOS); otherwise one is
@@ -1014,19 +1078,15 @@ async function doStart(audioContext = null) {
   // suspended and the whole pipeline would be silent.
   if (!audioContext) audioContext = createResumedAudioContext();
 
+  // Prime the mic permission now (get the prompt out of the way up front), then
+  // release it. The real capture stream is acquired only once a slot is granted
+  // (see acquireMicStream), so the mic 'in use' indicator never lights while we
+  // sit in the queue. Permission persists, so the later acquire is silent.
   try {
-    micStream = await navigator.mediaDevices.getUserMedia({
-      audio: {
-        echoCancellation: true,
-        noiseSuppression: true,
-        autoGainControl: true,
-      },
-    });
+    await primeMicPermission();
   } catch (err) {
     if (audioContext) void audioContext.close().catch(() => {});
-    throw new Error(
-      `Microphone access denied${err instanceof Error ? `: ${err.message}` : ""}`,
-    );
+    throw err;
   }
 
   // The webcam is started on arrival (autoStartCamera), so nothing to do here;
@@ -1036,13 +1096,19 @@ async function doStart(audioContext = null) {
     ...target,
     voice: settings.voice,
     instructions: effectiveInstructions(),
-    micStream,
+    acquireMic: acquireMicStream,
     tools: activeToolDefs(),
     noiseGate: gateParams(settings.noiseGate),
     ...(audioContext ? { audioContext } : {}),
   });
   client = c;
 
+  c.addEventListener("queue", (e) => {
+    const { position, queueId } = /** @type {CustomEvent<{ position: number; queueId: string }>} */ (e).detail;
+    if (queueId) queuedTicketId = queueId;
+    onQueuePosition(position);
+  });
+
   c.addEventListener("status", (e) => {
     const detail = /** @type {CustomEvent<{ status: string }>} */ (e).detail;
     onClientStatus(detail.status);
@@ -1080,6 +1146,9 @@ async function doStart(audioContext = null) {
   c.addEventListener("session", (e) => {
     const info = /** @type {CustomEvent<{ info: import("./ws/s2s-ws-client.js").WsSessionInfo }>} */ (e).detail.info;
     console.log("[ws] session created:", info.sessionId);
+    // A slot was granted — we're out of the queue; drop the ticket reference so
+    // teardown doesn't try to leave a line we already left.
+    queuedTicketId = "";
     // A metered tier (anon / free): heartbeat so the server can extend the
     // reservation and tell us when the daily budget runs out. PRO isn't limited.
     if (info.limited && info.sessionId) {
@@ -1163,6 +1232,24 @@ function endTrackedSession() {
   trackedTier = "";
 }
 
+/** Leave the waiting queue so the LB frees our place. sendBeacon so it still
+ *  fires on tab close; the LB also reaps the ticket on TTL as a backstop. */
+function endQueueTicket() {
+  if (!queuedTicketId) return;
+  const body = JSON.stringify({ queueId: queuedTicketId });
+  try {
+    const blob = new Blob([body], { type: "application/json" });
+    if (!navigator.sendBeacon("api/queue/end", blob)) {
+      void fetch("api/queue/end", {
+        method: "POST", headers: { "Content-Type": "application/json" }, body, keepalive: true,
+      }).catch(() => {});
+    }
+  } catch {
+    // Best-effort; the LB reaps the ticket on TTL anyway.
+  }
+  queuedTicketId = "";
+}
+
 /** @param {string} status */
 function onClientStatus(status) {
   switch (status) {
@@ -1170,6 +1257,9 @@ function onClientStatus(status) {
     case "connecting":
       setState("connecting");
       break;
+    case "queued":
+      setState("queued");
+      break;
     case "connected":
       setState("listening");
       break;
@@ -1194,6 +1284,7 @@ function onClientStatus(status) {
 async function teardown() {
   stopHeartbeat();
   endTrackedSession();
+  endQueueTicket();
   chat.reset({ dismiss: true });
   if (client) {
     try {
@@ -1238,7 +1329,7 @@ void autoStartCamera();
 void watchCameraPermission();
 
 // Reconcile a live session if the tab is closed/hidden mid-call (no teardown).
-window.addEventListener("pagehide", () => endTrackedSession());
+window.addEventListener("pagehide", () => { endTrackedSession(); endQueueTicket(); });
 
 requestAnimationFrame(() => {
   document.body.classList.remove("booting");

server.py

@@ -22,10 +22,18 @@ Endpoints:
   GET  /api/config           -> { search, lb, allowDirect, auth }
   GET  /api/me               -> login + tier + remaining budget (LB mode only)
   POST /api/search           -> { results, answer }  Google via Serper.dev
-  POST /api/session          -> proxies <LB>/session, reserves the first time chunk
+  POST /api/session          -> proxies <LB>/session: a grant, or a queue ticket
+  GET  /api/queue/{id}       -> proxies <LB>/queue/{id}: position, or a grant on claim
+  DELETE /api/queue/{id}     -> leave the queue (explicit "Leave queue" button)
+  POST /api/queue/end        -> leave the queue (sendBeacon on teardown)
   POST /api/session/heartbeat-> extend the reservation; { expired }
   POST /api/session/end      -> reconcile + refund (sendBeacon on teardown)
   /*                         -> static files (index.html, main.js, ...)
+
+When every compute slot is busy the load balancer hands back a queue ticket
+instead of a grant; the browser polls /api/queue/{id} until it reaches the front
+and a slot frees. Waiting reserves nothing — the daily budget is only reserved at
+the moment a slot is actually claimed (a grant), never while queued.
 """
 
 import asyncio
@@ -212,7 +220,8 @@ async def session(request: Request):
     # nothing is tracked. Within metering, unlimited tiers (pro, org) aren't either.
     tracked = LIMITER_ENABLED and limiter.budget_for(tier) is not None
 
-    # Refuse before troubling the LB if the day's budget is already gone.
+    # Refuse before troubling the LB if the day's budget is already gone. Done
+    # here (at enqueue) so we never put a user who can't talk into the queue.
     if tracked:
         rem = await asyncio.to_thread(limiter.remaining, keys, tier)
         if rem is not None and rem <= 0:
@@ -231,6 +240,16 @@ async def session(request: Request):
         logger.warning("Load balancer unreachable: %r", exc)
         raise HTTPException(status_code=502, detail="Speech service unreachable.")
 
+    # The queue is full: the LB replies 503 {state:"at_capacity"}. Relay it as-is
+    # so the client shows a soft "try again shortly", not a hard error.
+    if lb.status_code == 503:
+        body = _safe_json(lb)
+        if body.get("state") == "at_capacity":
+            resp = JSONResponse({"state": "at_capacity"}, status_code=503)
+            if set_cookie:
+                auth.set_anon_cookie(resp, set_cookie)
+            return resp
+
     if lb.status_code != 200:
         # The LB's error body may name the reason (e.g. capacity); it carries no
         # secret, so relay a trimmed copy.
@@ -238,6 +257,100 @@ async def session(request: Request):
         raise HTTPException(status_code=502, detail=f"Session handshake failed ({lb.status_code}).")
 
     data = lb.json()
+
+    # Busy pool: the LB queued us. Relay the ticket untouched — crucially with NO
+    # reservation, so waiting in line never costs the day's budget.
+    if data.get("state") == "queued":
+        data["tier"] = tier
+        resp = JSONResponse(data)
+        if set_cookie:
+            auth.set_anon_cookie(resp, set_cookie)
+        return resp
+
+    # A slot was free: reserve the first chunk now and return the grant.
+    return await _finalize_grant(data, keys, tier, tracked, set_cookie)
+
+
+@app.get("/api/queue/{queue_id}")
+async def queue_status(queue_id: str, request: Request):
+    """Poll a waiting ticket: relay the position, or — when the head of the line
+    claims a freed slot — reserve the budget now and return the grant. Re-checks the
+    daily budget at claim, since a multi-minute wait could have spent it elsewhere."""
+    if not LOAD_BALANCER_URL:
+        raise HTTPException(status_code=404, detail="Not found.")
+
+    tier, keys, set_cookie = auth.resolve_identity(request)
+    tracked = LIMITER_ENABLED and limiter.budget_for(tier) is not None
+
+    url = f"{LOAD_BALANCER_URL.rstrip('/')}/queue/{queue_id}"
+    try:
+        async with httpx.AsyncClient(timeout=15.0) as http:
+            lb = await http.get(url)
+    except httpx.RequestError as exc:
+        logger.warning("Load balancer unreachable: %r", exc)
+        raise HTTPException(status_code=502, detail="Speech service unreachable.")
+
+    if lb.status_code == 404:
+        # Ticket unknown/expired (reaped after we stopped polling). Tell the client
+        # to start over rather than spin.
+        resp = JSONResponse({"state": "expired"}, status_code=404)
+        if set_cookie:
+            auth.set_anon_cookie(resp, set_cookie)
+        return resp
+
+    if lb.status_code != 200:
+        logger.warning("Queue poll failed %s: %s", lb.status_code, lb.text[:300])
+        raise HTTPException(status_code=502, detail=f"Queue poll failed ({lb.status_code}).")
+
+    data = lb.json()
+
+    if data.get("state") == "queued":
+        data["tier"] = tier
+        resp = JSONResponse(data)
+        if set_cookie:
+            auth.set_anon_cookie(resp, set_cookie)
+        return resp
+
+    # Claimed a slot. Re-check the budget: it may have been spent in another tab
+    # during the wait. If so, refuse — the just-claimed slot is now a pending
+    # session on the LB and its pending-timeout reaper reclaims it shortly.
+    if tracked:
+        rem = await asyncio.to_thread(limiter.remaining, keys, tier)
+        if rem is not None and rem <= 0:
+            resp = JSONResponse(
+                {"tier": tier, "reason": "limit", "remainingSec": 0}, status_code=402
+            )
+            if set_cookie:
+                auth.set_anon_cookie(resp, set_cookie)
+            return resp
+
+    return await _finalize_grant(data, keys, tier, tracked, set_cookie)
+
+
+@app.delete("/api/queue/{queue_id}")
+async def queue_leave(queue_id: str):
+    """Leave the queue from the explicit 'Leave queue' button (a real fetch)."""
+    if not LOAD_BALANCER_URL:
+        raise HTTPException(status_code=404, detail="Not found.")
+    await _lb_leave(queue_id)
+    return {"ok": True}
+
+
+@app.post("/api/queue/end")
+async def queue_end(request: Request):
+    """Leave the queue on teardown/tab-close (navigator.sendBeacon, which can only
+    POST). Body: { queueId }. Best-effort; the LB reaps the ticket on TTL anyway."""
+    if not LOAD_BALANCER_URL:
+        raise HTTPException(status_code=404, detail="Not found.")
+    qid = await _queue_id(request)
+    if qid:
+        await _lb_leave(qid)
+    return {"ok": True}
+
+
+async def _finalize_grant(data, keys, tier, tracked, set_cookie):
+    """Shared grant tail (fast path or queue claim): reserve the first chunk, attach
+    the metering fields the client needs, and set the anon cookie."""
     remaining = None
     if tracked and data.get("session_id"):
         await asyncio.to_thread(limiter.begin, data["session_id"], keys, tier)
@@ -255,6 +368,33 @@ async def session(request: Request):
     return resp
 
 
+async def _lb_leave(queue_id: str) -> None:
+    """Best-effort: tell the LB to drop a waiting ticket."""
+    url = f"{LOAD_BALANCER_URL.rstrip('/')}/queue/{queue_id}"
+    try:
+        async with httpx.AsyncClient(timeout=5.0) as http:
+            await http.delete(url)
+    except httpx.RequestError as exc:
+        logger.warning("Queue leave failed: %r", exc)
+
+
+def _safe_json(response) -> dict:
+    try:
+        body = response.json()
+    except Exception:
+        return {}
+    return body if isinstance(body, dict) else {}
+
+
+async def _queue_id(request: Request) -> str:
+    """Pull `queueId` from a JSON body, tolerating sendBeacon's blob posts."""
+    try:
+        data = await request.json()
+    except Exception:
+        return ""
+    return (data or {}).get("queueId", "") if isinstance(data, dict) else ""
+
+
 async def _session_id(request: Request) -> str:
     """Pull `sessionId` from a JSON body, tolerating sendBeacon's blob posts."""
     try:

style.css

@@ -778,6 +778,7 @@ a:hover {
 .state-connected .ind-spinner,
 .state-auto-selecting .ind-spinner,
 .state-starting .ind-spinner,
+.state-queued .ind-spinner,
 .state-processing .ind-thinking,
 .state-listening .ind-bars,
 .state-user-speaking .ind-bars,
@@ -846,6 +847,34 @@ a:hover {
   letter-spacing: 0.08em;
 }
 
+/* "Leave queue": a quiet outlined pill under the caption, shown only while
+ * waiting. Understated to match the caption — it's an escape hatch, not a CTA. */
+.leave-queue-btn {
+  margin-top: 14px;
+  padding: 7px 16px;
+  font-family: var(--font-mono);
+  font-size: 11px;
+  font-weight: 500;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  color: var(--text-faint);
+  background: transparent;
+  border: 1px solid color-mix(in srgb, var(--text-faint) 35%, transparent);
+  border-radius: 999px;
+  cursor: pointer;
+  transition: color 0.2s ease, border-color 0.2s ease, background 0.2s ease;
+}
+.leave-queue-btn:hover {
+  color: var(--text);
+  border-color: color-mix(in srgb, var(--text-faint) 60%, transparent);
+  background: color-mix(in srgb, var(--text-faint) 8%, transparent);
+}
+.leave-queue-btn:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+.leave-queue-btn[hidden] { display: none; }
+
 /* ─── Tool-call toaster ───────────────────────────────────────────────── */
 
 /* A small, non-interactive pill that appears below the circle when the
@@ -1091,6 +1120,11 @@ body.booting *::after {
 .circle.state-connected,
 .circle.state-auto-selecting,
 .circle.state-starting     { --glow: #facc15; }
+/* Queued: a calm slate glow, distinct from connecting's active yellow — this is
+ * waiting, not working. The spinner turns slowly and the ring breathes. */
+.circle.state-queued       { --glow: #94a3b8; }
+.circle.state-queued .ind-spinner { animation-duration: 2.4s; }
+.circle.state-queued .circle-ring { animation: breathe 2.6s ease-in-out infinite; }
 .circle.state-listening,
 .circle.state-user-speaking { --glow: var(--listening); }
 .circle.state-processing   { --glow: var(--processing); }

ws/s2s-ws-client.js

@@ -23,7 +23,7 @@
  * sees high-level lifecycle events (`status`, `transcript`, `error`,
  * `session`), the same shape as the WebRTC client.
  *
- * @typedef {"idle" | "creating-session" | "connecting" | "connected" |
+ * @typedef {"idle" | "creating-session" | "queued" | "connecting" | "connected" |
  *           "user-speaking" | "processing" | "ai-speaking" | "closed" | "error"
  * } WsStatus
  *
@@ -50,7 +50,11 @@
  *   session POST and dials it directly — no load balancer in between.
  * @property {string} voice
  * @property {string} instructions
- * @property {MediaStream} micStream
+ * @property {MediaStream} [micStream] Live mic stream. Provide this OR `acquireMic`.
+ * @property {() => Promise<MediaStream>} [acquireMic] Lazily obtain the mic stream,
+ *   called only once a session is actually granted (after any queue wait). Lets the
+ *   caller prime mic permission up front but not hold the mic 'in use' indicator on
+ *   while waiting in line. Ignored if `micStream` is already set.
  * @property {AudioContext} [audioContext] Pre-created (and resumed) context.
  *   iOS Safari only lets an AudioContext start from within a user gesture, so
  *   the caller creates/resumes it synchronously on the orb tap and hands it
@@ -85,6 +89,16 @@ import {
 } from "./codec.js";
 import { OrbVisualiser, VIS_FFT_SIZE } from "./orb-visualizer.js";
 
+/** Build an Error carrying a `code` (and optional extra fields) so callers can
+ *  branch on the failure kind: "limit" | "queue-full" | "queue-expired" | "aborted".
+ *  @param {string} message @param {string} code @param {object} [extra] */
+function _codedError(message, code, extra) {
+  const err = /** @type {Error & { code?: string }} */ (new Error(message));
+  err.code = code;
+  if (extra) Object.assign(err, extra);
+  return err;
+}
+
 // The s2s pipeline runs internally at 16 kHz mono PCM. The WebRTC transport
 // resamples to 48 kHz for Opus, but the WebSocket transport emits the
 // native pipeline rate. We don't (can't) override it via `audio.output.format`
@@ -111,6 +125,16 @@ export class S2sWsRealtimeClient extends EventTarget {
       : options.loadBalancerUrl
         ? `${trimTrailingSlash(options.loadBalancerUrl)}/session`
         : "";
+    /** @type {(() => Promise<MediaStream>) | null} Lazy mic acquisition (post-grant). */
+    this._acquireMic = options.acquireMic ?? null;
+    /** @type {boolean} Set by close() to abort a queue wait in progress. */
+    this._closed = false;
+    /** @type {string} The active queue ticket id while waiting (else ""). */
+    this._queueId = "";
+    /** @type {(() => void) | null} Wakes the queue poll sleep early on close(). */
+    this._queueWake = null;
+    /** @type {ReturnType<typeof setTimeout> | 0} */
+    this._queueTimer = 0;
     /** @type {NoiseGate} Mic noise gate; off by default. */
     this._noiseGate = options.noiseGate ?? { enabled: false, thresholdDb: -45 };
     /** @type {WebSocket | null} */
@@ -213,12 +237,20 @@ export class S2sWsRealtimeClient extends EventTarget {
         throw new Error("No session endpoint or direct URL configured");
       }
       this._setStatus("creating-session");
-      const session = await this._createSession();
+      const session = await this._createSessionOrQueue();
+      if (this._closed) throw _codedError("connect aborted", "aborted");
       this.dispatchEvent(new CustomEvent("session", { detail: { info: session } }));
       connectUrl = session.connectUrl;
       this._setStatus("connecting");
     }
 
+    // Acquire the mic now — only once a slot is actually ours. The caller primed
+    // permission up front, so this is silent and the 'in use' indicator lights
+    // only for a real, connecting session (never during a queue wait).
+    if (!this.options.micStream && this._acquireMic) {
+      this.options.micStream = await this._acquireMic();
+    }
+
     // Spin up the AudioContext + worklets in parallel with the WS dial.
     const audioReady = this._setupAudio();
     const wsReady = this._openWebSocket(connectUrl);
@@ -226,9 +258,24 @@ export class S2sWsRealtimeClient extends EventTarget {
   }
 
   /**
+   * POST the session handshake; if the pool is busy, wait in the queue (polling
+   * position) until a slot is claimed. Resolves to a grant either way.
    * @returns {Promise<WsSessionInfo>}
    */
-  async _createSession() {
+  async _createSessionOrQueue() {
+    const first = await this._postSession();
+    if (first.state === "queued") {
+      this._setStatus("queued");
+      return await this._pollQueue(first);
+    }
+    return first.grant;
+  }
+
+  /**
+   * POST /session once. Returns either a granted session or a queue ticket.
+   * @returns {Promise<{ state: "granted", grant: WsSessionInfo } | { state: "queued", queueId: string, position: number, pollIntervalS: number }>}
+   */
+  async _postSession() {
     const url = this._sessionUrl;
     console.log("[ws] POST", url);
     const response = await fetch(url, {
@@ -240,18 +287,98 @@ export class S2sWsRealtimeClient extends EventTarget {
       // The session proxy refused: today's per-tier time budget is spent. Surface
       // it as a typed error so the UI shows the limit modal, not a crash.
       const body = await response.json().catch(() => ({}));
-      const err = /** @type {Error & { code?: string; tier?: string }} */ (
-        new Error("Daily conversation limit reached")
-      );
-      err.code = "limit";
-      err.tier = body?.tier;
-      throw err;
+      throw _codedError("Daily conversation limit reached", "limit", { tier: body?.tier });
+    }
+    if (response.status === 503) {
+      const body = await response.json().catch(() => ({}));
+      if (body?.state === "at_capacity") {
+        throw _codedError("The queue is full — try again shortly.", "queue-full");
+      }
+      throw new Error("/session failed (503)");
     }
     if (!response.ok) {
       const text = await response.text().catch(() => "");
       throw new Error(`/session failed (${response.status}): ${text}`);
     }
     const json = await response.json();
+    if (json.state === "queued") {
+      return {
+        state: "queued",
+        queueId: json.queue_id,
+        position: json.position,
+        pollIntervalS: json.poll_interval_s,
+      };
+    }
+    return { state: "granted", grant: this._parseGrant(json) };
+  }
+
+  /**
+   * Poll the waiting queue until this ticket claims a slot. Emits `queue` events
+   * ({ position }) as the line advances. Throws on limit (402), expiry (404), or
+   * close(). Transient network/5xx blips are ignored and retried next tick.
+   * @param {{ queueId: string, position: number, pollIntervalS: number }} ticket
+   * @returns {Promise<WsSessionInfo>}
+   */
+  async _pollQueue(ticket) {
+    const intervalMs = Math.max(1, ticket.pollIntervalS || 2) * 1000;
+    this._queueId = ticket.queueId;
+    this._emitQueue(ticket.position);
+
+    while (true) {
+      await this._queueSleep(intervalMs);
+      if (this._closed) throw _codedError("queue wait aborted", "aborted");
+
+      let response;
+      try {
+        response = await fetch(`api/queue/${encodeURIComponent(this._queueId)}`, {
+          headers: { "Content-Type": "application/json" },
+        });
+      } catch {
+        continue; // network blip — keep our place, retry next tick
+      }
+
+      if (response.status === 402) {
+        const body = await response.json().catch(() => ({}));
+        throw _codedError("Daily conversation limit reached", "limit", { tier: body?.tier });
+      }
+      if (response.status === 404) {
+        throw _codedError("Queue timed out", "queue-expired");
+      }
+      if (!response.ok) continue; // 502/503 — transient, retry
+
+      const json = await response.json().catch(() => null);
+      if (!json) continue;
+      if (json.state === "queued") {
+        this._emitQueue(json.position);
+        continue;
+      }
+      // Reached the front and claimed a slot.
+      this._queueId = "";
+      return this._parseGrant(json);
+    }
+  }
+
+  /** @param {number} position */
+  _emitQueue(position) {
+    this.dispatchEvent(
+      new CustomEvent("queue", { detail: { position, queueId: this._queueId } }),
+    );
+  }
+
+  /** A sleep that close() can cut short so a queued client tears down promptly.
+   *  @param {number} ms */
+  _queueSleep(ms) {
+    return new Promise((resolve) => {
+      this._queueWake = resolve;
+      this._queueTimer = setTimeout(() => {
+        this._queueWake = null;
+        resolve();
+      }, ms);
+    });
+  }
+
+  /** @param {any} json @returns {WsSessionInfo} */
+  _parseGrant(json) {
     return {
       sessionId: json.session_id,
       connectUrl: json.connect_url,
@@ -842,6 +969,15 @@ export class S2sWsRealtimeClient extends EventTarget {
   }
 
   async close() {
+    // Abort a queue wait in progress: flag it and wake the poll sleep so
+    // `_pollQueue` throws "aborted" and connect() unwinds cleanly.
+    this._closed = true;
+    if (this._queueWake) {
+      clearTimeout(this._queueTimer);
+      const wake = this._queueWake;
+      this._queueWake = null;
+      wake();
+    }
     this._visualiser?.stop();
     this._visualiser = null;
     try {