@dopamint-fun/open-sdk 0.1.0-dev.0 → 0.2.0-dev.1

package/dist/session.js

@@ -3,8 +3,8 @@ import { blake2b256 } from "./crypto.js";
 import { equalBytes, fromHex, textBytes, toHex0x } from "./bytes.js";
 import { AGENT_HTTP_CAPABILITY_HEADER, mintAgentHttpCapability, } from "./agentHttp.js";
 import { signRaw } from "./keypair.js";
-import { decodeAuthorityMessage, decodeEnvelope, encodeAckFrame, encodeEnvelope, encodeSeatAuthSuccessFrame, sessionErrorHint, sessionErrorName, } from "./sessionCodec.js";
-import { actionSigningBytes, encodeActionFrame, encodeJoinFrame, encodeResumeFrame, joinSigningBytes, resumeSigningBytes, } from "./sessionWire.js";
+import { MAX_TRANSPORT_FRAME_BYTES, PredictionGateConflictError, SessionBoundaryError, admitAuthorityEvent, decodeAuthorityMessage, freshSessionBoundary, decodeEnvelope, encodeAckFrame, encodeEnvelope, encodeSeatAuthSuccessFrame, sessionErrorHint, sessionErrorName, } from "./sessionCodec.js";
+import { actionSigningBytes, encodeActionFrame, encodeJoinFrame, encodeResumeFrame, joinSigningBytes, requireSessionVersion, resumeSigningBytes, SESSION_VERSION, UnsupportedSessionVersionError, } from "./sessionWire.js";
 import { decodeLegalActions, decodeParticipantView, encodeAction, pickAction, } from "./texas.js";
 import { authorizeSeatChallenge } from "./seatAuth.js";
 const ACTION_IDENTITY_DOMAIN = textBytes("dopa_open::client::action_identity_v1");
@@ -26,8 +26,41 @@ export function playReportLines(report) {
         lines.push(`rejoins ${report.rejoins}`);
     if (report.said > 0 || report.saidRefused > 0)
         lines.push(`said ${report.said} refused ${report.saidRefused}`);
+    lines.push(`eliminated ${report.eliminated}`);
     return lines;
 }
+/** How often a seat with nothing to decide reads the public table.
+ *
+ *  A seat that is out of the hand, or out of the sitting, is sent views with no
+ *  legal actions for as long as the others play, and the table used to be read
+ *  only when there was a decision to make -- so a busted seat read nothing and
+ *  printed nothing for the rest of the sitting. Slow, because the read is the
+ *  same one the anonymous cap counts. */
+export const IDLE_TABLE_READ_MS = 5_000;
+/** Watches the public table for this seat losing its last chip.
+ *
+ *  Out means no chips and not all in: a seat all in with nothing behind is
+ *  still in the hand, and only once the hand has settled against it does its
+ *  stack read zero with no bet out. `observe` answers true exactly once, the
+ *  first time it sees that, so the line it drives is printed once however many
+ *  hands the others go on to play. */
+export function eliminationWatch(seat) {
+    let out = false;
+    return {
+        get eliminated() {
+            return out;
+        },
+        observe(table) {
+            if (out || !table)
+                return false;
+            const mine = table.seats.find((entry) => entry.seat === seat);
+            if (!mine || mine.stack !== 0 || mine.allIn)
+                return false;
+            out = true;
+            return true;
+        },
+    };
+}
 /* A session-protocol refusal, with the tag kept on it.
  *
  * `postWire` and the message loop used to throw a plain Error whose text named
@@ -50,6 +83,30 @@ export class SessionRefusal extends Error {
 const UNKNOWN_SESSION = 6;
 const INVALID_RESUME_CURSOR = 7;
 const SESSION_SUPERSEDED = 10;
+/** The shared binding's discovery read bound (`MAX_DISCOVERY_RESPONSE_BYTES`).
+ *  A document larger than this is not a discovery document this client reads. */
+const MAX_DISCOVERY_RESPONSE_BYTES = 4096;
+/** How long a seat keeps asking for discovery from an origin that is not
+ *  answering: long enough to outlast a deployment restarting behind it, short
+ *  enough that a seat whose authority is truly gone still stops. */
+export const DISCOVERY_RETRY_BOUND_MS = 90_000;
+const DISCOVERY_RETRY_PAUSE_MS = 1_000;
+/** Statuses an origin gives while it is coming back, rather than a verdict on
+ *  whether it can host the session. */
+function discoveryMayAnswerLater(status) {
+    return (status === 404 ||
+        status === 408 ||
+        status === 425 ||
+        status === 429 ||
+        status >= 500);
+}
+class SessionDiscoveryRefused extends Error {
+    status;
+    constructor(status) {
+        super(`session discovery failed (${status})`);
+        this.status = status;
+    }
+}
 /** Whether this turn is still open at `nowMs`.
  *
  *  A predicate rather than a comparison in the loop, for the same reason
@@ -93,7 +150,10 @@ export async function chooseSeatAction(legal, view, strategy, decide, context =
         legal,
         view,
         seat: own.receivingSeat,
-        hole: own.holeCards,
+        hole: own.holeCards
+            ? [own.holeCards[0].label, own.holeCards[1].label]
+            : null,
+        holeCards: own.holeCards,
         executionId: context.executionId,
         table,
         seats: table?.seats ?? [],
@@ -145,9 +205,91 @@ export class SessionClient {
         this.clientNonce = clientNonce;
         this.fetchImpl = fetchImpl;
     }
+    /** How long discovery keeps asking an authority that is not answering.
+     *
+     *  Public so a test can shorten it; nothing else should need to. */
+    discoveryRetry = {
+        boundMs: DISCOVERY_RETRY_BOUND_MS,
+        pauseMs: DISCOVERY_RETRY_PAUSE_MS,
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    };
     url(path) {
         return `${this.baseUrl.replace(/\/$/, "")}${path}`;
     }
