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

package/dist/cli.js

@@ -12,16 +12,21 @@ import { randomBytes } from "node:crypto";
 import { dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { fromHex, toHex } from "./bytes.js";
+import { DEFAULT_SEAT_STATE_FILE, loadSeatState, saveSeatState, } from "./seatState.js";
+import { newSeatState, openTurn, seatAgentId, submitTurn, } from "./seatTurn.js";
 import { nameAgent } from "./identity.js";
 import { AGENT_HTTP_CAPABILITY_HEADER, mintAgentHttpCapability, } from "./agentHttp.js";
 import { DEFAULT_KEY_FILE, generateKeypair, loadKeypair, saveKeypair, signOwnerAuthenticator, signRaw, } from "./keypair.js";
 import { deriveAgentId, registerCanonicalPayload, revokeCanonicalPayload, rotateCanonicalPayload, } from "./registration.js";
-import { playReportLines, playSeat } from "./session.js";
-import { claimInviteLink, encodeClaimInvite, mintClaimInvite, } from "./claim.js";
+import { agentReadCapability, playReportLines, playSeat, readDisclosedEntitlement, } from "./session.js";
+import { claimInviteLink, encodeClaimInvite, encodeClaimInviteCompact, mintClaimInvite, } from "./claim.js";
 import { acceptAndAwaitAdmission } from "./offer.js";
 import { playTour, queueUntilSeated } from "./tour.js";
+import { joinRoomWhenComposed, MIN_ROOM_SEATS, openRoom, roomInvitePrompt, } from "./room.js";
+import { disputeHolding, JoinRefused, joinTransaction, leaveTransaction, listTournaments, matchmakingOverLine, planJoin, presentToTournament, readAgentEntry, playsHeldBy, giveBackTransaction, readTournament, sponsorAndExecute, tournamentIdArg, } from "./openTournament.js";
 import { authorityOriginFromSessionBase, buildConsentRequest, digestForPrompt, settlementConsentPath, verifyConsentDisclosure, } from "./settlement.js";
-import { actionSigningBytes, joinSigningBytes, resumeSigningBytes, } from "./sessionWire.js";
+import { actionSigningBytes, joinSigningBytes, requireSessionVersion, resumeSigningBytes, SESSION_VERSION, } from "./sessionWire.js";
+import { describeNext, refusalMessageFromText } from "./refusal.js";
 function fail(message) {
     console.error(`dopa-open: ${message}`);
     process.exit(1);
@@ -50,9 +55,11 @@ function identity(agent) {
     };
 }
 function readContext(raw) {
+    const sessionVersion = num(raw.session_version, "session_version");
+    requireSessionVersion(sessionVersion);
     return {
         wireVersion: num(raw.wire_version, "wire_version"),
-        sessionVersion: num(raw.session_version, "session_version"),
+        sessionVersion,
         sessionId: hex(raw.session_id, "session_id"),
         executionId: hex(raw.execution_id, "execution_id"),
         executionManifestDigest: hex(raw.execution_manifest_digest, "execution_manifest_digest"),
@@ -91,10 +98,11 @@ async function commandRegister(args) {
         options: {
             key: { type: "string", default: DEFAULT_KEY_FILE },
             "product-url": { type: "string" },
-            // versions accepted as comma-separated lists; every deployment today
-            // speaks version 1 on all three axes
+            // Versions accepted as comma-separated lists. The three axes are
+            // independent: the Product API and the DOPA-OPEN protocol are at 1,
+            // while the participant session axis is the overlay-bearing contract.
             "product-api-versions": { type: "string", default: "1" },
-            "session-versions": { type: "string", default: "1" },
+            "session-versions": { type: "string", default: `${SESSION_VERSION}` },
             "protocol-versions": { type: "string", default: "1" },
             "expires-at-ms": { type: "string" },
             /* What the agent is called at a table. Optional, and set right after
@@ -355,7 +363,7 @@ async function commandKey(args) {
     });
     const body = await response.text();
     if (!response.ok)
-        fail(`${retire ? "retirement" : "rotation"} refused (${response.status}): ${body}`);
+        fail(refusalMessageFromText(retire ? "retirement" : "rotation", response.status, body));
     console.log(body);
 }
 async function commandSign(args) {
@@ -378,7 +386,10 @@ async function commandSign(args) {
     if (kind === "join") {
         preimage = joinSigningBytes({
             wireVersion: num(raw.wire_version, "wire_version"),
-            supportedSessionVersions: raw.supported_session_versions ?? [1],
+            // A supplied list is signed exactly as given, old values included: a raw
+            // advertisement is the server's refusal to answer, not a version this
+            // client executes.
+            supportedSessionVersions: raw.supported_session_versions ?? [SESSION_VERSION],
             executionId: hex(raw.execution_id, "execution_id"),
             executionManifestDigest: hex(raw.execution_manifest_digest, "execution_manifest_digest"),
             participantId: hex(raw.participant_id, "participant_id"),
@@ -431,6 +442,20 @@ async function commandSign(args) {
  * that is the whole point, and `session.md` is explicit that a hand-rolled
  * signer drifts by a byte and is refused without a useful reason. */
 async function loadDecision(modulePath) {
+    /* `--decide baseline` used to be accepted here and is not any more.
+       Shipping a good default as one flag made not thinking the path of least
+       resistance, and most seats would have stopped there -- which is the
+       opposite of what this arena is for. The policy is still exported as
+       `baselineMove`, so an agent can run it, read it and override the spots it
+       disagrees with. Using it now costs understanding it, which is the point.
+  
+       The house plays it, so it is also the floor: a seat that reproduces it
+       exactly ties at zero edge, and beating it needs what it has not got. */
+    if (modulePath === "baseline")
+        fail("--decide baseline is gone. The house plays that policy now, so it is what you are\n" +
+            "measured against rather than what you submit. Import `baselineMove` from the SDK\n" +
+            "if you want it as a starting point, and beat it with what it does not do:\n" +
+            "it never bluffs the same way twice, never reads an opponent, and folds on a fixed line.");
     const resolved = pathToFileURL(resolve(modulePath)).href;
     let loaded;
     try {
@@ -475,8 +500,9 @@ async function commandPlay(args) {
             productUrl: productUrl,
             agent: loadKeypair(values.key),
             agentId: hex(values["agent-id"], "agent-id"),
-        }, values.table);
+        }, values.table, undefined, { onEliminated: () => console.log("eliminated staying_to_terminal") });
         console.log(`outcome ${report.outcome}`);
+        console.log(`eliminated ${report.eliminated}`);
         console.log(`committed_actions ${report.committedActions}`);
         console.log(`hands ${report.hands}`);
         return;
@@ -519,6 +545,7 @@ async function commandPlay(args) {
         strategy,
         decide,
         // Counted from one, as the watch page counts them.
+        onEliminated: () => console.log("eliminated staying_to_terminal"),
         onHand: (hand) => console.log(`hand ${hand.number + 1}${hand.stack !== null ? ` stack ${hand.stack}` : ""}`),
         disconnectAfterActions: values["disconnect-after-actions"] === undefined
             ? undefined
@@ -528,6 +555,19 @@ async function commandPlay(args) {
         console.log(line);
     console.log(`execution_id ${report.executionId}`);
     console.log(`session_base_url ${report.sessionBaseUrl}`);
+    /* This door used to stop here and leave the seat to compose `consent`
+       against a bounded window it was never told about. Three agents in the
+       2026-09-05 retest found the window only by probing for it, one of them with
+       91 seconds to spare — and the one that busted early had the least reason of
+       all to still be watching, while holding everybody else's payout. */
+    await handInSeatConsent({
+        productUrl: productUrl,
+        agent,
+        agentId: hex(values["agent-id"], "agent-id"),
+        offerId: values.offer,
+        seat: Number.parseInt(values.seat, 10),
+        report,
+    });
 }
 /* ── What a run leaves behind ─────────────────────────────────────────────
  *
@@ -610,9 +650,10 @@ async function signedGet(productUrl, target, agent, agentIdHex) {
  *
  *  An agent id is the owner's address hashed with a nonce drawn at
  *  registration, so a key does not determine it -- but the roster is public
- *  and filtered by owner, so the key's own address finds it. One agent: the
- *  answer. Several: ask, because guessing which of somebody's agents they
- *  meant is worse than saying there are three. */
+ *  and filtered by the wallet that claimed each agent, so a claimed agent's
+ *  address finds it. One agent: the answer. Several: ask, because guessing
+ *  which of somebody's agents they meant is worse than saying there are three.
+ *  An agent nobody has claimed is not on it, which the refusal says. */
 async function resolveAgentId(productUrl, ownerAddressHex, given) {
     if (given)
         return given;
@@ -622,7 +663,8 @@ async function resolveAgentId(productUrl, ownerAddressHex, given) {
     const body = (await response.json());
     const agents = body.agents ?? [];
     if (agents.length === 0)
-        fail(`no agent on this arena is registered to ${ownerAddressHex}; register first, or pass --agent-id`);
+        fail(`no agent on this arena is claimed by ${ownerAddressHex}. The roster lists an agent under the wallet that ` +
+            "claimed it, so one that registered itself is not here until it is claimed; pass --agent-id (register printed it)");
     if (agents.length > 1)
         fail(`this key owns ${agents.length} agents; pass --agent-id to say which:\n  ${agents
             .map((agent) => agent.agentId)
@@ -647,7 +689,7 @@ async function commandMe(args) {
     const response = await signedGet(productUrl, "/open/v1/agent/me", agent, agentId);
     const body = await response.text();
     if (!response.ok)
-        fail(`agent/me refused (${response.status}) at ${productUrl}/open/v1/agent/me: ${body}`);
+        fail(refusalMessageFromText(`agent/me at ${productUrl}/open/v1/agent/me`, response.status, body));
     try {
         console.log(JSON.stringify(JSON.parse(body), null, 2));
     }
@@ -655,39 +697,162 @@ async function commandMe(args) {
         console.log(body);
     }
 }
-async function commandConsent(args) {
+/* Two commands with the agent between them, instead of a loop with a function
+   inside it. `turn` says what the seat sees and stops; `act` sends one move and
+   stops. Nothing is running in between, which is the point: the thing deciding
+   is whoever is reading, not a module handed over in advance. */
+/* Chip amounts and deadlines are bigints, which `JSON.stringify` refuses
+   outright rather than rounding. A reader wants the number, so they go out as
+   strings: a wager is exact and a float is not. */
+function printableTurn(value) {
+    return JSON.stringify(value, (_key, entry) => (typeof entry === "bigint" ? entry.toString() : entry), 2);
+}
+/** The seat's agent id for `turn` and `act`, or a refusal that says why not.
+ *
+ *  Never the roster by owner: that lists an agent under the wallet that claimed
+ *  it, so an agent that registered itself was told it had registered nothing. */
+async function seatAgentIdOrExplain(state, agent, given) {
+    let agentId;
+    try {
+        agentId = await seatAgentId(state, agent, given);
+    }
+    catch (error) {
+        fail(`--agent-id was not given and seat ${state.seat} of offer ${state.offerId} could not be read to find it: ` +
+            `${error instanceof Error ? error.message : String(error)}. Pass --agent-id (register printed it).`);
+    }
+    if (!agentId)
+        fail(`seat ${state.seat} of offer ${state.offerId} is not held by this key (0x${toHex(agent.publicKey)}); ` +
+            "check --key and --seat, or pass --agent-id");
+    return agentId;
+}
+async function commandTurn(args) {
     const { values } = parseArgs({
         args,
         options: {
             key: { type: "string", default: DEFAULT_KEY_FILE },
+            state: { type: "string", default: DEFAULT_SEAT_STATE_FILE },
             "product-url": { type: "string" },
-            offer: { type: "string" },
+            "offer-id": { type: "string" },
+            "agent-id": { type: "string" },
             seat: { type: "string" },
-            "terminal-nonce": { type: "string" },
-            "terminal-commitment": { type: "string" },
-            entitlement: { type: "string" },
-            /* Accepted and unused: the consent is signed by the key, and the offer
-               names the agent. Every other command takes it, and the one that
-               refused it read as a bug to the agents that met it. */
+            wait: { type: "string" },
+            help: { type: "boolean", short: "h" },
+        },
+        allowPositionals: false,
+    });
+    if (values.help)
+        return void console.log(USAGE);
+    const agent = loadKeypair(values.key);
+    const statePath = values.state;
+    let state = loadSeatState(statePath);
+    if (!state) {
+        const productUrl = values["product-url"];
+        const offerId = values["offer-id"];
+        const seat = values.seat === undefined ? undefined : Number(values.seat);
+        if (!productUrl || !offerId || seat === undefined)
+            fail(`no seat is open at ${statePath}. Start one with --product-url --offer-id --seat, ` +
+                "which are what the admit answered with.");
+        state = newSeatState(productUrl, offerId, seat);
+    }
+    const agentId = await seatAgentIdOrExplain(state, agent, values["agent-id"]);
+    const outcome = await openTurn({
+        state: { ...state, agentId },
+        agent,
+        agentId: fromHex(agentId),
+        waitMs: values.wait === undefined ? 0 : Number(values.wait) * 1000,
+    });
+    saveSeatState(statePath, outcome.state);
+    if (outcome.kind === "your-turn") {
+        console.log(printableTurn({ turn: "yours", ...outcome.position }));
+        return;
+    }
+    if (outcome.kind === "unattachable") {
+        /* Printed rather than thrown, and with the sitting's state beside the
+           reason: an agent meeting this has to choose between waiting and giving
+           up, and "the table is still running" is what decides that. */
+        console.log(printableTurn({
+            turn: "unattachable",
+            sitting: outcome.sitting,
+            reason: outcome.reason,
+        }));
+        return;
+    }
+    if (outcome.kind === "terminal") {
+        /* The two values `consent` takes, printed where the seat can read them.
+           Without these the two-command loop reached the terminal and had no way to
+           settle: `consent` requires both, and this was the only place they were
+           ever seen. */
+        console.log(printableTurn(outcome.terminalNonce === undefined
+            ? { turn: "terminal", consent: "unavailable_reattached_after_the_end" }
+            : {
+                turn: "terminal",
+                terminal_nonce: outcome.terminalNonce,
+                terminal_commitment: outcome.terminalCommitment,
+            }));
+        return;
+    }
+    console.log(printableTurn({ turn: outcome.kind }));
+}
+async function commandAct(args) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            key: { type: "string", default: DEFAULT_KEY_FILE },
+            state: { type: "string", default: DEFAULT_SEAT_STATE_FILE },
             "agent-id": { type: "string" },
+            fold: { type: "boolean" },
+            check: { type: "boolean" },
+            call: { type: "boolean" },
+            "wager-to": { type: "string" },
+            say: { type: "string" },
+            help: { type: "boolean", short: "h" },
         },
+        allowPositionals: false,
     });
-    const productUrl = values["product-url"];
-    if (!productUrl)
-        fail("--product-url is required");
-    if (!values.offer)
-        fail("--offer is required");
-    if (!values.seat)
-        fail("--seat is required");
-    if (!values["terminal-nonce"])
-        fail("--terminal-nonce is required");
-    if (!values["terminal-commitment"])
-        fail("--terminal-commitment is required");
-    if (!values.entitlement)
-        fail("--entitlement is required");
+    if (values.help)
+        return void console.log(USAGE);
+    const chosen = [
+        values.fold ? { type: "fold" } : null,
+        values.check ? { type: "check" } : null,
+        values.call ? { type: "call" } : null,
+        values["wager-to"] !== undefined
+            ? { type: "wagerTo", amount: BigInt(values["wager-to"]) }
+            : null,
+    ].filter((action) => action !== null);
+    if (chosen.length !== 1)
+        fail("pass exactly one of --fold --check --call --wager-to <amount>");
+    /* A line is required, not decorative. Table talk is the one surface where a
+       seat shows what it was thinking, and a seat that never says anything is
+       indistinguishable from a script -- which, if it never says anything, it
+       may as well be. */
+    const say = values.say?.trim();
+    if (!say)
+        fail("--say is required: one line saying why, which rides the move onto the table.\n" +
+            'A read, the board, the price -- "board is dry, this should fold out weak pairs".');
     const agent = loadKeypair(values.key);
-    const seat = Number.parseInt(values.seat, 10);
-    const offerResponse = await fetch(`${productUrl.replace(/\/$/, "")}/open/v1/playground/matches/${values.offer}`);
+    const statePath = values.state;
+    const state = loadSeatState(statePath);
+    if (!state)
+        fail(`no seat is open at ${statePath}; run \`turn\` first`);
+    const agentId = await seatAgentIdOrExplain(state, agent, values["agent-id"]);
+    const result = await submitTurn({
+        state: { ...state, agentId },
+        agent,
+        agentId: fromHex(agentId),
+        action: chosen[0],
+        say: say,
+    });
+    saveSeatState(statePath, result.state);
+    console.log(JSON.stringify({ committed: result.committed, said: result.said }));
+}
+/** One seat's consent to a terminal, signed by its own key and submitted
+ *  until the authority accepts it or refuses outright.
+ *
+ *  The chips of a tournament table do not move until every seat has done
+ *  this, so it is worth a caller of its own rather than a flag on the play
+ *  loop. Prints what the authority recorded. */
+async function consentToTerminal(options) {
+    const offerResponse = await fetch(`${options.productUrl.replace(/\/$/, "")}/open/v1/playground/matches/${options.offerId}`);
     const offerBody = await offerResponse.text();
     if (!offerResponse.ok)
         fail(`offer read failed (${offerResponse.status}): ${offerBody}`);
@@ -699,19 +864,24 @@ async function commandConsent(args) {
     const promptResponse = await fetch(`${origin}${path}`);
     const promptText = await promptResponse.text();
     if (!promptResponse.ok)
-        fail(`consent prompt refused (${promptResponse.status}) at ${origin}${path}: ${promptText}`);
+        fail(refusalMessageFromText(`consent prompt at ${origin}${path}`, promptResponse.status, promptText));
     const prompt = JSON.parse(promptText);
+    /* Said before the signing work rather than after it: this is the number an
+       agent needs while it can still act on it, and the one every seat in the
+       retest had to go looking for. */
+    if (prompt.consent_deadline_ms !== undefined)
+        console.log(`consent_deadline_ms ${prompt.consent_deadline_ms}`);
     const disclosure = {
         prompt,
-        seat,
+        seat: options.seat,
         executionId: hex(record.admission.execution_id, "execution_id"),
-        finalNonce: BigInt(values["terminal-nonce"]),
-        finalCommitment: hex(values["terminal-commitment"], "terminal-commitment"),
-        entitlement: BigInt(values.entitlement),
+        finalNonce: BigInt(options.terminalNonce),
+        finalCommitment: hex(options.terminalCommitment, "terminal-commitment"),
+        entitlement: options.entitlement,
     };
     verifyConsentDisclosure(disclosure);
     const digest = digestForPrompt(prompt);
-    const signature = await signRaw(agent, digest);
+    const signature = await signRaw(options.agent, digest);
     const request = buildConsentRequest({
         ...disclosure,
         signature,
@@ -743,8 +913,17 @@ async function commandConsent(args) {
             // not JSON; the raw body is all there is to show
         }
         const said = refusal.detail ?? submitBody;
+        /* Another seat declined, so cooperative settlement is closed for everyone
+           and no consent of this seat's can reopen it. Said as an outcome rather
+           than as this seat's mistake: the table still settles, by the dispute
+           window rather than by quorum, and the entitlement is unchanged. */
+        if (refusal.code === "settlement_declined") {
+            console.log("state SettlementDeclined");
+            console.log("progress a seat declined this settlement, so it settles through the dispute window rather than by consent");
+            return;
+        }
         if (!refusal.retryable || attempt >= ATTEMPTS) {
-            fail(`consent submit refused (${submit.status}${refusal.code ? ` ${refusal.code}` : ""}) at ${origin}${path}: ${said}`);
+            fail(refusalMessageFromText(`consent submit at ${origin}${path}`, submit.status, submitBody));
         }
         console.error(`consent submit answered ${submit.status} (${refusal.code ?? "retryable"}), ` +
             `attempt ${attempt} of ${ATTEMPTS}: ${said}`);
@@ -764,6 +943,88 @@ async function commandConsent(args) {
     if (recorded.consent_window_remaining_ms !== undefined)
         console.log(`consent_window_remaining_ms ${recorded.consent_window_remaining_ms}`);
 }
+/** Hand in this seat's consent for the terminal a play loop just reached.
+ *
+ *  The chips do not move until every admitted seat has consented, a seat
+ *  entitled to zero included, and the window is bounded — so a play door that
+ *  printed the command instead of running it would be asking an agent that has
+ *  just finished a sitting to compose four flags against a clock. Both doors
+ *  that play a seat to its terminal hand it in here.
+ *
+ *  It is the busted seat this matters most for: it has nothing to collect, it
+ *  has been idle for the rest of the sitting, and nothing about "I was
+ *  eliminated" suggests there is one action left. Skipping it strands the whole
+ *  table's payout, the winner's with it. */
+async function handInSeatConsent(options) {
+    const { productUrl, agent, agentId, offerId, seat, report } = options;
+    if (report.terminalNonce === undefined) {
+        console.error("this sitting reached no terminal, so there is nothing to consent to; the table settles by timeout or referee");
+        return;
+    }
+    const entitlement = await readDisclosedEntitlement(fetch, productUrl, report.executionId, seat, agentReadCapability(agent, agentId));
+    if (entitlement === undefined) {
+        /* Said and returned, rather than exited on. A deployment that settles
+           nothing discloses no entitlement, and that is its shape rather than this
+           seat's mistake — the sitting was played and the report is worth having.
+           The command is printed whole so a seat that does owe one can still send
+           it once the disclosure lands. */
+        console.error(`the disclosure names no entitlement for seat ${seat}; if this deployment settles, consent with ` +
+            `"dopa-open consent --product-url ${productUrl} --offer ${offerId} --seat ${seat} ` +
+            `--terminal-nonce ${report.terminalNonce} --terminal-commitment ${report.terminalCommitment} ` +
+            `--entitlement <chips>" once it does`);
+        return;
+    }
+    console.log(`entitlement ${entitlement}`);
+    await consentToTerminal({
+        productUrl,
+        agent,
+        offerId,
+        seat,
+        terminalNonce: report.terminalNonce,
+        terminalCommitment: report.terminalCommitment,
+        entitlement,
+    });
+}
+async function commandConsent(args) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            key: { type: "string", default: DEFAULT_KEY_FILE },
+            "product-url": { type: "string" },
+            offer: { type: "string" },
+            seat: { type: "string" },
+            "terminal-nonce": { type: "string" },
+            "terminal-commitment": { type: "string" },
+            entitlement: { type: "string" },
+            /* Accepted and unused: the consent is signed by the key, and the offer
+               names the agent. Every other command takes it, and the one that
+               refused it read as a bug to the agents that met it. */
+            "agent-id": { type: "string" },
+        },
+    });
+    const productUrl = values["product-url"];
+    if (!productUrl)
+        fail("--product-url is required");
+    if (!values.offer)
+        fail("--offer is required");
+    if (!values.seat)
+        fail("--seat is required");
+    if (!values["terminal-nonce"])
+        fail("--terminal-nonce is required");
+    if (!values["terminal-commitment"])
+        fail("--terminal-commitment is required");
+    if (!values.entitlement)
+        fail("--entitlement is required");
+    await consentToTerminal({
+        productUrl: productUrl,
+        agent: loadKeypair(values.key),
+        offerId: values.offer,
+        seat: Number.parseInt(values.seat, 10),
+        terminalNonce: values["terminal-nonce"],
+        terminalCommitment: values["terminal-commitment"],
+        entitlement: BigInt(values.entitlement),
+    });
+}
 async function commandQueue(args) {
     const { values } = parseArgs({
         args,
@@ -775,6 +1036,7 @@ async function commandQueue(args) {
             decide: { type: "string" },
             "timeout-ms": { type: "string" },
             "poll-ms": { type: "string" },
+            "min-agents": { type: "string" },
             play: { type: "boolean", default: false },
         },
     });
@@ -784,8 +1046,24 @@ async function commandQueue(args) {
     if (!values["agent-id"])
         fail("--agent-id is required");
     const tour = values.tour;
-    if (tour !== "playground" && tour !== "tournament")
-        fail("--tour must be playground or tournament");
+    /* `tournament` used to be accepted here and posted to the legacy fixture
+       tour, whose waiting body carries only a reason -- so the seat printed
+       undefined counts for five minutes and then threw, and every entrant was
+       refunded. The open-entry tournament is its own command. */
+    if (tour === "tournament")
+        fail("--tour tournament is not the open-entry tournament; use \"dopa-open tournament join\" instead\n" +
+            describeNext({ action: "use", command: "dopa-open tournament join" }));
+    if (tour !== "playground")
+        fail("--tour must be playground");
+    /* Refused here rather than by the server: a floor the table cannot hold
+       would otherwise surface as a 400 after the agent has already decided to
+       wait, and a tournament has no fill to decline. */
+    let minAgents;
+    if (values["min-agents"] !== undefined) {
+        minAgents = Number(values["min-agents"]);
+        if (!Number.isInteger(minAgents) || minAgents < 1 || minAgents > 3)
+            fail("--min-agents counts real agents at a three-seat table, you included: 1 to 3");
+    }
     const client = {
         productUrl: productUrl,
         agent: loadKeypair(values.key),
@@ -811,6 +1089,7 @@ async function commandQueue(args) {
     console.log(`agent_page ${client.productUrl.replace(/\/$/, "")}/arena/agents/0x${values["agent-id"].replace(/^0x/i, "")}`);
     let lastWaitingLine = "";
     const seated = await queueUntilSeated(client, tour, {
+        minAgents,
         timeoutMs: values["timeout-ms"] === undefined
             ? undefined
             : Number.parseInt(values["timeout-ms"], 10),
@@ -825,11 +1104,23 @@ async function commandQueue(args) {
                 `fill_at_ms ${entry.fillAtMs}` +
                 (entry.houseSeatsAtFill !== undefined
                     ? ` house_seats_at_fill ${entry.houseSeatsAtFill}`
-                    : "");
+                    : "") +
+                (entry.minAgents !== undefined ? ` min_agents ${entry.minAgents}` : "") +
+                (entry.atFill !== undefined ? ` at_fill ${entry.atFill}` : "");
             if (line !== lastWaitingLine)
                 console.log(line);
             lastWaitingLine = line;
         },
+        /* Said once a restart, not once a poll: a queue that keeps re-entering
+           while the product comes back looks hung otherwise. */
+        onUnavailable: (error) => {
+            const line = `product_unavailable ${error instanceof Error ? error.message.split("\n")[0] : String(error)}`;
+            if (line !== lastWaitingLine) {
+                console.log(line);
+                console.log(describeNext({ action: "retry", after_ms: 3000 }));
+            }
+            lastWaitingLine = line;
+        },
     });
     if (seated.state === "offered") {
         console.log(`offer ${seated.offerId}`);
@@ -863,6 +1154,7 @@ async function commandQueue(args) {
             coordinatorKey: admitted.coordinatorKey,
             timeAuthorityKey: admitted.timeAuthorityKey,
             // Counted from one, as the watch page counts them.
+            onEliminated: () => console.log("eliminated staying_to_terminal"),
             onHand: (hand) => console.log(`hand ${hand.number + 1}${hand.stack !== null ? ` stack ${hand.stack}` : ""}`),
             /* Whoever the caller said is playing. Without `--decide` this stays the
                filler picker, and a seat run that way proves the transport works and
@@ -872,6 +1164,18 @@ async function commandQueue(args) {
         });
         for (const line of playReportLines(report))
             console.log(line);
+        /* The same hand-in `play` does. This door used to stop at the terminal, so
+           a seat that came through the queue held everybody else's payout behind a
+           consent window it was never told about — and the tour documents said this
+           command hands it in. */
+        await handInSeatConsent({
+            productUrl: client.productUrl,
+            agent: client.agent,
+            agentId: client.agentId,
+            offerId: seated.offerId,
+            seat: admitted.seat,
+            report,
+        });
         return;
     }
     console.log(`seated table ${seated.tableId}`);
@@ -881,11 +1185,471 @@ async function commandQueue(args) {
         console.log(`execution_id ${seated.executionId}`);
     if (!values.play)
         return;
-    const report = await playTour(client, seated.tableId);
+    /* An authority sitting is played through its participant session, and the
+       table's decision route answers `409 play_through_offer` — which the tour
+       loop threw on, so re-joining while seated dead-ended instead of resuming.
+       The offer id is what resumes it, and this answer does not carry one: the
+       product publishes the table, not the offer the seat accepted. The run
+       record written when the seat first accepted does, so point at that rather
+       than driving a loop that cannot work here. */
+    if (seated.mode === "authority") {
+        console.log("already_seated this sitting plays through its participant session, not the table routes");
+        console.log(`resume it with the reconnect line this key's run record holds: "dopa-open play --product-url ${client.productUrl} --key ${values.key} --agent-id ${values["agent-id"]} --offer <the offer this seat accepted> --seat <its seat>"`);
+        return;
+    }
+    const report = await playTour(client, seated.tableId, undefined, {
+        onEliminated: () => console.log("eliminated staying_to_terminal"),
+    });
     console.log(`outcome ${report.outcome}`);
+    console.log(`eliminated ${report.eliminated}`);
     console.log(`committed_actions ${report.committedActions}`);
     console.log(`hands ${report.hands}`);
 }
+/** `dopa-open room open | join`: the private room, on this agent's own key.
+ *
+ *  `open` creates the room and prints the one line its opener hands a guest.
+ *  `join` takes the seat that room reserved: on an authority stack the join
+ *  answers an offer, and the seat is taken by accepting it with this key,
+ *  which is the same path the playground queue takes. Asking the table routes
+ *  for a decision instead answers `409 play_through_offer`, so there is no
+ *  second loop to learn. */
+async function commandRoom(args) {
+    const [verb, ...rest] = args;
+    /* Checked before the key file is opened: a verb this command does not have
+       would otherwise fail on whatever it touched first, and the reader would
+       go looking for a missing key rather than a typo. */
+    if (verb !== "open" && verb !== "join")
+        fail(`room takes open or join, not "${verb ?? ""}"`);
+    const { values } = parseArgs({
+        args: rest,
+        options: {
+            key: { type: "string", default: DEFAULT_KEY_FILE },
+            "product-url": { type: "string" },
+            "agent-id": { type: "string" },
+            "table-id": { type: "string" },
+            seats: { type: "string", default: String(MIN_ROOM_SEATS) },
+            decide: { type: "string" },
+            play: { type: "boolean", default: false },
+            "timeout-ms": { type: "string", default: String(30 * 60_000) },
+        },
+    });
+    const productUrl = values["product-url"];
+    if (!productUrl)
+        fail("--product-url is required");
+    if (!values["agent-id"])
+        fail("--agent-id is required");
+    const client = {
+        productUrl: productUrl,
+        agent: loadKeypair(values.key),
+        agentId: hex(values["agent-id"], "agent-id"),
+    };
+    /* Loaded before anything is created or joined. A bad path found after the
+       room exists would leave a guest holding an id nobody is sitting at. */
+    const decide = values.decide
+        ? await loadDecision(values.decide)
+        : undefined;
+    if (decide && !values.play)
+        fail("--decide only means something with --play, which is what plays the seat");
+    if (verb === "open") {
+        const seats = Number(values.seats);
+        const room = await openRoom(client, seats);
+        console.log(`table ${room.tableId}`);
+        console.log(`seats ${room.seatCount}`);
+        console.log(`mode ${room.mode}`);
+        console.log(`settlement ${room.settlement}`);
+        if (room.executionId)
+            console.log(`execution_id ${room.executionId}`);
+        /* The invitation, as one line to paste. Printed under its own label so an
+           operator forwards the whole thing rather than the table id alone: an id
+           without the document is how a guest ends up asking the table routes for
+           a decision. */
+        console.log(`invite ${roomInvitePrompt(client.productUrl, room.tableId)}`);
+        /* The room's own page, which exists before any hand does. Not `watch`:
+           that word is the match link on every door, and `room join` prints it
+           once the room composes, so two different links under one label was a
+           thing an agent had to be warned about. */
+        console.log(`room_page ${client.productUrl.replace(/\/$/, "")}/arena/tours/private-room/tables/${room.tableId}`);
+        return;
+    }
+    const tableId = values["table-id"];
+    if (!tableId)
+        fail("--table-id is required: the id the room's opener sent you");
+    const joined = await joinRoomWhenComposed(client, tableId, {
+        timeoutMs: Number(values["timeout-ms"]),
+        onWaiting: () => console.log(`waiting_for_guest table ${tableId} holds this agent's seat; the room composes when its guest joins`),
+    });
+    console.log(`table ${joined.tableId}`);
+    console.log(`joined ${joined.joined}`);
+    if (joined.offerId === undefined) {
+        /* A mock stack composes no offer, so there is no seat to accept and
+           nothing for `--play` to drive. Said plainly rather than by an empty
+           report, because the difference is the whole point of `mode`. */
+        console.log("offer none this_stack_composes_no_offer");
+        return;
+    }
+    console.log(`offer ${joined.offerId}`);
+    if (joined.seat !== undefined)
+        console.log(`seat ${joined.seat}`);
+    if (!values.play)
+        return;
+    const admitted = await acceptAndAwaitAdmission(client.productUrl, joined.offerId, client.agentId, client.agent, {
+        onWaiting: (accepted, total) => console.log(`accepted ${accepted} of ${total}`),
+    });
+    console.log(`execution_id ${admitted.executionId}`);
+    const runRecord = {
+        productUrl: client.productUrl,
+        agentId: values["agent-id"],
+        offerId: joined.offerId,
+        seat: admitted.seat,
+        executionId: admitted.executionId,
+    };
+    const recordPath = writeRunRecord(values.key, runRecord);
+    console.log(`watch ${client.productUrl.replace(/\/$/, "")}/arena/matches/0x${admitted.executionId.replace(/^0x/i, "")}`);
+    console.log(`run_record ${recordPath}`);
+    console.log(`reconnect ${reconnectCommand(values.key, runRecord)}`);
+    takeSeatLock(values.key, values["agent-id"]);
+    const report = await playSeat({
+        productUrl: client.productUrl,
+        offerId: joined.offerId,
+        seat: admitted.seat,
+        agentId: client.agentId,
+        agent: client.agent,
+        coordinatorKey: admitted.coordinatorKey,
+        timeAuthorityKey: admitted.timeAuthorityKey,
+        onEliminated: () => console.log("eliminated staying_to_terminal"),
+        onHand: (hand) => console.log(`hand ${hand.number + 1}${hand.stack !== null ? ` stack ${hand.stack}` : ""}`),
+        strategy: "fold-heavy",
+        decide,
+    });
+    for (const line of playReportLines(report))
+        console.log(line);
+    /* A room settles the way every other sitting does, and the seat that played
+       it is the one holding the consent. Stopping at the terminal here left a
+       room's payout waiting on a window nobody in the room was told about. */
+    await handInSeatConsent({
+        productUrl: client.productUrl,
+        agent: client.agent,
+        agentId: client.agentId,
+        offerId: joined.offerId,
+        seat: admitted.seat,
+        report,
+    });
+}
+/** The tournament a command acts on: the one named, or the one the product runs. */
+async function tournamentArg(productUrl, named) {
+    if (typeof named === "string")
+        return tournamentIdArg(named);
+    const [first] = await listTournaments(productUrl);
+    if (!first)
+        fail("this product runs no open-entry tournament");
+    return first.tournamentId;
+}
+/** `dopa-open tournament status | join | leave`: the open-entry tournament on
+ *  this agent's own key. `join` sends the agent's own `queue_join` (after a
+ *  `redeem` when it has run out) through the product's gas sponsorship, then
+ *  presents the agent to matchmaking and, with `--play`, plays each table it
+ *  is seated at. */
+async function commandTournament(args) {
+    const [verb, ...rest] = args;
+    /* Before the key file is opened and before the chain is read: a verb this
+       command does not have would otherwise fail on whatever it touched first,
+       and the reader would go looking for a missing key rather than a typo. */
+    if (verb !== "status" && verb !== "join" && verb !== "leave" && verb !== "give-back")
+        fail(`tournament takes status, join, leave or give-back, not "${verb ?? ""}"`);
+    const { values } = parseArgs({
+        args: rest,
+        options: {
+            key: { type: "string", default: DEFAULT_KEY_FILE },
+            "product-url": { type: "string" },
+            "agent-id": { type: "string" },
+            tournament: { type: "string" },
+            owner: { type: "string" },
+            decide: { type: "string" },
+            "timeout-ms": { type: "string" },
+            "poll-ms": { type: "string" },
+            play: { type: "boolean", default: false },
+            "until-out": { type: "boolean", default: false },
+        },
+    });
+    const productUrl = values["product-url"];
+    if (!productUrl)
+        fail("--product-url is required");
+    const agent = loadKeypair(values.key);
+    const tournamentId = await tournamentArg(productUrl, values.tournament);
+    const overview = await readTournament(productUrl, tournamentId);
+    const chip = agent.ownerAddressHex;
+    const entry = await readAgentEntry(productUrl, tournamentId, chip);
+    const owner = entry?.owner ?? values.owner;
+    /* The owner took the play back between the plan and the transaction: what
+       this agent holds now is on the owner's side of the book. */
+    const playTakenBackNext = () => describeNext({
+        action: "read",
+        route: `/open/v1/tournaments/${tournamentId}/owners/${owner ?? "{owner}"}`,
+    });
+    const held = async () => owner ? await playsHeldBy(productUrl, tournamentId, owner, chip) : [];
+    let plays = await held();
+    if (verb === "status") {
+        console.log(`tournament ${tournamentId}`);
+        console.log(`phase ${overview.phase}`);
+        console.log(`level ${overview.level} blinds ${overview.smallBlind}/${overview.bigBlind}`);
+        /* `start_ms` beside the other two because the `before_start` refusal names
+           no time: without it a seat refused for being early has nothing to wait
+           for. */
+        console.log(`start_ms ${overview.startMs} close_ms ${overview.closeMs} end_ms ${overview.endMs}`);
+        console.log(`chip_address ${chip}`);
+        if (!entry) {
+            console.log("state not_entered");
+        }
+        else {
+            console.log(`state ${entry.state}`);
+            console.log(`balance ${entry.balance}`);
+            if (entry.walletBalance !== undefined)
+                console.log(`wallet ${entry.walletBalance}`);
+            console.log(`run_out ${entry.runOut}`);
+            console.log(`rank ${entry.rank}`);
+        }
+        /* Without an owner nothing was looked up, which reads exactly like an
+           owner holding none. The two are opposite answers: one says "ask again
+           with --owner", the other says "this owner has run out". */
+        if (owner) {
+            console.log(`owner ${owner}`);
+            console.log(`plays_held ${plays.length}`);
+        }
+        else {
+            console.log("plays_held unknown_no_owner_given");
+        }
+        /* The one place a dispute is published. Without it a seated agent whose
+           table is held reads a book that says "seated" and nothing about the
+           twenty-four hours it is waiting on. */
+        const disputedUntilMs = await disputeHolding(productUrl, tournamentId, chip);
+        if (disputedUntilMs !== undefined)
+            console.log(`in dispute until ${new Date(disputedUntilMs).toISOString()} — the table settles after that, and the winner is still paid`);
+        for (const play of plays)
+            console.log(`play ${play.playId}`);
+        return;
+    }
+    if (!values["agent-id"])
+        fail("--agent-id is required");
+    const client = {
+        productUrl: productUrl,
+        agent,
+        agentId: hex(values["agent-id"], "agent-id"),
+        tournamentId,
+    };
+    if (verb === "give-back") {
+        const play = plays[0];
+        if (!play)
+            fail("this agent holds no play to give back; `tournament status` lists what it holds");
+        const executed = await sponsorAndExecute(client, giveBackTransaction(overview, play, chip));
+        console.log(`gave_back ${play.playId} ${executed.digest} ${executed.status}`);
+        if (executed.status !== "success")
+            fail(executed.error ?? "the give-back aborted on chain");
+        return;
+    }
+    if (verb === "leave") {
+        if (entry?.state !== "queued")
+            fail(`this agent is ${entry?.state ?? "not in the book"}; only a queued agent can leave, and a seated one plays its table out`);
+        const executed = await sponsorAndExecute(client, leaveTransaction(overview, chip));
+        console.log(`left ${executed.digest} ${executed.status}`);
+        if (executed.status !== "success")
+            fail(executed.error ?? "the leave aborted on chain");
+        return;
+    }
+    const decide = values.decide ? await loadDecision(values.decide) : undefined;
+    if (decide && !values.play)
+        fail("--decide only means something with --play");
+    if (values["until-out"] && !values.play)
+        fail("--until-out plays one table after another, so it needs --play");
+    const pollMs = values["poll-ms"] === undefined ? 3_000 : Number(values["poll-ms"]);
+    const timeoutMs = values["timeout-ms"] === undefined ? 30 * 60_000 : Number(values["timeout-ms"]);
+    /* One sitting: enter if not already queued, wait for a table, and play it.
+       `--until-out` runs this until the agent has no play left and no chips to
+       keep playing with, or matchmaking closes under it. */
+    for (let sitting = 1;; sitting += 1) {
+        /* Between tables the book can still show the seat that has just finished:
+           the settlement is booked when the authority's record reaches the chain, a
+           moment after the seat handed in its consent. An agent told it is "already
+           seated at a table" there is not out — it is the last table still being
+           paid — so this waits for the seat to be released instead of reporting the
+           end of the run. */
+        if (sitting > 1) {
+            const settled = Date.now() + timeoutMs;
+            for (let said = false;;) {
+                const seat = await readAgentEntry(productUrl, tournamentId, chip);
+                if (seat?.state !== "seated")
+                    break;
+                if (Date.now() >= settled) {
+                    /* Before calling it stuck: a disputed table holds the book's seat for
+                       the whole window, so the wait ending is the expected shape rather
+                       than a broken settlement, and the agent needs the time, not an
+                       error. */
+                    const disputedUntilMs = await disputeHolding(productUrl, tournamentId, chip);
+                    if (disputedUntilMs !== undefined) {
+                        console.log(`in dispute until ${new Date(disputedUntilMs).toISOString()} — the table settles after that, and the winner is still paid`);
+                        return;
+                    }
+                    fail("the book still shows this agent seated at the table it finished; its settlement " +
+                        "has not been booked, and a fresh entry would be decided on the old stack");
+                }
+                if (!said) {
+                    console.log("settling the table this agent just played");
+                    said = true;
+                }
+                await new Promise((resolve) => setTimeout(resolve, pollMs));
+            }
+        }
+        /* Entering takes two attempts at most. A play is a shared object its owner
+           may take back without the agent's signature, so a redeem planned on the
+           book's last answer can arrive after the play is gone. The chain refuses
+           that by naming an object, which tells an operator nothing they can act
+           on; what tells them something is the second read, of what this agent
+           holds now. */
+        for (let attempt = 1;; attempt += 1) {
+            const standing = await readAgentEntry(productUrl, tournamentId, chip);
+            if (standing?.state === "queued") {
+                console.log(`already_queued stack ${standing.balance}`);
+                break;
+            }
+            plays = await held();
+            let plan;
+            try {
+                plan = planJoin(overview, standing, plays, owner);
+            }
+            catch (error) {
+                if (error instanceof JoinRefused) {
+                    // The first sitting refusing is the agent being told why it cannot
+                    // enter. A later one is the ordinary end of `--until-out`.
+                    if (sitting === 1)
+                        fail(error.message);
+                    console.log(`out ${error.message}`);
+                    return;
+                }
+                throw error;
+            }
+            /* Read rather than matched against the chain's wording: the play this
+               attempt meant to spend is either still held or it is not, and only the
+               second is worth another attempt. */
+            const spending = plan.play?.playId;
+            const takenBack = async () => spending !== undefined && !(await held()).some((play) => play.playId === spending);
+            let executed;
+            try {
+                executed = await sponsorAndExecute(client, joinTransaction(overview, plan, chip));
+            }
+            catch (error) {
+                if (attempt > 1 || !(await takenBack()))
+                    throw error;
+                console.log(`play_taken_back ${spending}`);
+                console.log(playTakenBackNext());
+                continue;
+            }
+            console.log(`${plan.redeem ? "redeemed_and_queued" : "queued"} ${executed.digest} ${executed.status}`);
+            if (executed.status === "success")
+                break;
+            if (attempt === 1 && (await takenBack())) {
+                console.log(`play_taken_back ${spending}`);
+                console.log(playTakenBackNext());
+                continue;
+            }
+            fail(executed.error ?? "the join aborted on chain");
+        }
+        const deadline = Date.now() + timeoutMs;
+        let last = "";
+        let seated;
+        /* The product forms tables from its own last read of the book, taken once
+           a tick, so a join that just landed reads as idle for a moment. That is
+           the read catching up, not a join that failed — but a join that really
+           did not hold reads the same way, so it is tolerated for a few polls and
+           then believed. */
+        const SETTLING_POLLS = 5;
+        let settling = 0;
+        while (Date.now() < deadline) {
+            const answer = await presentToTournament(client);
+            const line = answer.state === "queued"
+                ? `queued waiting ${answer.waiting} stack ${answer.stack}`
+                : answer.state;
+            if (line !== last)
+                console.log(line);
+            last = line;
+            if (answer.state === "seated" && answer.offerId && answer.seat) {
+                seated = answer;
+                break;
+            }
+            /* Queued when matchmaking closes, no table ever forms: waiting out the
+               timeout then ended the run as a failure while nothing was wrong but
+               the clock. Said as the end it is. */
+            if (answer.state === "queued") {
+                const now = await readTournament(productUrl, tournamentId);
+                if (now.phase !== "open") {
+                    console.log(matchmakingOverLine(now.phase, true));
+                    console.log(describeNext({ action: "stop" }));
+                    return;
+                }
+            }
+            /* Seated on chain, but the product has not published the offer this seat
+               accepts. Waiting out the timeout taught the agent nothing and then
+               threw, and `leave` refuses a seated agent — so say which table holds
+               the seat and stop, which is the only move left. */
+            if (answer.state === "seated") {
+                console.log(`seated_without_offer execution ${answer.executionId ?? "not_yet_published"}`);
+                console.log("this agent already holds a seat, so it cannot leave the queue; watch the execution and rejoin once the product publishes its offer");
+                return;
+            }
+            if (answer.state === "idle" || answer.state === "not_entered") {
+                settling += 1;
+                if (settling > SETTLING_POLLS)
+                    fail(`the book has shown this agent ${answer.state} for ${settling} polls; the join did not hold`);
+            }
+            else {
+                settling = 0;
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollMs));
+        }
+        if (!seated)
+            fail("no table formed before --timeout-ms");
+        const offerId = seated.offerId;
+        console.log(`offer ${offerId}`);
+        console.log(`seat ${seated.seat}`);
+        if (seated.executionId)
+            console.log(`watch ${client.productUrl.replace(/\/$/, "")}/arena/matches/${seated.executionId}`);
+        if (!values.play)
+            return;
+        const seat = seated.seat;
+        takeSeatLock(values.key, values["agent-id"]);
+        const report = await playSeat({
+            productUrl: client.productUrl,
+            offerId,
+            seat,
+            agentId: client.agentId,
+            agent: client.agent,
+            onEliminated: () => console.log("eliminated staying_to_terminal"),
+            onHand: (hand) => console.log(`hand ${hand.number + 1}${hand.stack !== null ? ` stack ${hand.stack}` : ""}`),
+            strategy: "fold-heavy",
+            decide,
+        });
+        for (const line of playReportLines(report))
+            console.log(line);
+        await handInSeatConsent({
+            productUrl: client.productUrl,
+            agent: client.agent,
+            agentId: client.agentId,
+            offerId,
+            seat,
+            report,
+        });
+        if (!values["until-out"])
+            return;
+        /* Between tables. The book takes a moment to show the settlement, and a
+           re-entry decided before it lands would be decided on the last table's
+           balance. */
+        const closed = await readTournament(productUrl, tournamentId);
+        if (closed.phase !== "open") {
+            console.log(matchmakingOverLine(closed.phase, false));
+            return;
+        }
+        console.log(`sitting ${sitting} done`);
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+    }
+}
 /** `dopa-open claim-invite`: the link a wallet needs to claim this agent.
  *
  *  A claim is two consents. The wallet signs on the arena's page; you, holding
@@ -919,14 +1683,18 @@ async function commandClaimInvite(args) {
         owner,
         ttlMs: Math.round(hours * 3_600_000),
     });
+    /* The link takes the compact encoding; `invite` still prints the hex, which
+       is what the claim body posts and what a reader can paste anywhere that
+       expects the old form. Both decode to the same 192 bytes. */
     const token = encodeClaimInvite(invite);
+    const linkToken = encodeClaimInviteCompact(invite);
     /* The arena's pages and its API share an origin on a deployment; a local
        stack serves them apart, which is what --arena-url is for. */
     const arena = (values["arena-url"] ?? productUrl).replace(/\/$/, "");
     console.log(`invite ${token}`);
     console.log(`for ${owner ? values.owner : "whoever opens the link"}`);
     console.log(`expires ${new Date(Number(invite.expiresAtMs)).toISOString()}`);
-    console.log(`claim_link ${claimInviteLink(arena, agentIdHex, token)}`);
+    console.log(`claim_link ${claimInviteLink(arena, agentIdHex, linkToken)}`);
 }
 const USAGE = `usage: dopa-open <command>
 
@@ -939,28 +1707,61 @@ const USAGE = `usage: dopa-open <command>
             (--name/--handle/--bio name it in the same breath)
   name      name an agent this key owns, or rename it before it is claimed
   queue     enter a tour and wait for a seat (--play to play it straight through)
-  play      drive a seat to a terminal disposition, from --table or --offer
+  room      open|join
+            the private room: open one and print the invite its guest needs, or
+            join one by that id and take the seat it reserved (--play)
+  tournament status|join|leave|give-back
+            the open-entry tournament on this key: read the book, queue (redeeming
+            first when run out), leave the queue, or give an unplayed ticket back
+  play      drive a seat to a terminal disposition, from --table or --offer,
+            and hand in its settlement consent when one is reached
   consent   recompute the settlement digest and submit this seat's consent
+  turn      what this seat sees right now, as JSON, then stop
+  act       send one move for that turn, with a line, then stop
   sign      sign a join/action/resume request described by a JSON file
   key       authorise a replacement key for an agent, or retire it
 
 keygen writes the key file named by --out; every other command reads the one
 named by --key. Both default to .dopa-keypair.
 play and queue --play pick moves with --strategy, a filler for a seat nobody is
-deciding for. Pass --decide <module.mjs> instead to play your own: its default
-export is called once per turn with the legal actions, the view and the
-deadline, and returns one action. The two contradict each other and cannot be
-passed together.
+deciding for. Pass --decide <module.mjs> instead to play your own: the default export is
+called once per turn with the legal actions, the view, the table and the
+deadline, and returns one action. The SDK exports baselineMove, the policy the
+house itself plays: import it as a starting point, never as an answer.
+--decide and --strategy contradict each other and cannot be passed together.
+turn and act are the other shape: no loop, no module, you between them. turn
+prints the position and exits, act sends one move and exits, and the seat is
+kept in --state (default .dopa-seat), so losing the process does not lose the
+seat. Come back quickly though: the authority keeps each hand's deal for a few
+hands only, and a seat that returns after the table has moved past that window
+cannot resume into it. Treat that as a defect to work around, not a limit to
+build on.
+act requires --say: one line saying why, which rides the move onto the table.
 key requires --product-url --agent-id and either --next-key <file> or --retire.
 It signs with the key the agent registered under, which a rotation does not
 move: after one rotation that is a different file from the one the agent is
 playing with. A key that was lost cannot sign its own replacement.
 queue requires --product-url --agent-id, and takes --tour playground|tournament
-(default playground), --timeout-ms, --poll-ms and --play.
+(default playground), --timeout-ms, --poll-ms, --play and, on the playground,
+--min-agents 1|2|3: the fewest real agents, you included, you will sit with. A
+fill that cannot meet it leaves you queued (at_fill stays_queued) instead of
+seating you with house seats; raise --timeout-ms to wait for more agents.
+tournament takes --product-url and, for join and leave, --agent-id; --tournament
+names one (default: the one the product runs). join sends queue_join for exactly
+the booked balance through the product's gas sponsorship, with redeem first in
+the same transaction when the agent has run out; it refuses when the wallet holds
+other than the booked balance, and --owner names the bundle a first redeem draws
+from. join then waits for a table (--play plays it); leave returns the escrow.
 play on a tour seat requires --product-url --agent-id --table. On an offer it
 requires --product-url --agent-id --offer --seat --coordinator-key
 --time-authority-key. consent requires --product-url --offer --seat
---terminal-nonce --terminal-commitment --entitlement.`;
+--terminal-nonce --terminal-commitment --entitlement.
+The chips move on a cooperative settle, which needs every admitted seat's
+signature — a seat entitled to zero included — within 120 seconds of the
+terminal. play and queue --play hand that in for you, printing
+consent_deadline_ms; consent is for a seat that drove its own session. A seat
+that busted early owes it too: its own payout is nothing and the table's is
+what it is holding.`;
 async function main() {
     const [command, ...rest] = process.argv.slice(2);
     /* `--help` anywhere, not only alone. `dopa-open register --help` is what a
@@ -986,8 +1787,16 @@ async function main() {
             return commandName(rest);
         case "queue":
             return commandQueue(rest);
+        case "room":
+            return commandRoom(rest);
+        case "tournament":
+            return commandTournament(rest);
         case "play":
             return commandPlay(rest);
+        case "turn":
+            return commandTurn(rest);
+        case "act":
+            return commandAct(rest);
         case "consent":
             return commandConsent(rest);
         case "sign":