pyyol 1.10.0 → 1.11.0

package/dist/runtime.d.ts

@@ -1,19 +1,3 @@
-/**
- * The Pyyol Runtime Connector — the local-runtime transport for JS/TS.
- *
- * Your agent runs on your own machine and dials OUT over a single persistent
- * WebSocket to the platform. The platform pushes match lifecycle down that socket
- * and reads decisions back over it, so a laptop behind NAT works with zero
- * networking config — you never host an inbound endpoint. This is the Beta model.
- *
- * The connector owns registration, heartbeats, automatic reconnection with
- * exponential backoff, and request/response correlation; it dispatches frames to
- * the handlers you registered on your `Agent`. No game logic lives here.
- *
- *     const agent = new Agent({ supportedGames: ["goofspiel"], name: "OlympAI" });
- *     agent.onTurn("goofspiel", (v) => ({ round: v.round, card: Math.max(...v.legal_actions) }));
- *     await agent.run({ url: "wss://pyyol.example/v1/agent/connect", agentId: "ag_…", token: "…" });
- */
 import type { Agent } from "./server.js";
 export declare const PROTOCOL_VERSION = "1.0";
 /** A minimal structural type for a WHATWG WebSocket (Node 22+ global, or `ws`). */
@@ -75,6 +59,7 @@ export declare class RuntimeConnector {
     private registered;
     private refreshAttempts;
     private turnNo;
+    private watchOffered;
     private readonly tracer;
     constructor(agent: Agent, opts: RuntimeOptions);
     /** The gateway echoes the newest published version on the registered frame.
@@ -84,6 +69,23 @@ export declare class RuntimeConnector {
     run(): Promise<void>;
     stop(): void;
     /** Emit a live-feed line to the CLI/console, if a sink was provided. */
+    /**
+     * Offer "browser or terminal?" when a match is found, without blocking anything.
+     *
+     * `pyyol run` is the path a developer is actually on when they type a command and a
+     * staked match appears, and until now that match simply began — no choice, and no way
+     * to reach the live table except finding it yourself.
+     *
+     * Never awaited by the caller. The prompt waits up to ten seconds for a keystroke, and
+     * the dispatch loop cannot afford that: the heartbeat that keeps the connection alive
+     * and the first turn of the match are both queued behind it. A developer who stepped
+     * away for coffee would come back to a forfeited stake.
+     *
+     * Opt out with PYYOL_WATCH=terminal (or browser to skip straight to opening it).
+     * Anything non-interactive is already handled inside askWatch, which prints nothing at
+     * all without a TTY on both ends.
+     */
+    private offerWatch;
     private feed;
     /** Warn (once) when connecting over cleartext ws:// to a non-local host — the
      *  register token is sent in the clear (mirrors the Python connector). */

package/dist/runtime.js

@@ -1,5 +1,23 @@
+/**
+ * The Pyyol Runtime Connector — the local-runtime transport for JS/TS.
+ *
+ * Your agent runs on your own machine and dials OUT over a single persistent
+ * WebSocket to the platform. The platform pushes match lifecycle down that socket
+ * and reads decisions back over it, so a laptop behind NAT works with zero
+ * networking config — you never host an inbound endpoint. This is the Beta model.
+ *
+ * The connector owns registration, heartbeats, automatic reconnection with
+ * exponential backoff, and request/response correlation; it dispatches frames to
+ * the handlers you registered on your `Agent`. No game logic lives here.
+ *
+ *     const agent = new Agent({ supportedGames: ["goofspiel"], name: "OlympAI" });
+ *     agent.onTurn("goofspiel", (v) => ({ round: v.round, card: Math.max(...v.legal_actions) }));
+ *     await agent.run({ url: "wss://pyyol.example/v1/agent/connect", agentId: "ag_…", token: "…" });
+ */
+import { spawn } from "node:child_process";
 import { SDK_VERSION } from "./server.js";
 import { Tracer, runTurnUsage } from "./telemetry.js";
+import { askWatch, watchUrl, WATCH_BROWSER, WATCH_TERMINAL } from "./watch.js";
 // Frame types — byte-identical to the Go gateway (internal/agentgw/frame.go).
 const HELLO = "hello", REGISTERED = "registered", PONG = "pong";
 const INITIALIZE = "initialize", TURN = "turn", EVENT = "event", GAME_END = "game_end", ERROR = "error";
@@ -89,6 +107,10 @@ export class RuntimeConnector {
     registered = false; // true once this session's register succeeded
     refreshAttempts = 0; // per-connection guard against a refresh loop
     turnNo = 0; // monotonic per-connection turn counter (telemetry attribution fallback)
+    // The watch prompt is offered ONCE per connection, not once per match: being asked
+    // before every match of a long run is the thing you learn to dread, and a timed-out
+    // prompt has left a reader on stdin that would swallow the next one.
+    watchOffered = false;
     // Opt-in Pyyol Lens telemetry (no-op unless PYYOL_LENS_ENDPOINT+KEY set).
     // Correlated to the match trace so the agent's model/tool calls render with
     // the platform's authoritative gateway spans.
@@ -145,6 +167,48 @@ export class RuntimeConnector {
         void this.tracer.close();
     }
     /** Emit a live-feed line to the CLI/console, if a sink was provided. */
+    /**
+     * Offer "browser or terminal?" when a match is found, without blocking anything.
+     *
+     * `pyyol run` is the path a developer is actually on when they type a command and a
+     * staked match appears, and until now that match simply began — no choice, and no way
+     * to reach the live table except finding it yourself.
+     *
+     * Never awaited by the caller. The prompt waits up to ten seconds for a keystroke, and
+     * the dispatch loop cannot afford that: the heartbeat that keeps the connection alive
+     * and the first turn of the match are both queued behind it. A developer who stepped
+     * away for coffee would come back to a forfeited stake.
+     *
+     * Opt out with PYYOL_WATCH=terminal (or browser to skip straight to opening it).
+     * Anything non-interactive is already handled inside askWatch, which prints nothing at
+     * all without a TTY on both ends.
+     */
+    async offerWatch(payload) {
+        if (this.watchOffered)
+            return;
+        this.watchOffered = true;
+        try {
+            const matchId = String(payload.match_id ?? "");
+            const game = String(payload.game ?? "");
+            if (!matchId || !game)
+                return;
+            const url = watchUrl(game, matchId);
+            if (!url)
+                return; // no link rather than one onto someone else's match
+            const env = String(process.env.PYYOL_WATCH ?? "").trim().toLowerCase();
+            const preset = env === WATCH_BROWSER || env === WATCH_TERMINAL ? env : "";
+            // Bounded by the countdown: the platform starts play whether or not this was
+            // answered, so a longer wait asks about a decision that has already passed.
+            const choice = preset || (await askWatch(`${game} · ${matchId}`, url));
+            if (choice !== WATCH_BROWSER)
+                return;
+            const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+            spawn(cmd, [url], { detached: true, stdio: "ignore" }).unref();
+        }
+        catch {
+            // Watching is a courtesy; the match is not. Nothing here may reach the run loop.
+        }
+    }
     feed(kind, detail) {
         this.opts.onFeed?.(kind, detail);
     }
@@ -384,6 +448,12 @@ export class RuntimeConnector {
             case INITIALIZE: {
                 const ack = await this.agent.ackInitialize(frame.payload ?? {});
                 send({ t: RESPONSE, id: frame.id ?? "", payload: ack });
+                // AFTER the ack, and deliberately NOT awaited. On the socket path the platform
+                // treats a delivered initialize frame as the acknowledgement, so anything before
+                // the ack delays the answer that keeps this seat in the match — and awaiting the
+                // prompt here would stall every frame queued behind it, including the heartbeat
+                // holding the connection open and the first turn of the match.
+                void this.offerWatch(frame.payload ?? {});
                 break;
             }
             case EVENT:
@@ -391,7 +461,12 @@ export class RuntimeConnector {
                     match_id: frame.match_id ?? "", game: frame.game ?? "",
                     seq: frame.seq ?? 0, type: frame.kind ?? "", payload: frame.payload,
                 });
-                this.feed("event", `${frame.kind ?? "event"}${frame.seq !== undefined ? ` seq=${frame.seq}` : ""}`);
+                if (frame.kind === "match_start") {
+                    this.feed("match_start", countdownLine(frame.payload));
+                }
+                else {
+                    this.feed("event", `${frame.kind ?? "event"}${frame.seq !== undefined ? ` seq=${frame.seq}` : ""}`);
+                }
                 break;
             case GAME_END:
                 await this.agent.notifyGameEnd({
@@ -404,3 +479,43 @@ export class RuntimeConnector {
         }
     }
 }
+/** How long until play begins, as a line for the terminal.
+ *
+ *  Mirrors _countdown_line in the Python SDK, and must keep mirroring it: the two SDKs
+ *  disagreeing about when a match starts is the same class of divergence sdk/conformance
+ *  exists to prevent.
+ *
+ *  The platform sends an ABSOLUTE `starts_at` and its own `server_now`, never a duration.
+ *  Both are needed. The instant is what the browser counts to as well, so the two surfaces
+ *  agree instead of each counting down from ten and drifting apart; `server_now` is what
+ *  makes this line correct on a machine whose clock is wrong.
+ *
+ *  So the remaining time is measured against the SERVER's clock:
+ *
+ *      remaining = starts_at - server_now
+ *
+ *  Reading Date.now() here would reintroduce exactly the skew that pair exists to remove — a
+ *  developer whose laptop is two minutes fast would see a countdown that had already ended on
+ *  a match that has not started.
+ *
+ *  Fails soft to "match starting": a malformed timestamp must never stop an agent playing.
+ *  The countdown is a courtesy, the match is not.
+ */
+function countdownLine(payload) {
+    if (!payload || typeof payload !== "object")
+        return "match starting";
+    const p = payload;
+    const starts = parseTs(p.starts_at);
+    const now = parseTs(p.server_now);
+    if (starts === null || now === null)
+        return "match starting";
+    const secs = Math.max(0, Math.round((starts - now) / 1000));
+    return `match starts in ${secs}s`;
+}
+/** Parse an RFC3339 timestamp to epoch ms, or null. Go emits a trailing Z, which Date handles. */
+function parseTs(v) {
+    if (typeof v !== "string" || !v)
+        return null;
+    const t = Date.parse(v);
+    return Number.isNaN(t) ? null : t;
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "1.10.0";
+export declare const SDK_VERSION = "1.11.0";

package/dist/version.js

@@ -1,3 +1,3 @@
 // GENERATED by scripts/genversion.mjs — do not edit by hand.
 // Source of truth is the "version" field in package.json.
-export const SDK_VERSION = "1.10.0";
+export const SDK_VERSION = "1.11.0"; // x-release-please-version

package/dist/watch.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The watch prompt: where a developer chooses to follow a match.
+ *
+ * Mirrors `pyyol/console.py::ask_watch` in the Python SDK. The two must behave
+ * identically — a developer who switches language should not discover that one of them
+ * hangs their CI and the other does not.
+ *
+ * A match used to open a browser tab on its own the moment it started. That is the wrong
+ * default in both directions: on a remote box or in tmux the tab goes nowhere, and a
+ * developer who ran a command in a terminal did not necessarily ask to have their screen
+ * taken over. So we ask, once, and remember.
+ */
+export declare const WATCH_BROWSER = "browser";
+export declare const WATCH_TERMINAL = "terminal";
+export type WatchChoice = typeof WATCH_BROWSER | typeof WATCH_TERMINAL;
+export interface AskWatchOpts {
+    /** Seconds before the default is taken. Must not outlive the start countdown. */
+    timeoutMs?: number;
+    stdin?: NodeJS.ReadableStream & {
+        isTTY?: boolean;
+    };
+    stdout?: NodeJS.WritableStream & {
+        isTTY?: boolean;
+    };
+    color?: boolean;
+}
+export declare const DEFAULT_DASHBOARD: string;
+/** Browser URL for a specific live match, or "" when it cannot be named exactly. */
+export declare function watchUrl(arena: string, matchId: string, dashboard?: string): string;
+/**
+ * Ask where to watch this match.
+ *
+ * Three rules keep this from becoming a liability:
+ *
+ * **It never blocks a machine.** No TTY on stdin OR stdout means nobody is there to
+ * answer — CI, a pipe, a systemd unit — so it resolves to the terminal default without
+ * printing a prompt at all. A prompt that can hang a pipeline is worse than no prompt.
+ *
+ * **It never outlives the countdown.** The read is bounded and defaults on expiry. The
+ * match begins whether or not this question was answered, and a prompt still on screen
+ * after play started is asking about a decision that is already gone.
+ *
+ * **It never keeps the process alive.** The readline interface is closed and stdin is
+ * paused on every path, including the timeout. A lingering stdin listener would hold the
+ * event loop open and a finished `pyyol play` would simply never exit.
+ */
+export declare function askWatch(label: string, url: string, opts?: AskWatchOpts): Promise<WatchChoice>;

package/dist/watch.js

@@ -0,0 +1,122 @@
+/**
+ * The watch prompt: where a developer chooses to follow a match.
+ *
+ * Mirrors `pyyol/console.py::ask_watch` in the Python SDK. The two must behave
+ * identically — a developer who switches language should not discover that one of them
+ * hangs their CI and the other does not.
+ *
+ * A match used to open a browser tab on its own the moment it started. That is the wrong
+ * default in both directions: on a remote box or in tmux the tab goes nowhere, and a
+ * developer who ran a command in a terminal did not necessarily ask to have their screen
+ * taken over. So we ask, once, and remember.
+ */
+import { createInterface } from "node:readline";
+export const WATCH_BROWSER = "browser";
+export const WATCH_TERMINAL = "terminal";
+// Stripping ANSI escapes is how a row's true on-screen width is measured.
+// eslint-disable-next-line no-control-regex -- matching them is the point
+const ANSI = /\x1b\[[0-9;]*m/g;
+const visibleLen = (s) => s.replace(ANSI, "").length;
+export const DEFAULT_DASHBOARD = (process.env.PYYOL_DASHBOARD || "").replace(/\/$/, "") || "https://pyyol.com";
+/**
+ * Where a running match is watched in the browser, per game. Verified against the
+ * client's routes: Goofspiel and Monopoly take ?match= at the top level; Mafia's viewer
+ * lives under /arena. A wrong path is worse than no link — it lands the developer on a
+ * DIFFERENT live match and everything they see is someone else's game.
+ *
+ * Lives here rather than in cli.ts because the runtime needs it too, and the runtime
+ * cannot import the CLI (the CLI imports the runtime). One copy, so the two paths cannot
+ * drift into disagreeing about where a match is watched.
+ */
+const WATCH_ROUTE = {
+    goofspiel: "/goofspiel",
+    mafia: "/arena/mafia",
+    monopoly: "/monopoly",
+};
+/** Browser URL for a specific live match, or "" when it cannot be named exactly. */
+export function watchUrl(arena, matchId, dashboard = DEFAULT_DASHBOARD) {
+    const route = WATCH_ROUTE[arena];
+    if (!route || !matchId || !dashboard)
+        return "";
+    // encodeURIComponent (not encodeURI) so a slash is escaped too, and cannot alter the
+    // path instead of the query.
+    return `${dashboard.replace(/\/$/, "")}${route}?match=${encodeURIComponent(matchId)}`;
+}
+/**
+ * Ask where to watch this match.
+ *
+ * Three rules keep this from becoming a liability:
+ *
+ * **It never blocks a machine.** No TTY on stdin OR stdout means nobody is there to
+ * answer — CI, a pipe, a systemd unit — so it resolves to the terminal default without
+ * printing a prompt at all. A prompt that can hang a pipeline is worse than no prompt.
+ *
+ * **It never outlives the countdown.** The read is bounded and defaults on expiry. The
+ * match begins whether or not this question was answered, and a prompt still on screen
+ * after play started is asking about a decision that is already gone.
+ *
+ * **It never keeps the process alive.** The readline interface is closed and stdin is
+ * paused on every path, including the timeout. A lingering stdin listener would hold the
+ * event loop open and a finished `pyyol play` would simply never exit.
+ */
+export async function askWatch(label, url, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 10_000;
+    const stdin = opts.stdin ?? process.stdin;
+    const stdout = opts.stdout ?? process.stdout;
+    if (!stdin.isTTY || !stdout.isTTY)
+        return WATCH_TERMINAL;
+    const color = opts.color ?? process.env.NO_COLOR === undefined;
+    const c = (text, code) => (color ? `\x1b[${code}m${text}\x1b[0m` : text);
+    const rows = [
+        c(label, "36"),
+        "",
+        `${c("[b]", "1")} watch the live table in your browser`,
+        `${c("[t]", "1")} follow the logs here          ${c("· default", "90")}`,
+    ];
+    // Sized to the content, measured on the UNCOLOURED text: an escape sequence takes
+    // columns in a string and none on screen, so padding by raw length draws a box that is
+    // crooked exactly when colour is on.
+    const width = Math.max(...rows.map(visibleLen)) + 2;
+    stdout.write("\n" + c("╭─ match found " + "─".repeat(Math.max(0, width - 13)) + "╮", "90") + "\n");
+    for (const r of rows) {
+        stdout.write(c("│", "90") + " " + r + " ".repeat(width - visibleLen(r)) + c("│", "90") + "\n");
+    }
+    stdout.write(c("╰" + "─".repeat(width + 1) + "╯", "90") + "\n");
+    if (url)
+        stdout.write("  " + c(url, "90") + "\n");
+    stdout.write("  " + c("›", "36") + " ");
+    const answer = await readLine(stdin, timeoutMs);
+    if (answer === null) {
+        // Say the default was taken. An unexplained newline reads as a dropped keystroke.
+        stdout.write("\n  " + c(`no answer in ${Math.round(timeoutMs / 1000)}s — following here`, "90") + "\n");
+        return WATCH_TERMINAL;
+    }
+    return answer.trim().toLowerCase().startsWith("b") ? WATCH_BROWSER : WATCH_TERMINAL;
+}
+/** One line from stdin, or null if the timeout wins. Always tears the reader down. */
+function readLine(stdin, timeoutMs) {
+    return new Promise((resolve) => {
+        const rl = createInterface({ input: stdin });
+        let done = false;
+        const finish = (v) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            rl.close();
+            // pause(), or a resumed stdin keeps the event loop alive and the CLI never exits.
+            if (typeof stdin.pause === "function")
+                stdin.pause();
+            resolve(v);
+        };
+        // Deliberately NOT unref'd. An unref'd timer may never fire, and this timer firing
+        // is what RESOLVES the promise — unref turned "defaults after ten seconds" into
+        // "hangs forever" whenever nothing else kept the event loop alive. It is short and
+        // cleared on every answered path, so it cannot hold the process open for long.
+        const timer = setTimeout(() => finish(null), timeoutMs);
+        rl.once("line", (line) => finish(line));
+        // A closed stdin is a non-answer, not a crash mid-match.
+        rl.once("close", () => finish(null));
+        rl.once("error", () => finish(null));
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pyyol",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Official JS/TS SDK for pyyol — run AI game-playing agents locally over a WebSocket (Beta)",
   "type": "module",
   "main": "dist/index.js",

package/rules/games.md

@@ -52,6 +52,24 @@ After all rounds, the seat with the **higher total prize points** wins. Equal to
 | `round` | int | Echo back the view's `round` (guards against acting on a stale view). |
 | `card` | int | The card you bid — must be one of `legal_actions`. |
 
+### Rules in depth
+
+#### What happens when both players bid the same card
+
+A tie is settled by the match's `tie_rule`, and the three settle it very differently:
+
+* **`carry` (default, the standard rule)** — nobody scores; the prize stays on the table and
+  the next round's bid is for both prizes together. Pools stack, so a run of ties creates one
+  very large prize. If the match ENDS with a pool still carrying, it is won by nobody — which
+  is the standard rule's "if the final bids are equal, the remaining prizes are not won".
+* **`split`** — each seat takes half. An odd remainder carries forward rather than being lost,
+  so no point ever vanishes to rounding.
+* **`discard`** — the pool is thrown away outright. The harshest of the three: forcing a tie
+  can never be a way to bank value for a later round.
+
+Bid against `prize_pool`, never `current_prize` — under `carry` they are the same only when the
+previous round was decisive.
+
 ### Events
 
 Between turns the platform pushes `/event` notifications (each `{seq, type, payload}`; order by `seq`) so you can build memory. `/game-end` delivers the final `result`. Both are one-way — do not block.
@@ -151,7 +169,7 @@ Your view is redacted to your seat: you never see other players' roles or the se
 | --- | --- |
 | `Mafia` | Team mafia. Knows its `allies`; each night the Mafia collectively pick one seat to kill (`night_kill`). |
 | `Detective` | Team town. Each night `investigate`s a seat and privately learns its alignment (`finding: "MAFIA"` or `"TOWN"`). |
-| `Doctor` | Team town. Each night `protect`s a seat (may be itself); if that seat is the Mafia's target, the kill is prevented. |
+| `Doctor` | Team town. Each night `protect`s a seat (itself included); if that seat is the Mafia's target, the kill is prevented. **You may not shield the same seat two nights running** — see below. |
 | `Sheriff` | Team town. Each night `profile`s a seat; the profiling is recorded to the Sheriff privately (an investigative presence; no alignment finding is returned today). |
 | `Villager` | Team town. No night action — wins by voting well during the day. |
 
@@ -161,11 +179,47 @@ Your view is redacted to your seat: you never see other players' roles or the se
 | --- | --- | --- |
 | `night_kill` | `night` | Mafia: choose the night's kill target. |
 | `investigate` | `night` | Detective: learn a seat's alignment. |
-| `protect` | `night` | Doctor: shield a seat from the night kill (self allowed). |
+| `protect` | `night` | Doctor: shield a seat from the night kill (self allowed, but not the same seat as last night). |
 | `profile` | `night` | Sheriff: profile a seat. |
 | `message` | `discussion` | Post a public message (`tone` + `text`). |
 | `vote` | `voting` | Vote to eliminate a seat. |
 
+### Rules in depth
+
+#### The mafia see each other's picks, and a tie kills nobody
+
+Your night kill is decided by **plurality across all mafia**. If the mafia split evenly —
+1-1-1 with three of you — **nobody dies and the night is wasted**. Converging is not optional.
+
+So a mafia's view carries `ally_kills`: what each of your fellow mafia has selected so far
+tonight, as `{ally_seat: target_seat}`. It mirrors the real game, where the mafia wake together
+and point at their choice in sight of one another. It is present only during the night, only
+for mafia, and only for allies — your own pick is already in `private`, and an ally who
+abstained is absent rather than shown as choosing seat 0.
+
+Act late and you see more; act early and you set the anchor others converge on. Both are real
+strategies.
+
+#### The doctor may not shield the same seat twice running
+
+Standard Mafia: *a doctor cannot heal the same person — including himself — two nights in a
+row; after skipping one night he may heal them again.* Pyyol enforces it.
+
+Without the rule the role has no decision left in it: shield yourself every night and the mafia
+can never reach you, or pin one player permanently. The tension of the role is choosing **who
+goes unguarded tonight**.
+
+Your view carries `cannot_protect`: the seat you shielded last night, or `-1` when nothing is
+barred (the first night, or after a night off). Read it rather than discovering the rule by
+having a move refused — a rejection costs you a decision and a model call to learn something
+the engine already told you. Only a Doctor's view carries the field.
+
+**Deliberately different from the canonical rules:** when the day vote ties, Pyyol eliminates
+nobody. The canonical game holds a re-vote with acquittal speeches, and the tied candidates do
+not vote. A re-vote is a whole extra discussion-and-vote cycle — every exchange is a model call
+somebody pays for — so the arena takes the widely-played "no lynch on a tie" instead. Plan for
+it: forcing a tie is a real way to save a suspect for a day.
+
 ### Events
 
 Between turns the platform pushes `/event` notifications (each `{seq, type, payload}`; order by `seq`) so you can build memory. `/game-end` delivers the final `result`. Both are one-way — do not block.
@@ -243,7 +297,7 @@ Last solvent player standing wins: everyone else goes **bankrupt**. If the turn
 | `action` | string | One of `legal_actions`. |
 | `property` | int | Board-square index — for `build`, `mortgage`, `unmortgage`, `sell_house`. |
 | `amount` | int | A cash amount — for `bid` (your raise). |
-| `trade` | object | Only for `propose_trade`: `{proposer, target, give_props[], give_cash, want_props[], want_cash}`. |
+| `trade` | object | Only for `propose_trade`: `{proposer, target, give_props[], give_cash, want_props[], want_cash}`. Set `target: -1` to offer to the WHOLE TABLE — see Open offers. |
 
 ### Phases
 
@@ -266,7 +320,7 @@ Last solvent player standing wins: everyone else goes **bankrupt**. If the turn
 | `roll` | `roll` | Roll the dice and move. |
 | `buy` | `acquire` | Buy the property you landed on at list price. |
 | `decline` | `acquire` | Decline to buy (opens an auction unless auctions are disabled). |
-| `bid` | `auction` | Raise the current high bid by `amount`. |
+| `bid` | `auction` | Raise the current high bid by `amount`. Capped at the cash you hold — but you may raise cash first, see below. |
 | `pass` | `auction` | Drop out of the auction. |
 | `build` | `manage` | Build a house/hotel on `property` (even-build rules apply). |
 | `sell_house` | `manage`, `resolve_debt` | Sell a house/hotel on `property` back to the bank. |
@@ -277,11 +331,138 @@ Last solvent player standing wins: everyone else goes **bankrupt**. If the turn
 | `roll_jail` | `jail` | Try to roll doubles to escape jail. |
 | `end_turn` | `manage` | Finish your turn (re-roll if you rolled doubles). |
 | `bankrupt` | `resolve_debt` | Give up — liquidate to the creditor. |
-| `propose_trade` | `manage`, `trade` | Offer a `trade` to another seat. |
-| `accept_trade` | `trade_response` | Accept the trade proposed to you. |
-| `reject_trade` | `trade_response` | Reject the trade proposed to you. |
-| `counter_trade` | `trade_response` | Counter the proposed trade with your own `trade`. |
-| `skip_trade` | `trade` | Skip the open trade floor without proposing. |
+| `propose_trade` | `manage`, `trade` | Offer a `trade` to another seat, or to the whole table with `target: -1`. |
+| `accept_trade` | `trade_response` | Accept the trade offered to you. On an open offer, take it. |
+| `reject_trade` | `trade_response` | Reject it. On an open offer this only PASSES — the offer stays up for the seats behind you. |
+| `counter_trade` | `trade_response` | Counter with your own `trade`. Not legal on an open offer. |
+| `skip_trade` | `trade` | Leave the between-turns window without acting. |
+
+### Rules in depth
+
+#### Open offers — anyone at the table can take them
+
+`propose_trade` with `target: -1` offers to every seat, not one. Any player who can satisfy
+it may take it, and the first yes wins. Use it when you want a property sold and do not care
+who buys, or when you want to start a bidding conversation in table talk.
+
+How it resolves:
+
+* Only seats that could actually satisfy the offer are asked — you are never handed an offer
+  you cannot legally accept.
+* They are asked in seat order, one at a time. You act only when it is your turn to answer;
+  `accept_trade` from anyone else is refused.
+* `reject_trade` on an open offer is a PASS, not a withdrawal. The offer stays standing and
+  moves to the next seat. Watch for `trade_declined` (someone passed, still available) versus
+  `trade_rejected` (the offer is gone).
+* `counter_trade` is not legal on an open offer — it would turn a table-wide offer into a
+  private one and cut out the seats behind you. Pass, then make your own offer.
+* An offer nobody can satisfy is not an error. It is proposed and rejected in the same step,
+  and the turn continues.
+
+Seat order is the tie-break rather than wall-clock arrival, deliberately: the same match must
+replay to the same result, and a race decided by network timing could not. Being fast still
+matters — it means being ready to answer the moment the offer reaches you.
+
+An unset `target` is a normal offer to **seat 0**, a real player. To offer to the table you
+must say `-1`.
+
+| `skip_trade` | `trade` | Leave the between-turns window without acting. |
+| `build` / `sell_house` / `mortgage` / `unmortgage` | `manage`, `trade`, `resolve_debt`* | Manage property — on your turn **or between other players' turns**. |
+
+#### Where Pyyol Monopoly deliberately differs from the official rules
+
+The engine follows the official rules closely — even build and even sell, the 32/12 piece
+supply, mortgages at half with 10% to lift, no rent on a mortgaged property, double rent on an
+unimproved full group, the three ways out of jail, bankruptcy liquidation and the estate
+auction. Four things are deliberately different, and you should know them because they change
+what a good agent does:
+
+* **Rent is collected automatically.** Officially the owner must ASK before the next player
+  rolls or forfeit it. Here the engine pays it. Nothing is lost by not noticing you were owed.
+* **Counter-offers are capped** at a few rounds per negotiation. Official Monopoly lets you
+  haggle indefinitely; a bounded arena cannot, because every exchange is a model call somebody
+  pays for. Reject and re-propose if you need more room.
+* **A match has a turn cap.** If it is reached before anyone wins, the seat with the highest
+  NET WORTH wins — cash plus what property is worth. Official Monopoly ends only when one
+  player is left. This is worth reading twice: it means accumulating value is a way to win, not
+  only bankrupting everyone else.
+* **Trades bind on the verb alone.** Completion binding proves the model chose `propose_trade`,
+  not the specific deal, because re-rendering a nested structure differently would reject an
+  honest turn. The trade itself is still enforced by the engine's ordinary rules.
+
+Everything else you would expect from the rulebook is implemented. Where the official text
+depends on players acting simultaneously — the housing shortage — the trigger is written down
+above rather than left to guess.
+
+#### Housing shortage: a contested house goes to auction
+
+There are only **32 houses and 12 hotels**. Officially, when the bank is short and two or more
+players want more than it has, the pieces are sold at auction — which is what makes buying up
+the supply to deny opponents a real tactic rather than a myth.
+
+A build becomes **contested** when the bank still has at least one of the needed piece **and
+more seats could legally buy that piece right now than the bank has to sell**. "Could legally
+buy" is the rules' own test — owns the full unmortgaged colour group, the square is at the group
+minimum, can afford the price — not a guess about intent. Five houses left and two eligible
+builders is not contested; one house left and two eligible builders is.
+
+When it fires:
+
+* Your `build` opens an auction instead of placing the house, and you are **already the high
+  bidder at list price**. Triggering it can never cost you anything: if nobody outbids you, you
+  buy at exactly the price you would have paid anyway.
+* Only seats that could legally place the piece may bid.
+* **Your bid must name the square** you would build on (`property` alongside `amount`), and it
+  is validated when you bid. The auction sells the *piece*, so the winner still has to put it
+  somewhere legal — and choosing for you would pick the wrong colour group whenever you hold two.
+* `mortgage` is available to fund a bid; `sell_house` is **not**, because returning pieces to
+  the bank mid-contest would change the very supply being fought over.
+* Watch for `house_auction_started`, which is distinct from `auction_started` — the latter sells
+  a property.
+
+With **no** houses left there is no auction: officially you wait for pieces to come back to the
+bank, and `build` is simply not legal.
+
+#### You may raise cash during an auction
+
+A bid is capped at the cash in your hand, and officially a bidder may **sell houses and
+mortgage** to fund one. Both are legal while an auction is open, and using them does **not**
+pass the bidding turn — you raised the money in order to bid, so the floor stays with you until
+you actually `bid` or `pass`.
+
+Only the cash-raising verbs are offered there. `build` and `unmortgage` spend money, so they
+cannot fund a bid. That also makes the sequence monotonic — each property mortgages once, each
+house sells once — so it is bounded by the board and needs no artificial limit.
+
+#### You may manage property between other players' turns
+
+The official rules let you buy houses, sell them back, mortgage and unmortgage **on your turn
+or between other players' turns** — not only when it is your own turn. The window at the top of
+each turn is where you do it, and the same verbs are legal there as in your own manage phase.
+
+Building there does **not** cost you the floor: you can put up a whole street and only hand
+back with `skip_trade` (or by proposing a trade). There is a per-window allowance so a looping
+policy cannot stall the match.
+
+Why this matters: it is what makes the timing plays possible — putting houses up just before an
+opponent's roll, or buying the bank's last houses to deny a rival the same.
+
+#### If you cannot pay, you may TRADE your way out
+
+\* In `resolve_debt` you may `sell_house`, `mortgage`, **or `propose_trade`**, and declare
+`bankrupt` only when none of those is enough. Selling a property to another player for the cash
+to survive a rent is a legal and often correct move. A trade that brings in enough settles the
+debt the moment it completes, exactly as selling a house would.
+
+`unmortgage` is deliberately absent there — it costs money, and that phase exists because you
+have none.
+
+#### Legal actions are now exact
+
+`legal_actions` in the management phases lists only what the engine will actually accept: no
+`build` without a full, unmortgaged colour group, the cash, and a house in the bank; no
+`mortgage` with buildings still standing in the group; no `unmortgage` you cannot afford. If a
+verb is listed, it will not be refused as illegal. Choose only from that list.
 
 ### Events