+    /** Requires the authority's published discovery to host the current session
+     *  contract, before any challenge, signature, or session request.
+     *
+     *  Discovery is a compatibility predicate over published facts, never an
+     *  authenticity claim: the join handshake is still the admission decision.
+     *  The body is read under the same bound the shared binding enforces, so a
+     *  hostile pre-join answer cannot stream into this process. A document that
+     *  names no compatible contract is final -- an authority that cannot host
+     *  the session does not become able to by asking again.
+     *
+     *  An origin that did not answer with a document is another matter, and is
+     *  asked again within `discoveryRetry`. A seat reconnects at whatever moment
+     *  its stream dropped, and a deployment restarting behind that origin
+     *  answers 404, 502 or nothing for a few seconds. Taken as final, one such
+     *  answer ended a seat mid-sitting while its table played on without it, and
+     *  the clock folded every turn it had left. */
+    async requireCompatibleDiscovery() {
+        const response = await this.answeredDiscovery();
+        const document = JSON.parse(await this.readBoundedDiscovery(response));
+        const wires = document.wire_versions;
+        const sessions = document.session_versions;
+        const ceiling = document.max_transport_frame_bytes;
+        if (!Array.isArray(wires) ||
+            !Array.isArray(sessions) ||
+            !wires.includes(1) ||
+            !sessions.includes(SESSION_VERSION) ||
+            typeof ceiling !== "number" ||
+            !Number.isFinite(ceiling) ||
+            ceiling < MAX_TRANSPORT_FRAME_BYTES)
+            throw new Error("authority discovery does not support participant session V3");
+    }
+    async answeredDiscovery() {
+        const { boundMs, pauseMs, sleep } = this.discoveryRetry;
+        const until = Date.now() + boundMs;
+        for (;;) {
+            let refusal;
+            try {
+                const response = await this.fetchImpl(this.url("/v1/session/discovery"));
+                if (response.ok)
+                    return response;
+                if (!discoveryMayAnswerLater(response.status))
+                    throw new SessionDiscoveryRefused(response.status);
+                refusal = `session discovery failed (${response.status})`;
+                await response.body?.cancel();
+            }
+            catch (error) {
+                if (error instanceof SessionDiscoveryRefused)
+                    throw error;
+                refusal = `session discovery failed (${error instanceof Error ? error.message : String(error)})`;
+            }
+            if (Date.now() + pauseMs > until)
+                throw new Error(`${refusal}; still refused after ${boundMs} ms`);
+            await sleep(pauseMs);
+        }
+    }
+    async readBoundedDiscovery(response) {
+        const reader = response.body?.getReader();
+        if (!reader)
+            return "";
+        const chunks = [];
+        let total = 0;
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.length;
+            if (total > MAX_DISCOVERY_RESPONSE_BYTES) {
+                await reader.cancel();
+                throw new Error("session discovery exceeds 4096 bytes");
+            }
+            chunks.push(value);
+        }
+        return Buffer.concat(chunks).toString("utf8");
+    }
     async challenge() {
         const response = await this.fetchImpl(this.url("/v1/session/challenge"), {
             method: "POST",
@@ -165,14 +307,15 @@ export class SessionClient {
             throw new Error(`challenge must be 74 bytes, got ${bytes.length}`);
         return new Uint8Array(bytes);
     }
-    async postWire(path, wire, withToken) {
+    async postWire(path, wire, withToken, tokenOverride) {
         const headers = {
             "content-type": "application/json",
         };
         if (withToken) {
-            if (!this.token)
+            const token = tokenOverride ?? this.token;
+            if (!token)
                 throw new Error("session token missing");
-            headers["session-token"] = this.token;
+            headers["session-token"] = token;
         }
         let lastError = "";
         let lastRefusal = null;
@@ -198,7 +341,11 @@ export class SessionClient {
                     }
                 }
             }
-            catch {
+            catch (error) {
+                /* A selected version this build cannot speak is not a transport
+                   flake: rethrow it rather than retrying the raw status. */
+                if (error instanceof UnsupportedSessionVersionError)
+                    throw error;
                 /* keep raw body */
             }
             if (!retryable)
@@ -212,10 +359,11 @@ export class SessionClient {
             : new Error(lastError);
     }
     async join() {
+        await this.requireCompatibleDiscovery();
         const challenge = await this.challenge();
         const request = {
             wireVersion: 1,
-            supportedSessionVersions: [1],
+            supportedSessionVersions: [SESSION_VERSION],
             executionId: this.executionId,
             executionManifestDigest: this.executionManifestDigest,
             participantId: this.participantId,
@@ -236,6 +384,7 @@ export class SessionClient {
                 throw new Error("join did not return a session token");
             this.token = body.token;
         }
+        this.eventsAfter = 0n;
         const batch = await this.pollEvents();
         if (!batch.messages.some((message) => message.type === "sessionJoined"))
             throw new Error("join did not deliver SessionJoined");
@@ -302,12 +451,17 @@ export class SessionClient {
     startSubmit(wire) {
         return this.postWire("/v1/session/actions", wire, true);
     }
-    async acknowledge(context, cursor) {
-        const response = await this.postWire("/v1/session/acknowledgements", encodeAckFrame(context, cursor), true);
+    async acknowledge(context, cursor, originToken) {
+        const response = await this.postWire("/v1/session/acknowledgements", encodeAckFrame(context, cursor), true, originToken);
         if (!response.ok)
             throw new Error(`ack failed (${response.status}): ${await response.text()}`);
     }
     async resume(context, cursor) {
+        /* A retained context from another session version is not resumable: its
+           cursor and token belong to a contract this build does not speak. This
+           runs first so no challenge, signature, or request is spent on it. */
+        requireSessionVersion(context.sessionVersion);
+        await this.requireCompatibleDiscovery();
         const challenge = await this.challenge();
         const request = {
             context,
@@ -323,6 +477,13 @@ export class SessionClient {
         const headerToken = response.headers.get("session-token");
         if (headerToken)
             this.token = headerToken;
+        /* A resumed binding delivers from a buffer of its own, indexed from zero;
+           `after` is an index into that buffer, not the stream position the last
+           binding reached. Kept, it asked a fresh buffer for everything past the
+           old index, so every poll came back empty while the authority's queue for
+           this seat filled and closed: a seat that resumed once, late in a
+           sitting, never saw another turn. */
+        this.eventsAfter = 0n;
     }
     async answerSeatAuth(challenge, coordinatorKey, timeAuthorityKey, pending) {
         const preimage = authorizeSeatChallenge({
@@ -340,10 +501,40 @@ export class SessionClient {
             throw new Error(`seat-authorization failed (${response.status}): ${await response.text()}`);
     }
 }
-export async function playSeat(args) {
+/** A GET asked again while the origin answers as a restarting one does -- no
+ *  answer, 408, 429 or a 5xx -- until `bound` has passed. Any other answer is
+ *  returned as it came, so a refusal stays the caller's to read. */
+export async function fetchWhileRestarting(fetchImpl, url, retry = {
+    boundMs: DISCOVERY_RETRY_BOUND_MS,
+    pauseMs: DISCOVERY_RETRY_PAUSE_MS,
+}) {
+    const sleep = retry.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const until = Date.now() + retry.boundMs;
+    for (;;) {
+        const lastChance = Date.now() + retry.pauseMs > until;
+        try {
+            const response = await fetchImpl(url);
+            const restarting = response.status === 408 ||
+                response.status === 429 ||
+                response.status >= 500;
+            if (!restarting || lastChance)
+                return response;
+            await response.body?.cancel();
+        }
+        catch (error) {
+            if (lastChance)
+                throw error;
+        }
+        await sleep(retry.pauseMs);
+    }
+}
+export async function openSeatSession(args) {
     const fetchImpl = args.fetchImpl ?? fetch;
     const product = args.productUrl.replace(/\/$/, "");
-    const offer = await fetchImpl(`${product}/open/v1/playground/matches/${args.offerId}`);
+    /* Read again while the product is coming back: a seat reopens its session
+       after every dropped stream, and the product answering 502 for the seconds
+       it restarts ended the seat as surely as a refusal would have. */
+    const offer = await fetchWhileRestarting(fetchImpl, `${product}/open/v1/playground/matches/${args.offerId}`, args.restartRetry);
     if (!offer.ok)
         throw new Error(`offer read failed (${offer.status}): ${await offer.text()}`);
     const record = (await offer.json());
@@ -374,9 +565,29 @@ export async function playSeat(args) {
         throw new Error("the admission names no time-authority key; pass timeAuthorityKey");
     const executionHex = record.admission.execution_id.replace(/^0x/i, "");
     const executionId = `0x${executionHex}`;
-    const nonce = new Uint8Array(randomBytes(32));
-    nonce[0] = args.seat & 0xff;
+    const nonce = args.clientNonce ?? new Uint8Array(randomBytes(32));
+    if (!args.clientNonce)
+        nonce[0] = args.seat & 0xff;
     const client = new SessionClient(record.admission.session_base_url, args.agent, args.seat, args.agentId, fromHex(record.admission.execution_id), fromHex(record.admission.manifest_digest), nonce, fetchImpl);
+    return {
+        client,
+        product,
+        executionHex,
+        coordinatorKey,
+        timeAuthorityKey,
+        sessionBaseUrl: record.admission.session_base_url,
+        executionId,
+    };
+}
+export async function playSeat(args) {
+    const fetchImpl = args.fetchImpl ?? fetch;
+    const { client, product, executionHex, coordinatorKey, timeAuthorityKey, executionId, } = await openSeatSession(args);
+    const record = {
+        admission: {
+            execution_id: executionId,
+            session_base_url: client.baseUrl,
+        },
+    };
     const strategy = args.strategy ?? "fold-heavy";
     const decide = args.decide;
     const acted = new Set();
@@ -386,18 +597,33 @@ export async function playSeat(args) {
     let said = 0;
     let saidRefused = 0;
     let lastHandSeen = null;
+    const elimination = eliminationWatch(args.seat);
+    let lastIdleTableReadMs = 0;
     /* Who the other seats are, read once per agent for the whole sitting: a
        name does not change mid-match, and a read per turn would be a read per
        turn per seat. */
     const names = new Map();
+    /* The seat's own key on the table read. Without it a seat in a private room
+       is just another stranger at the door, and the decision below would be made
+       against a null table while the agent was sitting at it. */
+    const tableCapability = agentReadCapability(args.agent, args.agentId);
     let disconnectExerciseDone = false;
     let pending = null;
     let lastContext = null;
     let lastCursor = { sequence: 0n, witnessedReceipt: null };
+    /* What this seat has accepted: the event sequence, the receipt floor, the
+       view it was last shown, and the named gate phase it holds. Every event
+       goes through it before anything is acknowledged, so the two doors -- this
+       loop and `openTurn` -- refuse the same streams for the same reasons. */
+    let accepted = freshSessionBoundary();
     const inbox = [];
     let joined = await client.join();
     if (joined.context)
         lastContext = joined.context;
+    const joinedToken = client.token;
+    if (!joinedToken)
+        throw new Error("join did not return a session token");
+    let originToken = joinedToken;
     const handle = async (message) => {
         if (message.type === "error") {
             if (message.retryable)
@@ -413,11 +639,34 @@ export async function playSeat(args) {
         if (message.type === "actionPending" ||
             message.type === "actionAcknowledged")
             return null;
+        if (message.type === "predictionGatePrepared" ||
+            message.type === "predictionGateOpened" ||
+            message.type === "predictionGateReleased") {
+            /* A named notice moves no receipt and carries no view: it is accepted,
+               acknowledged, and waited on. Only the real view that follows a
+               release is a turn to decide. */
+            const admitted = admitAuthorityEvent(accepted, message);
+            if (admitted.disposition !== "applied")
+                return null;
+            accepted = admitted.boundary;
+            lastContext = message.context;
+            await client.acknowledge(message.context, message.cursor, originToken);
+            lastCursor = message.cursor;
+            return null;
+        }
         if ("context" in message)
             lastContext = message.context;
         if (message.type === "sessionTerminal") {
-            await client.acknowledge(message.context, message.cursor);
-            lastCursor = message.cursor;
+            const admitted = admitAuthorityEvent(accepted, message);
+            /* A re-delivered terminal is this boundary's own last event - a resume
+               at the terminal cursor repeats it. There is nothing to apply and its
+               acknowledgement is spent, but the sitting is over either way and the
+               caller still needs what `consent` takes. */
+            if (admitted.disposition === "applied") {
+                accepted = admitted.boundary;
+                await client.acknowledge(message.context, message.cursor, originToken);
+                lastCursor = message.cursor;
+            }
             return {
                 outcome: "terminal",
                 committedActions,
@@ -425,6 +674,7 @@ export async function playSeat(args) {
                 rejoins,
                 said,
                 saidRefused,
+                eliminated: elimination.eliminated,
                 terminalNonce: message.finalState.nonce.toString(),
                 terminalCommitment: toHex0x(message.finalState.commitment),
                 executionId: record.admission.execution_id,
@@ -433,33 +683,61 @@ export async function playSeat(args) {
         }
         let view = null;
         let cursor = null;
-        if (message.type === "sessionJoined") {
+        if (message.type === "sessionJoined" ||
+            message.type === "participantView" ||
+            message.type === "actionCommitted" ||
+            message.type === "actionRejected" ||
+            message.type === "sessionResumed") {
             view = message.view;
             cursor = message.cursor;
         }
-        else if (message.type === "participantView") {
-            view = message.view;
-            cursor = message.cursor;
-        }
-        else if (message.type === "actionCommitted") {
-            pending = null;
-            committedActions += 1;
-            view = message.view;
-            cursor = message.cursor;
-        }
-        else if (message.type === "actionRejected") {
-            pending = null;
-            view = message.view;
-            cursor = message.cursor;
-        }
-        else if (message.type === "sessionResumed") {
-            view = message.view;
-            cursor = message.cursor;
-        }
-        if (view && cursor !== null && lastContext) {
-            const nonceKey = view.state.nonce.toString();
+        if (cursor !== null && lastContext) {
+            /* Accepted before anything else happens: a refusal here leaves the
+               retained boundary untouched and nothing acknowledged. */
+            const admitted = admitAuthorityEvent(accepted, message);
+            /* A re-delivery is the suffix a resume repeats. It was applied and
+               acknowledged once, so nothing here moves for it: no view, no pending
+               resolution, no commit count, no table read, no decision, no
+               acknowledgement. */
+            if (admitted.disposition !== "applied")
+                return null;
+            accepted = admitted.boundary;
+            /* Resolved only for the applied event, so a replayed commit cannot
+               count twice or drop a proposal that is still in flight. */
+            if (message.type === "actionCommitted") {
+                pending = null;
+                committedActions += 1;
+            }
+            else if (message.type === "actionRejected")
+                pending = null;
+            if (view &&
+                view.legalActions.length === 0 &&
+                !elimination.eliminated &&
+                Date.now() - lastIdleTableReadMs >= IDLE_TABLE_READ_MS) {
+                /* Nothing to decide: somebody else's turn, a hand this seat folded, or
+                   a sitting this seat is out of. Read now and then, so the hand lines go
+                   on and a seat that has lost its last chip says so once. */
+                lastIdleTableReadMs = Date.now();
+                const idle = await readPublicTable(fetchImpl, product, executionHex, names, tableCapability);
+                if (idle && idle.handNumber !== lastHandSeen) {
+                    lastHandSeen = idle.handNumber;
+                    args.onHand?.({
+                        number: idle.handNumber,
+                        stack: idle.seats.find((entry) => entry.seat === args.seat)?.stack ??
+                            null,
+                    });
+                }
+                if (elimination.observe(idle))
+                    args.onEliminated?.();
+            }
+            const nonceKey = view?.state.nonce.toString() ?? "";
             const now = BigInt(Date.now());
-            if (view.legalActions.length > 0 &&
+            if (
+            /* A viewless admission is acknowledged and waited on: a held seat has
+               nothing to answer, and nothing to infer on, until its gate releases
+               and the real view arrives. */
+            view !== null &&
+                view.legalActions.length > 0 &&
                 !acted.has(nonceKey) &&
                 view.participantDeadlineMs > now) {
                 const legal = decodeLegalActions(view.legalActions);
@@ -467,7 +745,7 @@ export async function playSeat(args) {
                    played a seat wrote this poll itself; the SDK owns the transport, so
                    it owns this read too. Per turn, not per event: the table only
                    matters at the moment there is a decision to make. */
-                const table = await readPublicTable(fetchImpl, product, executionHex, names);
+                const table = await readPublicTable(fetchImpl, product, executionHex, names, tableCapability);
                 /* And what has been said in this hand, which the skill promised the
                    decision would see. Best-effort like the table: a seat that cannot
                    read the talk still has its own cards and the legal set. */
@@ -579,13 +857,15 @@ export async function playSeat(args) {
                     }
                 }
             }
-            await client.acknowledge(lastContext, cursor);
+            await client.acknowledge(lastContext, cursor, originToken);
             lastCursor = cursor;
             if (!disconnectExerciseDone &&
                 args.disconnectAfterActions !== undefined &&
                 committedActions >= args.disconnectAfterActions) {
                 disconnectExerciseDone = true;
                 await client.resume(lastContext, lastCursor);
+                originToken = client.token ?? originToken;
+                inbox.length = 0;
                 reconnects += 1;
             }
         }
@@ -613,14 +893,27 @@ export async function playSeat(args) {
                         rejoins,
                         said,
                         saidRefused,
+                        eliminated: elimination.eliminated,
                         executionId: record.admission.execution_id,
                         sessionBaseUrl: record.admission.session_base_url,
                     };
                 await client.resume(lastContext, lastCursor);
+                originToken = client.token ?? originToken;
                 reconnects += 1;
             }
         }
         catch (error) {
+            /* A version this build cannot speak is never answered by resuming or
+               rejoining: the same refusal would come back, and a rejoin could even
+               look successful while the seat cannot read the gated stream. */
+            if (error instanceof UnsupportedSessionVersionError)
+                throw error;
+            /* Nor is a refused projection: the event the authority sent is one this
+               contract forbids, and resuming would fetch the same bytes again while
+               the loop reported it as flaky transport. */
+            if (error instanceof SessionBoundaryError ||
+                error instanceof PredictionGateConflictError)
+                throw error;
             if (!lastContext || reconnects >= 5)
                 throw error;
             /* Three refusals, three answers. A gone session (`UnknownSession`, or a
@@ -639,20 +932,32 @@ export async function playSeat(args) {
                     rejoins,
                     said,
                     saidRefused,
+                    eliminated: elimination.eliminated,
                     executionId: record.admission.execution_id,
                     sessionBaseUrl: record.admission.session_base_url,
                 };
+            /* Whatever the old binding delivered and this loop had not handled yet
+               is delivered again from the cursor by the new one. */
+            inbox.length = 0;
             if (answer === "rejoin") {
                 joined = await client.join();
+                originToken = client.token ?? originToken;
                 if (joined.context)
                     lastContext = joined.context;
                 lastCursor = { sequence: 0n, witnessedReceipt: null };
+                /* A rejoin is a new session: nothing the old one retained - its phase,
+                   its floor, its sequence - describes this one, and only a boundary
+                   this loop opened itself may be reset. The stale inbox belongs to
+                   the session that is gone. */
+                accepted = freshSessionBoundary();
+                inbox.length = 0;
                 inbox.push(...joined.messages);
                 rejoins += 1;
                 reconnects += 1;
                 continue;
             }
             await client.resume(lastContext, lastCursor);
+            originToken = client.token ?? originToken;
             reconnects += 1;
         }
     }
@@ -684,17 +989,96 @@ export function normaliseCardCode(code) {
     const suit = trimmed.slice(-1).toLowerCase();
     return `${rank}${suit}`;
 }
-/** The public table for one execution, as the spectator snapshot shows it.
+/** What the terminal disclosure says one seat takes off the table, read off
+ *  the spectator snapshot's status.
+ *
+ *  Read rather than assumed: consent checks the seat's chips against it before
+ *  it signs, and a number a client invented would be refused there. The
+ *  disclosure is published a moment after the seat sees the terminal, so this
+ *  waits for it, bounded well inside the consent window.
+ *
+ *  Signed as the seat where a capability is given. A private room's snapshot
+ *  answers only its seats and owning wallets, so an anonymous read of it never
+ *  finds an entitlement at all, and a room whose seats read that way never
+ *  settles. A playground or tournament sitting ignores the capability. */
+export async function readDisclosedEntitlement(fetchImpl, product, executionId, seat, capability, options = {}) {
+    const attempts = options.attempts ?? 15;
+    const pauseMs = options.pauseMs ?? 1_000;
+    const target = `/open/v1/spectator/executions/${executionId}`;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        try {
+            const header = capability ? await capability("GET", target) : null;
+            const response = await fetchImpl(`${product.replace(/\/$/, "")}${target}`, header === null
+                ? undefined
+                : { headers: { [AGENT_HTTP_CAPABILITY_HEADER]: header } });
+            if (response.ok) {
+                const body = (await response.json());
+                const chips = body.status?.entitlements?.find((entitlement) => entitlement.seat === seat)?.chips;
+                if (chips !== undefined)
+                    return BigInt(chips);
+            }
+        }
+        catch {
+            /* A read that did not answer is another attempt, not an end. */
+        }
+        await new Promise((resolve) => setTimeout(resolve, pauseMs));
+    }
+    return undefined;
+}
+/** Read a sitting's status off the public history surface.
  *
- *  Best-effort: a read that does not answer is null, never a throw -- the
- *  seat's own view is what the turn depends on, and a decision is better made
- *  without the board than not made at all.
+ *  Its own read rather than part of `readPublicTable`, because that answers
+ *  what is on the table right now and returns nothing at all once the table is
+ *  gone -- which is precisely the moment this question is being asked. */
+export async function readSittingStatus(fetchImpl, product, executionHex) {
+    try {
+        const response = await fetchImpl(`${product}/open/v1/history/matches/${executionHex}`);
+        if (!response.ok)
+            return { state: "unknown" };
+        const wire = (await response.json());
+        switch (wire.status) {
+            case "completed":
+            case "settling":
+            case "failed":
+                return { state: "over", detail: wire.status };
+            case "live":
+                return { state: "live" };
+            /* `unavailable` is the product saying it does not know, and a status
+               this build has never heard of is the same thing. Neither is a reason
+               to tell a seat its sitting ended. */
+            default:
+                return { state: "unknown" };
+        }
+    }
+    catch {
+        return { state: "unknown" };
+    }
+}
+/** The capability `readPublicTable` asks for, minted on this agent's own key.
  *
- *  `names` is filled as agents are met and read from after that, so who is
- *  in a seat costs one custody read per agent per sitting. */
-export async function readPublicTable(fetchImpl, product, executionHex, names = new Map()) {
+ *  A private room's live view is owner-session-only unless the reader holds a
+ *  seat at that room, and the seat says so with the same signature every other
+ *  Product API call carries. A playground sitting ignores one, so a seat can
+ *  send it without having to know which kind of table it sat down at. */
+export function agentReadCapability(agent, agentId) {
+    return async (method, requestTarget) => {
+        const { header } = await mintAgentHttpCapability(agent, agentId, {
+            method,
+            requestTarget,
+            body: new Uint8Array(),
+        });
+        return header;
+    };
+}
+export async function readPublicTable(fetchImpl, product, executionHex, names = new Map(), capability) {
+    /* Bound to the target the server reconstructs from the request, which is the
+       origin-form path and not the absolute URL the fetch is given. */
+    const target = `/open/v1/spectator/executions/${executionHex}`;
     try {
-        const response = await fetchImpl(`${product}/open/v1/spectator/executions/${executionHex}`);
+        const header = capability ? await capability("GET", target) : null;
+        const response = await fetchImpl(`${product}${target}`, header === null
+            ? undefined
+            : { headers: { [AGENT_HTTP_CAPABILITY_HEADER]: header } });
         if (!response.ok)
             return null;
         const wire = (await response.json());