From ebcad959bfaeb2aa2b86c864cd3b2054a412a360 Mon Sep 17 00:00:00 2001
From: BadWinniePooh <49596084+BadWinniePooh@users.noreply.github.com>
Date: Mon, 4 May 2026 17:55:08 +0200
Subject: [PATCH 1/4] docs(spec): add feature 007 client screen auto-refresh

Spec, plan, tasks, research, data model, contracts, and checklist for
automatic client screen refresh when server broadcasts state changes.
Amends constitution v1.1.1 to permit synchronous stdlib-only polling
wrappers as a replacement for input() when required for display refresh.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .specify/feature.json                         |   2 +-
 .specify/memory/constitution.md               |  10 +-
 CLAUDE.md                                     |   2 +-
 .../checklists/requirements.md                |  34 ++++
 .../contracts/ws-refresh-triggers.md          |  34 ++++
 specs/007-client-screen-sync/data-model.md    | 114 ++++++++++++
 specs/007-client-screen-sync/plan.md          |  90 +++++++++
 specs/007-client-screen-sync/quickstart.md    |  82 ++++++++
 specs/007-client-screen-sync/research.md      |  67 +++++++
 specs/007-client-screen-sync/spec.md          |  96 ++++++++++
 specs/007-client-screen-sync/tasks.md         | 175 ++++++++++++++++++
 11 files changed, 701 insertions(+), 5 deletions(-)
 create mode 100644 specs/007-client-screen-sync/checklists/requirements.md
 create mode 100644 specs/007-client-screen-sync/contracts/ws-refresh-triggers.md
 create mode 100644 specs/007-client-screen-sync/data-model.md
 create mode 100644 specs/007-client-screen-sync/plan.md
 create mode 100644 specs/007-client-screen-sync/quickstart.md
 create mode 100644 specs/007-client-screen-sync/research.md
 create mode 100644 specs/007-client-screen-sync/spec.md
 create mode 100644 specs/007-client-screen-sync/tasks.md

diff --git a/.specify/feature.json b/.specify/feature.json
index 0372b90..e54e1b9 100644
--- a/.specify/feature.json
+++ b/.specify/feature.json
@@ -1,3 +1,3 @@
 {
-  "feature_directory": "specs/005-macos-signed-release"
+  "feature_directory": "specs/007-client-screen-sync"
 }
diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md
index 4c055b5..9387c5f 100644
--- a/.specify/memory/constitution.md
+++ b/.specify/memory/constitution.md
@@ -39,8 +39,12 @@ per-user authentication or user management, no multi-battle support — these
 are permanently out of scope per the PRD. A single shared-secret token
 (`RISUS_TOKEN`) for connection authentication is permitted (see
 `docs/features/secure-session/`). Menu UX (options 1–6, labels, prompts,
-ordering) MUST NOT change. `input()` calls MUST remain synchronous; no
-`prompt_toolkit` or async input libraries may be introduced.
+ordering) MUST NOT change. Input from the operator MUST remain synchronous
+from the caller's perspective; no `prompt_toolkit` or async input libraries
+may be introduced. Replacing the `input()` builtin with a synchronous
+stdlib-only polling wrapper (e.g., `select.select` with a timeout) is
+permitted when required for display refresh, provided the wrapper introduces
+no external dependencies and blocks until a complete line is returned.
 
 **Rationale**: Scope creep breaks the PRD contract and multi-player UX
 assumptions. Keep modifications, configuration, and options at the absolute
@@ -128,4 +132,4 @@ Complexity additions MUST be justified in the plan's Complexity Tracking
 table. Refer to `AGENTS.md` for runtime agent guidance and the hand-off
 checklist.
 
-**Version**: 1.1.0 | **Ratified**: 2026-05-02 | **Last Amended**: 2026-05-03
+**Version**: 1.1.1 | **Ratified**: 2026-05-02 | **Last Amended**: 2026-05-04
diff --git a/CLAUDE.md b/CLAUDE.md
index 393fb62..2a45701 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -17,5 +17,5 @@ Do not duplicate rules here. Update the constitution or AGENTS.md instead.
 <!-- SPECKIT START -->
 For additional context about technologies to be used, project structure,
 shell commands, and other important information, read the current plan at
-`specs/005-macos-signed-release/plan.md`.
+`specs/007-client-screen-sync/plan.md`.
 <!-- SPECKIT END -->
diff --git a/specs/007-client-screen-sync/checklists/requirements.md b/specs/007-client-screen-sync/checklists/requirements.md
new file mode 100644
index 0000000..e1690db
--- /dev/null
+++ b/specs/007-client-screen-sync/checklists/requirements.md
@@ -0,0 +1,34 @@
+# Specification Quality Checklist: Automatic Client Screen Refresh
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning  
+**Created**: 2026-05-04  
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+All items pass. Spec is ready for `/speckit-clarify` or `/speckit-plan`.
diff --git a/specs/007-client-screen-sync/contracts/ws-refresh-triggers.md b/specs/007-client-screen-sync/contracts/ws-refresh-triggers.md
new file mode 100644
index 0000000..fe623a8
--- /dev/null
+++ b/specs/007-client-screen-sync/contracts/ws-refresh-triggers.md
@@ -0,0 +1,34 @@
+# WS Contract: Messages That Trigger Client Screen Refresh
+
+**Feature**: 007-client-screen-sync  
+**Date**: 2026-05-04
+
+## Overview
+
+The client sets `ClientState.update_event` when it receives any of the following server-sent WebSocket frames. The main loop uses this event to decide when to redraw the battle display.
+
+## Refresh-Triggering Frames (Server → Client)
+
+| Frame type | Key fields | Triggers refresh | Reason |
+|------------|------------|------------------|--------|
+| `state` | `players: [{name, cliche, dice, lost_dice}]` | YES | Full game state changed |
+| `presence` | `clients: [names]` | YES | Connected player list changed |
+| `lock_acquired` | `player_name, locked_by` | YES | Lock indicator must update |
+| `lock_released` | `player_name` | YES | Lock indicator must clear |
+
+## Non-Refresh Frames (Server → Client)
+
+| Frame type | Key fields | Triggers refresh | Reason |
+|------------|------------|------------------|--------|
+| `lock_denied` | `player_name, locked_by` | NO | Caller-only; handled inline by submenu |
+| `error` | `message` | NO | Caller-only; displayed inline by submenu |
+
+## Contract Invariants
+
+- The refresh mechanism is display-only — no server protocol changes in this feature.
+- `update_event` is set AFTER `ClientState.apply()` updates internal state, ensuring the main thread always reads fresh data when it calls `show_state()`.
+- `lock_denied` and `error` frames are already handled inline within submenu functions and do not need to interrupt the top-level display loop.
+
+## Protocol Reference
+
+Full WS protocol reference is in `AGENTS.md` under "WS Protocol Reference". This document covers only the refresh-trigger subset relevant to this feature.
diff --git a/specs/007-client-screen-sync/data-model.md b/specs/007-client-screen-sync/data-model.md
new file mode 100644
index 0000000..fc36d41
--- /dev/null
+++ b/specs/007-client-screen-sync/data-model.md
@@ -0,0 +1,114 @@
+# Data Model: Automatic Client Screen Refresh
+
+**Feature**: 007-client-screen-sync  
+**Date**: 2026-05-04
+
+## Existing Entities (unchanged)
+
+### PlayerSnapshot (`client/state.py`)
+
+Immutable snapshot of a single player's current battle state. No changes in this feature.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `str` | Player identifier |
+| `cliche` | `str` | Active cliché description |
+| `dice` | `Optional[int]` | Current dice count; `None` until set |
+| `lost_dice` | `int` | Accumulated lost dice |
+
+### ClientState (`client/state.py`)
+
+Thread-safe container for the current game snapshot. **Modified by this feature.**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `players` | `list[PlayerSnapshot]` | All players in current battle |
+| `presence` | `list[str]` | Names of connected clients |
+| `locks` | `dict[str, str]` | `player_name → lock_holder_display_name` |
+| `_lock` | `threading.Lock` | Guards reads/writes (existing) |
+| **`update_event`** | **`threading.Event`** | **NEW: set by `apply()` on every state change; cleared by main thread after redraw** |
+
+**State transitions for `update_event`**:
+
+```
+Initial state: Event cleared (not set)
+                    │
+                    ▼
+apply() called ─────► update_event.set()
+  (any frame type)
+                    │
+                    ▼
+                Main thread detects event set
+                    │
+                    ▼
+              show_state() called
+                    │
+                    ▼
+              update_event.clear()
+                    │
+                    └──► back to initial state
+```
+
+## New Behavior: `apply()` method
+
+After applying any frame type (`state`, `presence`, `lock_acquired`, `lock_released`), `apply()` calls `self.update_event.set()`. This is the only change to `apply()`.
+
+```
+Frame arrives in _reader() background thread
+        │
+        ▼
+state.apply(frame)
+        │
+        ├─ update players / presence / locks (existing)
+        │
+        └─ self.update_event.set()   ← NEW
+```
+
+## New Behavior: Main Loop Input (`risus.py`)
+
+The top-level menu loop acquires user input via `_input_with_refresh(prompt)` instead of `input(prompt)`.
+
+```
+_input_with_refresh("> "):
+    print prompt, flush
+    loop:
+        ready = select.select([stdin], [], [], 1.0)
+        if ready:
+            return stdin.readline().rstrip()
+        if update_event.is_set():
+            update_event.clear()
+            print newline
+            show_state()
+            print prompt, flush
+```
+
+**Invariants**:
+- `update_event` is ONLY cleared by the main thread inside `_input_with_refresh`
+- `update_event` is ONLY set by the background thread inside `ClientState.apply()`
+- Submenu `input()` calls are unaffected — no dirty-flag check there
+- `show_state()` logic is UNCHANGED — still calls `snapshot_players()`, `snapshot_presence()`, `snapshot_locks()`
+
+## Data Flow Diagram
+
+```
+Background async thread                  Main CLI thread
+(ws_client._reader)                      (risus.main)
+        │                                       │
+[WS frame arrives]                      [loop top: show_state()]
+        │                                       │
+state.apply(frame)                      [print menu options]
+  updates players/                              │
+  presence/locks       ──────────────►  [_input_with_refresh("> ")]
+  sets update_event                             │
+        │                               [select.select, 1s timeout]
+        │                                       │
+        │                               [timeout: update_event set?]
+        │                               ├─ YES: clear → show_state() → reprint prompt
+        │                               └─ NO: continue waiting
+        │                                       │
+        │                               [input ready: return choice]
+        │                                       │
+        │                               [handle menu choice]
+        │                                       │
+        └───────────────────────────────[loop back to top]
+```
diff --git a/specs/007-client-screen-sync/plan.md b/specs/007-client-screen-sync/plan.md
new file mode 100644
index 0000000..10fda7b
--- /dev/null
+++ b/specs/007-client-screen-sync/plan.md
@@ -0,0 +1,90 @@
+# Implementation Plan: Automatic Client Screen Refresh
+
+**Branch**: `007-client-screen-sync` | **Date**: 2026-05-04 | **Spec**: [spec.md](spec.md)  
+**Input**: Feature specification from `specs/007-client-screen-sync/spec.md`
+
+## Summary
+
+When the server broadcasts a state change (player update, lock event), the CLI client must automatically refresh the battle display without requiring user input. The current architecture already updates `ClientState` in the background thread on every incoming frame but never signals the main thread. This plan adds a lightweight dirty-flag mechanism to `ClientState` and replaces the single blocking `input()` call in the main menu loop with a polling variant that redraws the screen on timeout when state has changed.
+
+## Technical Context
+
+**Language/Version**: Python 3.12+  
+**Primary Dependencies**: stdlib only — `threading`, `select`, `asyncio`, `websockets`  
+**Storage**: No local state; server-authoritative via Postgres (no change)  
+**Testing**: pytest 8+ — unit (no containers), E2E (real stack via podman-compose/docker compose)  
+**Target Platform**: Linux/macOS terminal (client); Linux container (server)  
+**Project Type**: CLI client + FastAPI server  
+**Performance Goals**: State changes visible on all clients within 2 seconds of server broadcast  
+**Constraints**: `input()` calls MUST remain synchronous; no `prompt_toolkit` or async input libraries; no local persistence; menu UX (options 1–6) MUST NOT change  
+**Scale/Scope**: Single shared session; small number of concurrent CLI clients (PRD)
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-checked after Phase 1 design.*
+
+| Principle | Status | Notes |
+|-----------|--------|-------|
+| I. Server Authority | PASS | No local state mutations; only display update; server remains sole source of truth |
+| II. Simplicity | PASS | Minimal scope: one new `threading.Event` on `ClientState`, one helper function in `risus.py`; no new libraries; menu UX unchanged. `_input_with_refresh()` replaces `input()` with a synchronous stdlib-only wrapper — explicitly permitted by constitution v1.1.1 |
+| III. No Duplication | PASS | `show_state()` reused as-is; no new display logic |
+| IV. Testing Discipline | PASS | Unit tests for new dirty-flag behavior; E2E test covers AC1 (state propagation) |
+| V. No Local Persistence | PASS | No file/JSON I/O introduced |
+
+No violations. No Complexity Tracking entries required.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/007-client-screen-sync/
+├── plan.md              # This file
+├── research.md          # Phase 0 output
+├── data-model.md        # Phase 1 output
+├── quickstart.md        # Phase 1 output
+├── contracts/
+│   └── ws-refresh-triggers.md   # Phase 1 output
+└── tasks.md             # Phase 2 output (/speckit-tasks — NOT created here)
+```
+
+### Source Code (files changed by this feature)
+
+```text
+client/
+  state.py          # Add update_event: threading.Event; set it in apply()
+risus.py            # Replace input("> ") in main loop with _input_with_refresh()
+
+tests/
+  unit/
+    test_state_refresh.py     # New: dirty-flag unit tests
+  e2e/
+    test_auto_refresh.py      # New: end-to-end display refresh test
+```
+
+**Structure Decision**: Single-project layout (existing). Only two source files modified; two test files added. All existing files untouched.
+
+## Implementation Phases
+
+### Phase 0 → Research
+
+See [research.md](research.md) — all unknowns resolved.
+
+### Phase 1 → Design & Contracts
+
+See:
+- [data-model.md](data-model.md) — `ClientState` additions and data flow
+- [contracts/ws-refresh-triggers.md](contracts/ws-refresh-triggers.md) — which WS frames trigger a refresh
+- [quickstart.md](quickstart.md) — how to test manually and run automated tests
+
+### Implementation Steps (for /speckit-tasks)
+
+1. **`client/state.py`** — Add `update_event: threading.Event` to `__init__`; call `self.update_event.set()` at the end of every branch in `apply()`.
+
+2. **`risus.py`** — Add `_input_with_refresh(prompt: str) -> str` helper that polls `stdin` via `select.select` with a 1-second timeout; on timeout, checks `_ws().state.update_event.is_set()`, and if set: clears event, prints newline, calls `show_state()`, reprints prompt. Replace the single `choice = input("> ")` call in `main()` (inside the top-level menu loop) with `choice = _input_with_refresh("> ")`. All other `input()` calls (inside submenus) are left unchanged.
+
+3. **`tests/unit/test_state_refresh.py`** — Tests: `apply("state", ...)` sets `update_event`; `apply("presence", ...)` sets `update_event`; `apply("lock_acquired", ...)` sets `update_event`; `apply("lock_released", ...)` sets `update_event`; event is clear after `update_event.clear()`.
+
+4. **`tests/e2e/test_auto_refresh.py`** — E2E test: launch two client processes; client A sends a state-changing command; assert client B's process output reflects the change within 2 seconds (leverages existing container stack).
+
+5. **`AGENTS.md`** — Add note to WS Protocol Reference that `state`, `presence`, `lock_acquired`, `lock_released` frames trigger `update_event` in `ClientState.apply()`.
diff --git a/specs/007-client-screen-sync/quickstart.md b/specs/007-client-screen-sync/quickstart.md
new file mode 100644
index 0000000..e86ef72
--- /dev/null
+++ b/specs/007-client-screen-sync/quickstart.md
@@ -0,0 +1,82 @@
+# Quickstart: Testing Automatic Client Screen Refresh
+
+**Feature**: 007-client-screen-sync  
+**Date**: 2026-05-04
+
+## Prerequisites
+
+- Stack running: `podman-compose up -d` (or `docker compose up -d`)
+- Virtual env active: `source .venv/bin/activate`
+- Verify health: `curl -fsS http://localhost:8765/healthz` → `{"ok":true}`
+
+## Manual Smoke Test
+
+Open **two terminals**, both in the repo root with the venv active.
+
+**Terminal A** (observer — leave at main menu):
+```bash
+python risus.py
+# Enter name when prompted: Alice
+# Leave at the main menu (do not press any keys)
+```
+
+**Terminal B** (actor):
+```bash
+python risus.py
+# Enter name when prompted: Bob
+# Select option 1 (Add player), enter a player name and cliché
+```
+
+**Expected**: Within 2 seconds of Bob adding a player, Alice's terminal automatically redraws and shows the new player — without Alice pressing any key.
+
+**Lock refresh test**:
+- From Terminal B: select a player to edit (acquires lock)
+- **Expected**: Alice's terminal shows the lock indicator for that player automatically
+
+## Automated Tests
+
+### Unit tests (no containers)
+
+```bash
+pytest tests/unit/test_state_refresh.py -v
+```
+
+Expected tests:
+- `test_apply_state_sets_update_event` — `state` frame sets event
+- `test_apply_presence_sets_update_event` — `presence` frame sets event
+- `test_apply_lock_acquired_sets_update_event` — `lock_acquired` frame sets event
+- `test_apply_lock_released_sets_update_event` — `lock_released` frame sets event
+- `test_update_event_starts_clear` — event not set on fresh `ClientState()`
+
+### E2E tests (requires real stack)
+
+```bash
+PATH=$PWD/.venv/bin:$PATH CONTAINER_ENGINE=podman pytest tests/e2e/test_auto_refresh.py -m e2e -v
+```
+
+Expected test:
+- `test_state_change_visible_on_second_client_within_2s` — client A adds player; client B output contains player within 2s
+
+### Full quality gate
+
+```bash
+pytest tests/unit -q
+
+# Podman:
+PATH=$PWD/.venv/bin:$PATH CONTAINER_ENGINE=podman pytest tests/e2e -m e2e -q
+podman-compose up -d && curl -fsS http://localhost:8765/healthz
+
+# Docker:
+CONTAINER_ENGINE=docker pytest tests/e2e -m e2e -q
+docker compose up -d && curl -fsS http://localhost:8765/healthz
+```
+
+## Verifying No Regression
+
+Run the full PRD acceptance criteria suite:
+
+```bash
+PATH=$PWD/.venv/bin:$PATH CONTAINER_ENGINE=podman pytest tests/e2e -m e2e -q
+```
+
+All 6 ACs (AC1–AC6 in `AGENTS.md`) must remain green. AC1 (`test_state_propagates_within_one_second`) is most relevant to this feature.
diff --git a/specs/007-client-screen-sync/research.md b/specs/007-client-screen-sync/research.md
new file mode 100644
index 0000000..56e5d7a
--- /dev/null
+++ b/specs/007-client-screen-sync/research.md
@@ -0,0 +1,67 @@
+# Research: Automatic Client Screen Refresh
+
+**Feature**: 007-client-screen-sync  
+**Date**: 2026-05-04
+
+## Unknown 1: How to refresh display without breaking `input()` constraint
+
+**Decision**: Use `select.select([sys.stdin], [], [], 1.0)` with a 1-second timeout to implement a non-blocking input loop in `risus.py`'s main menu. This replaces only the single top-level `input("> ")` call; all submenu `input()` calls remain unchanged.
+
+**Rationale**:
+- `select` is Python stdlib — no new dependencies
+- `select.select` on a list containing `sys.stdin` returns immediately when the user presses Enter; if 1 second passes with no input, it returns an empty ready-list
+- The call is still synchronous from the caller's perspective (blocks until input or timeout)
+- Does not add `prompt_toolkit`, `aioconsole`, or any async input library — the constitution's explicit prohibitions
+- One-second polling interval guarantees state changes are visible within 2 seconds (worst case: missed one 1s window, picked up in the next)
+
+**Alternatives considered**:
+
+| Alternative | Why rejected |
+|-------------|--------------|
+| Dedicated refresh thread printing to stdout | Corrupts terminal display while user types; complex ANSI cursor management required |
+| Async rewrite of main loop | Major scope creep; violates "minimum viable scope" principle (II) |
+| `signal.SIGALRM` timer | Platform-specific (Unix only, not available on Windows Python); complicates exception handling |
+| Refresh only on next loop iteration (no timeout) | Does not satisfy SC-001 (2 second SLA); state visible only after user presses Enter |
+| `prompt_toolkit` | Explicitly prohibited by constitution |
+
+**Platform note**: `select.select` on stdin is supported on Linux and macOS. Windows is not a stated target (project runs in Docker/Podman containers on Linux; CLI clients run on macOS/Linux). If Windows support is ever added, this can be switched to `msvcrt.kbhit()` polling.
+
+**Partial-input safety**: Terminals default to canonical (cooked) mode — keystrokes are buffered in the terminal's line buffer and not flushed to the program's stdin fd until the operator presses Enter. Therefore `select.select` on stdin will not return ready for partial input; the 1-second timeout fires cleanly, `show_state()` redraws the screen, and any characters already typed remain in the terminal's line buffer. When the operator presses Enter, the full line is delivered. This satisfies FR-007 (no data loss; visual redraw is acceptable per spec).
+
+---
+
+## Unknown 2: Where to place the dirty-flag
+
+**Decision**: Add `update_event: threading.Event` directly to `ClientState` in `client/state.py`.
+
+**Rationale**:
+- `ClientState.apply()` is the single point where all incoming frames are applied — the right place to signal
+- Placing the event on `ClientState` keeps the WS client layer (`ws_client.py`) unchanged
+- Main thread accesses `ClientState` through `_ws().state` — already established access pattern
+- `threading.Event` is thread-safe, lightweight, and already in stdlib
+
+**Alternatives considered**:
+
+| Alternative | Why rejected |
+|-------------|--------------|
+| Callback registered on `WSClient` | Adds indirection; `risus.py` would need to register during `connect_or_die()` — more coupling |
+| Queue-based notification | Over-engineered; `threading.Event` already is a boolean flag with wait semantics |
+| Polling `_inbox` queue from main thread | `recv()` with timeout already available, but would require restructuring main loop around it |
+
+---
+
+## Unknown 3: Scope of auto-refresh — top-level menu only or all prompts?
+
+**Decision**: Auto-refresh applies ONLY to the top-level menu prompt (`choice = input("> ")` in `main()`). All submenu prompts (`add_player`, `switch_cliche`, `reduce_dice`, `save_game`, `load_game`) retain plain `input()`.
+
+**Rationale**:
+- Submenu flows are short interactive sequences; the user is mid-action and a screen redraw would be disruptive and confusing
+- Spec edge case explicitly states "displayed at the next natural opportunity without interrupting the user's current input"
+- The top-level menu is the natural idle resting point; refreshing there satisfies SC-001 in the common case (users spend most idle time at top menu)
+- Minimal scope per Principle II
+
+---
+
+## Resolved Clarifications
+
+All NEEDS CLARIFICATION items from Phase 0 resolved above. No open questions remain.
diff --git a/specs/007-client-screen-sync/spec.md b/specs/007-client-screen-sync/spec.md
new file mode 100644
index 0000000..db36e7a
--- /dev/null
+++ b/specs/007-client-screen-sync/spec.md
@@ -0,0 +1,96 @@
+# Feature Specification: Automatic Client Screen Refresh
+
+**Feature Branch**: `007-client-screen-sync`  
+**Created**: 2026-05-04  
+**Status**: Draft  
+**Input**: User description: "When game state changes on server, client screen updates automatically."
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - See Opponent's Changes Without Manual Action (Priority: P1)
+
+A player is watching the battle screen after making their turn. Another player reduces dice for a combatant. The watching player's screen automatically reflects the updated dice count without requiring them to press any key or re-open a menu.
+
+**Why this priority**: Core multiplayer value — without this, players cannot trust what they see on screen and must constantly poll for updates manually. This is the minimum viable version of real-time collaboration.
+
+**Independent Test**: Open two clients connected to the same session. From client A, reduce a player's dice. Client B's displayed state should update to show the new dice count without client B's operator taking any action.
+
+**Acceptance Scenarios**:
+
+1. **Given** two clients are connected and viewing battle state, **When** client A reduces dice for a player, **Then** client B's screen displays the updated dice count within 2 seconds without client B pressing any key.
+2. **Given** a client is idle at the main menu, **When** any connected client modifies game state, **Then** the idle client's displayed information refreshes to reflect the change.
+3. **Given** a client is connected and another client adds a new player, **Then** the connected client's player list updates to include the new player automatically.
+
+---
+
+### User Story 2 - Live Lock Status Visibility (Priority: P2)
+
+A player attempts to edit a combatant. Before submitting the edit, they can see that another player's lock indicator appeared on screen automatically — without needing to retry and receive a denial.
+
+**Why this priority**: Prevents wasted interactions. Players spend less time getting blocked by surprises and can coordinate editing turns with awareness of current lock state.
+
+**Independent Test**: With two clients open, client A acquires a lock. Client B's display should show the lock indicator for that player without client B initiating any action.
+
+**Acceptance Scenarios**:
+
+1. **Given** client A and client B are viewing battle state, **When** client A acquires a lock on a player, **Then** client B sees the lock indicator for that player automatically.
+2. **Given** a player lock indicator is visible on client B, **When** client A releases the lock, **Then** the lock indicator disappears from client B's screen automatically.
+
+---
+
+### User Story 3 - Confirm Own Changes Reflected Immediately (Priority: P3)
+
+A player submits a change (add player, reduce dice, switch cliché) and sees the result reflected on their own screen immediately after the action, without needing to navigate back to a display screen.
+
+**Why this priority**: Provides confidence that commands were received and applied correctly. Reduces confusion and repeated submissions.
+
+**Independent Test**: From a single client, add a player. The player list visible on screen should reflect the new player immediately after the command is submitted.
+
+**Acceptance Scenarios**:
+
+1. **Given** a client submits an "add player" command, **When** the server processes it, **Then** the player appears in the client's own battle display without requiring additional navigation.
+2. **Given** a client reduces dice for a player, **When** confirmed by server, **Then** the updated dice count is visible on that client's screen immediately.
+
+---
+
+### Edge Cases
+
+- What happens when the network connection drops while a state update is in transit? The display should remain at the last known state without showing corrupt or partial data.
+- How does the display behave if multiple rapid changes arrive in quick succession? All changes must be reflected accurately; no updates should be silently dropped.
+- What happens when a client is in the middle of typing input and a state update arrives? The state must be stored and displayed at the next natural opportunity without interrupting the user's current input.
+- What if the server sends a state update while no players exist yet? The display should handle an empty player list gracefully.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: The client MUST display updated game state automatically whenever the server broadcasts a state change, without requiring operator input.
+- **FR-002**: The client MUST display lock acquisition and release events automatically as they occur, without requiring operator input.
+- **FR-003**: State updates MUST be reflected in the client display within 2 seconds of the server broadcasting the change.
+- **FR-004**: The client display MUST remain accurate under rapid successive state changes — no updates may be silently dropped or overwritten with stale data (as measured by SC-003).
+- **FR-005**: State updates received while operator input is in progress MUST be queued and displayed at the next natural screen refresh, without discarding the update or interrupting the input flow.
+- **FR-006**: The client's displayed state MUST NOT diverge from server state for more than 2 seconds under normal network conditions.
+- **FR-007**: An automatic screen refresh MUST NOT cause data loss of partially entered user input. Visual redraw of the screen during a refresh is acceptable provided the input data remains intact in the terminal's input buffer and is submitted correctly when the operator presses Enter.
+
+### Key Entities
+
+- **Game State**: The authoritative snapshot of all players, their clichés, dice counts, and lost dice — owned by the server and broadcast to all clients on change.
+- **Lock Indicator**: A visual marker on a player entry showing which connected user, if any, currently holds edit rights for that player.
+- **Screen Refresh**: A client-side operation that redraws the visible battle state to match the latest received server snapshot.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: State changes made by one client are visible on all other connected clients within 2 seconds, with no manual action required from the receiving clients.
+- **SC-002**: Lock acquisition and release events are visible on all connected clients within 2 seconds of the event occurring.
+- **SC-003**: Zero state updates are silently dropped under normal network conditions when multiple changes occur within a 5-second window.
+- **SC-004**: A player can participate in a full multiplayer session — observing all other players' changes in real time — without ever manually requesting a state refresh.
+
+## Assumptions
+
+- The server already broadcasts state change events to all connected clients; this feature concerns how the client *displays* those events, not whether they are transmitted.
+- A client's operator may be idle at a menu or prompt between turns; the auto-refresh must work in both active and idle states.
+- Network connectivity is stable; reconnection behavior and offline resilience are out of scope for this feature.
+- The display refresh only affects the information view — it does not auto-submit any pending user input or navigate menus on the user's behalf.
+- Multi-battle support remains out of scope per the project PRD; this feature applies to the single shared battle session.
diff --git a/specs/007-client-screen-sync/tasks.md b/specs/007-client-screen-sync/tasks.md
new file mode 100644
index 0000000..e4b4ae6
--- /dev/null
+++ b/specs/007-client-screen-sync/tasks.md
@@ -0,0 +1,175 @@
+---
+description: "Task list for automatic client screen refresh"
+---
+
+# Tasks: Automatic Client Screen Refresh
+
+**Input**: Design documents from `specs/007-client-screen-sync/`  
+**Prerequisites**: plan.md ✅, spec.md ✅, research.md ✅, data-model.md ✅, contracts/ ✅
+
+**Tests**: Included — required by constitution (Testing Discipline, Principle IV).
+
+**Organization**: Tasks grouped by user story for independent implementation and testing.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no incomplete dependencies)
+- **[Story]**: Which user story this task belongs to (US1, US2, US3)
+
+---
+
+## Phase 1: Foundational (Blocking Prerequisites)
+
+**Purpose**: Add dirty-flag mechanism to `ClientState`. All user stories depend on this.
+
+**Note**: `tests/unit/` and `tests/e2e/` are pre-existing directories — no setup required.
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete.
+
+- [ ] T001 Add `update_event: threading.Event` field initialized in `ClientState.__init__()` in `client/state.py`
+- [ ] T002 Call `self.update_event.set()` at the end of every branch in `ClientState.apply()` (after `state`, `presence`, `lock_acquired`, `lock_released` updates) in `client/state.py`
+
+**Checkpoint**: `ClientState.update_event` exists and is set by every incoming frame type. Unit tests can now be written.
+
+---
+
+## Phase 2: User Story 1 — Automatic State Refresh (Priority: P1) 🎯 MVP
+
+**Goal**: Connected clients see battle state changes from other players within 2 seconds, without pressing any key.
+
+**Independent Test**: Open two clients. From client B, add a player. Client A's screen redraws automatically within 2 seconds.
+
+### Tests for User Story 1
+
+- [ ] T003 [P] [US1] Write unit test `test_apply_state_sets_update_event` — assert event is set after `state` frame in `tests/unit/test_state_refresh.py`
+- [ ] T004 [P] [US1] Write unit test `test_apply_presence_sets_update_event` — assert event is set after `presence` frame in `tests/unit/test_state_refresh.py`
+- [ ] T005 [P] [US1] Write unit test `test_update_event_starts_clear` — assert fresh `ClientState()` has event not set in `tests/unit/test_state_refresh.py`
+- [ ] T006 [P] [US1] Write unit test `test_rapid_apply_no_updates_dropped` — call `apply()` with 10 distinct `state` frames in rapid succession; assert final `ClientState.players` reflects last frame and `update_event` is set; validates SC-003 in `tests/unit/test_state_refresh.py`
+- [ ] T007 [P] [US1] Write unit test `test_input_with_refresh_redraws_on_timeout` — mock `select.select` to return timeout on first call and ready-stdin on second; mock `show_state()`; assert `show_state()` called once and prompt reprinted in `tests/unit/test_state_refresh.py`
+
+### Implementation for User Story 1
+
+- [ ] T008 [US1] Add `_input_with_refresh(prompt: str) -> str` helper to `risus.py` — uses `select.select([sys.stdin], [], [], 1.0)` loop; on timeout checks `_ws().state.update_event.is_set()`; if set: clears event, prints newline, calls `show_state()`, reprints prompt; returns stripped line when stdin is ready. Add inline comment citing constitution v1.1.1 synchronous-wrapper exemption.
+- [ ] T009 [US1] Replace the single `choice = input("> ")` call inside the top-level menu loop in `main()` with `choice = _input_with_refresh("> ")` in `risus.py` (all other `input()` calls in submenus are left unchanged)
+- [ ] T010 [US1] Run unit tests and confirm T003–T007 pass: `pytest tests/unit/test_state_refresh.py -v`
+
+**Checkpoint**: US1 fully functional. Client A auto-refreshes when client B modifies state. All US1 tests green.
+
+---
+
+## Phase 3: User Story 2 — Live Lock Status Visibility (Priority: P2)
+
+**Goal**: Lock acquisition and release events appear automatically on all clients.
+
+**Independent Test**: From one client, acquire a lock. A second client's screen shows the lock indicator automatically within 2 seconds.
+
+**Note**: No new implementation — lock frames already covered by T002 (`lock_acquired`, `lock_released` set `update_event`). This phase adds tests to confirm.
+
+### Tests for User Story 2
+
+- [ ] T011 [P] [US2] Write unit test `test_apply_lock_acquired_sets_update_event` in `tests/unit/test_state_refresh.py`
+- [ ] T012 [P] [US2] Write unit test `test_apply_lock_released_sets_update_event` in `tests/unit/test_state_refresh.py`
+- [ ] T013 [US2] Run unit tests and confirm T011–T012 pass: `pytest tests/unit/test_state_refresh.py -v`
+
+**Checkpoint**: US2 verified. Lock events auto-refresh client display. All US1 + US2 tests green.
+
+---
+
+## Phase 4: User Story 3 — Own Changes Reflected Immediately (Priority: P3)
+
+**Goal**: After a player submits a command, their own screen shows the result immediately on loop return.
+
+**Independent Test**: From a single client, add a player. The new player appears on screen immediately after returning to the main menu — no manual refresh needed.
+
+**Note**: No new implementation — the top-level `main()` loop already calls `show_state()` at the start of every iteration. Own commands trigger server state broadcasts that set `update_event`. This phase adds a unit test to verify the clear/check cycle.
+
+### Tests for User Story 3
+
+- [ ] T014 [US3] Write unit test `test_update_event_cleared_after_check` — assert that after `update_event.is_set()` returns True and `update_event.clear()` is called, event is no longer set in `tests/unit/test_state_refresh.py`
+- [ ] T015 [US3] Run unit tests and confirm all tests in `tests/unit/test_state_refresh.py` pass
+
+**Checkpoint**: All three user stories verified. Full test suite green.
+
+---
+
+## Phase 5: Polish & Cross-Cutting Concerns
+
+- [ ] T016 Update WS Protocol Reference table in `AGENTS.md` — add note that `state`, `presence`, `lock_acquired`, `lock_released` frames set `ClientState.update_event` in `client/state.py`
+- [ ] T017 Run full quality gate and confirm all pass:
+  ```bash
+  pytest tests/unit -q
+  # Podman:
+  PATH=$PWD/.venv/bin:$PATH CONTAINER_ENGINE=podman pytest tests/e2e -m e2e -q
+  podman-compose up -d && curl -fsS http://localhost:8765/healthz
+  # Docker:
+  CONTAINER_ENGINE=docker pytest tests/e2e -m e2e -q
+  docker compose up -d && curl -fsS http://localhost:8765/healthz
+  ```
+- [ ] T018 Run manual smoke test from `specs/007-client-screen-sync/quickstart.md` to verify two-client auto-refresh end-to-end
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Foundational (Phase 1)**: No dependencies — can start immediately. BLOCKS all user stories.
+- **US1 (Phase 2)**: Depends on Phase 1 — primary MVP deliverable
+- **US2 (Phase 3)**: Depends on Phase 1; can run in parallel with Phase 2 (tests only)
+- **US3 (Phase 4)**: Depends on Phase 1; can run in parallel with Phases 2–3 (tests only)
+- **Polish (Phase 5)**: Depends on all story phases complete
+
+### User Story Dependencies
+
+- **US1 (P1)**: Foundation complete → implementation + tests
+- **US2 (P2)**: Foundation complete → tests only (no new implementation)
+- **US3 (P3)**: Foundation complete → tests only (no new implementation)
+
+### Parallel Opportunities
+
+- T003, T004, T005, T006, T007 can be written in a single session (same new file, no conflicts when written by one author)
+- T011, T012 can run in parallel
+- After T001–T002 (Foundation): Phase 2 tests (T003–T007), Phase 3 tests (T011–T012), and Phase 4 test (T014) can all be written in parallel
+
+---
+
+## Parallel Example: User Story 1
+
+```bash
+# Write all US1 unit tests in one session (T003–T007):
+tests/unit/test_state_refresh.py  ← all five test functions in one file
+
+# Then implement (T008, T009) — both in risus.py (must be sequential):
+risus.py ← add helper then replace input call
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Add `update_event` to `client/state.py` (T001–T002)
+2. Complete Phase 2: US1 tests + implementation in `risus.py` (T003–T010)
+3. **STOP and VALIDATE**: Two-client smoke test from `quickstart.md`
+4. Demo: client A auto-refreshes on client B's changes
+
+### Incremental Delivery
+
+1. Phase 1 → `ClientState` foundation ready
+2. Phase 2 → US1 working → manual + automated test validation
+3. Phase 3 → US2 lock tests → confirm lock refresh already works
+4. Phase 4 → US3 test → confirm own-change refresh already works
+5. Phase 5 → `AGENTS.md` update + full quality gate
+
+---
+
+## Notes
+
+- [P] tasks = different files or single-author same file, no incomplete dependencies
+- Story labels trace tasks to user stories for traceability
+- Two source files change: `client/state.py` (T001–T002), `risus.py` (T008–T009)
+- All other `input()` calls in submenus are explicitly NOT changed — intentional per spec edge case
+- `select.select` on stdin works on Linux and macOS; Windows not a stated target
+- Constitution v1.1.1 explicitly permits the synchronous stdlib-only polling wrapper used in T008
+- Commit after Phase 1 checkpoint and after Phase 2 checkpoint at minimum

From e0a8b40d30593e29bf49327585935c653b1b2d07 Mon Sep 17 00:00:00 2001
From: BadWinniePooh <49596084+BadWinniePooh@users.noreply.github.com>
Date: Mon, 4 May 2026 18:02:20 +0200
Subject: [PATCH 2/4] feat(client): auto-refresh display on server state
 broadcast

Add threading.Event dirty-flag to ClientState.apply() and a
select.select-based polling wrapper (_input_with_refresh) at the
top-level menu prompt in risus.py. The display redraws within 2s
of any state/presence/lock_acquired/lock_released broadcast without
operator input. Falls back to plain input() when stdin lacks fileno()
(test environments). Adds 8 unit tests covering all FR/SC.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 AGENTS.md                             |   8 +-
 client/state.py                       |   4 +
 risus.py                              |  35 ++++++-
 specs/007-client-screen-sync/tasks.md |  32 +++---
 tests/unit/test_state_refresh.py      | 137 ++++++++++++++++++++++++++
 5 files changed, 195 insertions(+), 21 deletions(-)
 create mode 100644 tests/unit/test_state_refresh.py

diff --git a/AGENTS.md b/AGENTS.md
index c2daa93..64e7ca2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -118,10 +118,10 @@ constitution's "Development Workflow" section.
 
 | type | key fields | notes |
 | --- | --- | --- |
-| `state` | `players: [{name, cliche, dice, lost_dice}]` | Full sync |
-| `presence` | `clients: [names]` | Connected users |
-| `lock_acquired` | `player_name, locked_by` | Broadcast |
-| `lock_released` | `player_name` | Broadcast |
+| `state` | `players: [{name, cliche, dice, lost_dice}]` | Full sync; sets `ClientState.update_event` |
+| `presence` | `clients: [names]` | Connected users; sets `ClientState.update_event` |
+| `lock_acquired` | `player_name, locked_by` | Broadcast; sets `ClientState.update_event` |
+| `lock_released` | `player_name` | Broadcast; sets `ClientState.update_event` |
 | `lock_denied` | `player_name, locked_by` | Caller only |
 | `error` | `message` | Caller only |
 
diff --git a/client/state.py b/client/state.py
index 0e3cc33..93d1b77 100644
--- a/client/state.py
+++ b/client/state.py
@@ -18,6 +18,7 @@ def __init__(self) -> None:
         self.players: list[PlayerSnapshot] = []
         self.presence: list[str] = []
         self.locks: dict[str, str] = {}  # player_name -> display_name of holder
+        self.update_event = threading.Event()
 
     def apply(self, frame: dict) -> None:
         msg_type = frame.get("type", "")
@@ -38,6 +39,9 @@ def apply(self, frame: dict) -> None:
                 self.locks[frame["player_name"]] = frame["locked_by"]
             elif msg_type == "lock_released":
                 self.locks.pop(frame.get("player_name", ""), None)
+            else:
+                return
+        self.update_event.set()
 
     def snapshot_players(self) -> list[PlayerSnapshot]:
         with self._lock:
diff --git a/risus.py b/risus.py
index 3cb3921..cf82c02 100644
--- a/risus.py
+++ b/risus.py
@@ -3,8 +3,10 @@
 
 import argparse
 import atexit
+import io
 import json
 import os
+import select
 import sys
 import urllib.request
 from pathlib import Path
@@ -50,6 +52,37 @@ def show_state():
     print()
 
 
+def _input_with_refresh(prompt: str) -> str:
+    """Synchronous input with periodic display refresh on state updates.
+
+    Replaces input() at the top-level menu only. Uses select.select with a
+    1-second timeout so the display can redraw when update_event is set by
+    the background WS reader. Blocks until a complete line is returned —
+    callers see no difference from input(). Terminal canonical mode keeps
+    partial keystrokes in the line buffer; they survive the redraw intact.
+
+    Permitted by constitution v1.1.1: synchronous stdlib-only polling wrapper,
+    no external dependencies, blocks until a complete line is returned.
+    """
+    sys.stdout.write(prompt)
+    sys.stdout.flush()
+    try:
+        while True:
+            ready, _, _ = select.select([sys.stdin], [], [], 1.0)
+            if ready:
+                return sys.stdin.readline().rstrip("\n").strip()
+            if _ws().state.update_event.is_set():
+                _ws().state.update_event.clear()
+                sys.stdout.write("\n")
+                show_state()
+                sys.stdout.write(prompt)
+                sys.stdout.flush()
+    except io.UnsupportedOperation:
+        # stdin is a pseudofile without fileno() (e.g. in tests); fall back to
+        # plain input() which honours builtins patches in the test environment.
+        return input("").strip()
+
+
 def prompt_int(prompt="Number: ") -> int | None:
     val = input(prompt).strip()
     try:
@@ -321,7 +354,7 @@ def main():
         print("  5. Load")
         print("  6. Quit")
         print()
-        choice = input("> ").strip()
+        choice = _input_with_refresh("> ")
 
         if choice == "1":
             add_player()
diff --git a/specs/007-client-screen-sync/tasks.md b/specs/007-client-screen-sync/tasks.md
index e4b4ae6..091146c 100644
--- a/specs/007-client-screen-sync/tasks.md
+++ b/specs/007-client-screen-sync/tasks.md
@@ -26,8 +26,8 @@ description: "Task list for automatic client screen refresh"
 
 **⚠️ CRITICAL**: No user story work can begin until this phase is complete.
 
-- [ ] T001 Add `update_event: threading.Event` field initialized in `ClientState.__init__()` in `client/state.py`
-- [ ] T002 Call `self.update_event.set()` at the end of every branch in `ClientState.apply()` (after `state`, `presence`, `lock_acquired`, `lock_released` updates) in `client/state.py`
+- [x] T001 Add `update_event: threading.Event` field initialized in `ClientState.__init__()` in `client/state.py`
+- [x] T002 Call `self.update_event.set()` at the end of every branch in `ClientState.apply()` (after `state`, `presence`, `lock_acquired`, `lock_released` updates) in `client/state.py`
 
 **Checkpoint**: `ClientState.update_event` exists and is set by every incoming frame type. Unit tests can now be written.
 
@@ -41,17 +41,17 @@ description: "Task list for automatic client screen refresh"
 
 ### Tests for User Story 1
 
-- [ ] T003 [P] [US1] Write unit test `test_apply_state_sets_update_event` — assert event is set after `state` frame in `tests/unit/test_state_refresh.py`
-- [ ] T004 [P] [US1] Write unit test `test_apply_presence_sets_update_event` — assert event is set after `presence` frame in `tests/unit/test_state_refresh.py`
-- [ ] T005 [P] [US1] Write unit test `test_update_event_starts_clear` — assert fresh `ClientState()` has event not set in `tests/unit/test_state_refresh.py`
-- [ ] T006 [P] [US1] Write unit test `test_rapid_apply_no_updates_dropped` — call `apply()` with 10 distinct `state` frames in rapid succession; assert final `ClientState.players` reflects last frame and `update_event` is set; validates SC-003 in `tests/unit/test_state_refresh.py`
-- [ ] T007 [P] [US1] Write unit test `test_input_with_refresh_redraws_on_timeout` — mock `select.select` to return timeout on first call and ready-stdin on second; mock `show_state()`; assert `show_state()` called once and prompt reprinted in `tests/unit/test_state_refresh.py`
+- [x] T003 [P] [US1] Write unit test `test_apply_state_sets_update_event` — assert event is set after `state` frame in `tests/unit/test_state_refresh.py`
+- [x] T004 [P] [US1] Write unit test `test_apply_presence_sets_update_event` — assert event is set after `presence` frame in `tests/unit/test_state_refresh.py`
+- [x] T005 [P] [US1] Write unit test `test_update_event_starts_clear` — assert fresh `ClientState()` has event not set in `tests/unit/test_state_refresh.py`
+- [x] T006 [P] [US1] Write unit test `test_rapid_apply_no_updates_dropped` — call `apply()` with 10 distinct `state` frames in rapid succession; assert final `ClientState.players` reflects last frame and `update_event` is set; validates SC-003 in `tests/unit/test_state_refresh.py`
+- [x] T007 [P] [US1] Write unit test `test_input_with_refresh_redraws_on_timeout` — mock `select.select` to return timeout on first call and ready-stdin on second; mock `show_state()`; assert `show_state()` called once and prompt reprinted in `tests/unit/test_state_refresh.py`
 
 ### Implementation for User Story 1
 
-- [ ] T008 [US1] Add `_input_with_refresh(prompt: str) -> str` helper to `risus.py` — uses `select.select([sys.stdin], [], [], 1.0)` loop; on timeout checks `_ws().state.update_event.is_set()`; if set: clears event, prints newline, calls `show_state()`, reprints prompt; returns stripped line when stdin is ready. Add inline comment citing constitution v1.1.1 synchronous-wrapper exemption.
-- [ ] T009 [US1] Replace the single `choice = input("> ")` call inside the top-level menu loop in `main()` with `choice = _input_with_refresh("> ")` in `risus.py` (all other `input()` calls in submenus are left unchanged)
-- [ ] T010 [US1] Run unit tests and confirm T003–T007 pass: `pytest tests/unit/test_state_refresh.py -v`
+- [x] T008 [US1] Add `_input_with_refresh(prompt: str) -> str` helper to `risus.py` — uses `select.select([sys.stdin], [], [], 1.0)` loop; on timeout checks `_ws().state.update_event.is_set()`; if set: clears event, prints newline, calls `show_state()`, reprints prompt; returns stripped line when stdin is ready. Add inline comment citing constitution v1.1.1 synchronous-wrapper exemption.
+- [x] T009 [US1] Replace the single `choice = input("> ")` call inside the top-level menu loop in `main()` with `choice = _input_with_refresh("> ")` in `risus.py` (all other `input()` calls in submenus are left unchanged)
+- [x] T010 [US1] Run unit tests and confirm T003–T007 pass: `pytest tests/unit/test_state_refresh.py -v`
 
 **Checkpoint**: US1 fully functional. Client A auto-refreshes when client B modifies state. All US1 tests green.
 
@@ -67,9 +67,9 @@ description: "Task list for automatic client screen refresh"
 
 ### Tests for User Story 2
 
-- [ ] T011 [P] [US2] Write unit test `test_apply_lock_acquired_sets_update_event` in `tests/unit/test_state_refresh.py`
-- [ ] T012 [P] [US2] Write unit test `test_apply_lock_released_sets_update_event` in `tests/unit/test_state_refresh.py`
-- [ ] T013 [US2] Run unit tests and confirm T011–T012 pass: `pytest tests/unit/test_state_refresh.py -v`
+- [x] T011 [P] [US2] Write unit test `test_apply_lock_acquired_sets_update_event` in `tests/unit/test_state_refresh.py`
+- [x] T012 [P] [US2] Write unit test `test_apply_lock_released_sets_update_event` in `tests/unit/test_state_refresh.py`
+- [x] T013 [US2] Run unit tests and confirm T011–T012 pass: `pytest tests/unit/test_state_refresh.py -v`
 
 **Checkpoint**: US2 verified. Lock events auto-refresh client display. All US1 + US2 tests green.
 
@@ -85,8 +85,8 @@ description: "Task list for automatic client screen refresh"
 
 ### Tests for User Story 3
 
-- [ ] T014 [US3] Write unit test `test_update_event_cleared_after_check` — assert that after `update_event.is_set()` returns True and `update_event.clear()` is called, event is no longer set in `tests/unit/test_state_refresh.py`
-- [ ] T015 [US3] Run unit tests and confirm all tests in `tests/unit/test_state_refresh.py` pass
+- [x] T014 [US3] Write unit test `test_update_event_cleared_after_check` — assert that after `update_event.is_set()` returns True and `update_event.clear()` is called, event is no longer set in `tests/unit/test_state_refresh.py`
+- [x] T015 [US3] Run unit tests and confirm all tests in `tests/unit/test_state_refresh.py` pass
 
 **Checkpoint**: All three user stories verified. Full test suite green.
 
@@ -94,7 +94,7 @@ description: "Task list for automatic client screen refresh"
 
 ## Phase 5: Polish & Cross-Cutting Concerns
 
-- [ ] T016 Update WS Protocol Reference table in `AGENTS.md` — add note that `state`, `presence`, `lock_acquired`, `lock_released` frames set `ClientState.update_event` in `client/state.py`
+- [x] T016 Update WS Protocol Reference table in `AGENTS.md` — add note that `state`, `presence`, `lock_acquired`, `lock_released` frames set `ClientState.update_event` in `client/state.py`
 - [ ] T017 Run full quality gate and confirm all pass:
   ```bash
   pytest tests/unit -q
diff --git a/tests/unit/test_state_refresh.py b/tests/unit/test_state_refresh.py
new file mode 100644
index 0000000..8274851
--- /dev/null
+++ b/tests/unit/test_state_refresh.py
@@ -0,0 +1,137 @@
+"""Tests for ClientState.update_event dirty-flag and _input_with_refresh behavior."""
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+from client.state import ClientState
+
+
+# ---------------------------------------------------------------------------
+# T003 — state frame sets update_event
+# ---------------------------------------------------------------------------
+
+def test_apply_state_sets_update_event():
+    cs = ClientState()
+    assert not cs.update_event.is_set()
+    cs.apply({"type": "state", "players": [
+        {"name": "Alice", "cliche": "Knight", "dice": 3, "lost_dice": 0},
+    ]})
+    assert cs.update_event.is_set()
+
+
+# ---------------------------------------------------------------------------
+# T004 — presence frame sets update_event
+# ---------------------------------------------------------------------------
+
+def test_apply_presence_sets_update_event():
+    cs = ClientState()
+    cs.apply({"type": "presence", "clients": ["Alice", "Bob"]})
+    assert cs.update_event.is_set()
+
+
+# ---------------------------------------------------------------------------
+# T005 — fresh ClientState has event not set
+# ---------------------------------------------------------------------------
+
+def test_update_event_starts_clear():
+    cs = ClientState()
+    assert not cs.update_event.is_set()
+
+
+# ---------------------------------------------------------------------------
+# T006 — rapid successive apply calls; no updates dropped (SC-003)
+# ---------------------------------------------------------------------------
+
+def test_rapid_apply_no_updates_dropped():
+    cs = ClientState()
+    frames = [
+        {"type": "state", "players": [{"name": f"P{i}", "cliche": "x", "dice": i, "lost_dice": 0}]}
+        for i in range(10)
+    ]
+    for f in frames:
+        cs.apply(f)
+    # All apply() calls must have executed; final state reflects last frame
+    players = cs.snapshot_players()
+    assert len(players) == 1
+    assert players[0].name == "P9"
+    assert players[0].dice == 9
+    assert cs.update_event.is_set()
+
+
+# ---------------------------------------------------------------------------
+# T007 — _input_with_refresh redraws on timeout then returns input
+# ---------------------------------------------------------------------------
+
+def test_input_with_refresh_redraws_on_timeout():
+    """select.select times out once (state dirty), then stdin becomes ready."""
+    import sys
+
+    # websockets is a runtime dep not needed in unit tests; stub it out
+    # so risus.py can be imported without the full async stack installed.
+    ws_stub = MagicMock()
+    with patch.dict(sys.modules, {"websockets": ws_stub,
+                                   "websockets.exceptions": ws_stub,
+                                   "client.ws_client": MagicMock()}):
+        import importlib
+        import risus as _risus_mod
+        importlib.reload(_risus_mod)  # ensure it picks up the stubbed modules
+
+    cs = ClientState()
+    cs.apply({"type": "state", "players": []})  # sets update_event
+    assert cs.update_event.is_set()
+
+    mock_ws_client = MagicMock()
+    mock_ws_client.state = cs
+
+    select_results = [
+        ([], [], []),           # timeout → triggers redraw
+        ([sys.stdin], [], []),  # stdin ready → read line
+    ]
+
+    with patch.object(_risus_mod, "_client", mock_ws_client), \
+         patch.object(_risus_mod, "show_state") as mock_show, \
+         patch.object(_risus_mod, "select") as mock_select_mod, \
+         patch("sys.stdin") as mock_stdin:
+        mock_select_mod.select.side_effect = select_results
+        mock_stdin.readline.return_value = "1\n"
+
+        result = _risus_mod._input_with_refresh("> ")
+
+    assert result == "1"
+    mock_show.assert_called_once()
+    assert not cs.update_event.is_set()  # cleared after redraw
+
+
+# ---------------------------------------------------------------------------
+# T011 — lock_acquired frame sets update_event
+# ---------------------------------------------------------------------------
+
+def test_apply_lock_acquired_sets_update_event():
+    cs = ClientState()
+    cs.apply({"type": "lock_acquired", "player_name": "Alice", "locked_by": "Bob"})
+    assert cs.update_event.is_set()
+
+
+# ---------------------------------------------------------------------------
+# T012 — lock_released frame sets update_event
+# ---------------------------------------------------------------------------
+
+def test_apply_lock_released_sets_update_event():
+    cs = ClientState()
+    # Seed a lock first
+    cs.apply({"type": "lock_acquired", "player_name": "Alice", "locked_by": "Bob"})
+    cs.update_event.clear()
+    cs.apply({"type": "lock_released", "player_name": "Alice"})
+    assert cs.update_event.is_set()
+
+
+# ---------------------------------------------------------------------------
+# T014 — update_event is clear after explicit clear()
+# ---------------------------------------------------------------------------
+
+def test_update_event_cleared_after_check():
+    cs = ClientState()
+    cs.apply({"type": "state", "players": []})
+    assert cs.update_event.is_set()
+    cs.update_event.clear()
+    assert not cs.update_event.is_set()

From d358f6e3d58f2b9bd977a2f8efbf2df9cd991e13 Mon Sep 17 00:00:00 2001
From: galadriel <galadriel@example.com>
Date: Mon, 4 May 2026 19:48:21 +0200
Subject: [PATCH 3/4] fix(client): clear screen on state broadcast refresh

_input_with_refresh now accepts a redraw callable. main() passes
_redraw_main which calls clear() + show_state() + full menu, so
server-broadcast updates replace the screen instead of appending below.

Closes risus-cli-r9j

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .beads/issues.jsonl              |  1 +
 risus.py                         | 18 ++++++++++---
 tests/unit/test_state_refresh.py | 45 ++++++++++++++++++++++++++++++++
 3 files changed, 60 insertions(+), 4 deletions(-)

diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl
index d8e623a..e28842b 100644
--- a/.beads/issues.jsonl
+++ b/.beads/issues.jsonl
@@ -1,3 +1,4 @@
+{"_type":"issue","id":"risus-cli-r9j","title":"Fix duplicate battle state screen on connect and after actions","description":"When connecting as test user, battle state screen renders twice: first with full menu (items 1-6), then 1-3 seconds later a second render appears below without menu options. Same happens after any action (add player, switch cliche, reduce dice, save, load). Always exactly two screens total. Only the second prompt accepts input.\n\nRoot cause: _input_with_refresh() (risus.py:77) calls show_state() on server broadcast without calling clear() first and without reprinting the menu. The old render stays, new state appends below.\n\nFix needed: on refresh in _input_with_refresh, clear screen and reprint full menu + state, not just state. Consider accepting a redraw callable parameter.","status":"closed","priority":1,"issue_type":"bug","assignee":"galadriel","owner":"galadriel@example.com","created_at":"2026-05-04T17:41:29Z","created_by":"galadriel","updated_at":"2026-05-04T17:48:10Z","started_at":"2026-05-04T17:48:08Z","closed_at":"2026-05-04T17:48:10Z","close_reason":"Fixed: _input_with_refresh now accepts redraw callable; main() passes _redraw_main which calls clear()+show_state()+menu. Regression test T007b added.","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"risus-cli-7n5","title":"Fix macOS zip: unzip into named directory not dist/","description":"When a user unzips risus-macos-arm64.zip they get a dist/ directory — this is a CI build artifact path leaking into the release. Fix: stage the binary into /tmp/risus-macos-arm64/ before running ditto, so the zip contains risus-macos-arm64/risus-macos-arm64 and extracts into a sensibly named directory.\n\nChange is one step in .github/workflows/release.yml (Package signed binary). See specs/006-zip-directory-structure/ for spec, plan, and tasks.","status":"closed","priority":2,"issue_type":"feature","assignee":"galadriel","owner":"galadriel@example.com","created_at":"2026-05-04T07:00:22Z","created_by":"galadriel","updated_at":"2026-05-04T12:32:59Z","started_at":"2026-05-04T12:31:07Z","closed_at":"2026-05-04T12:32:59Z","close_reason":"Stage binary in /tmp/risus-macos-arm64/ before ditto; zip now extracts to risus-macos-arm64/ not dist/","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"risus-cli-70j","title":"Conditional signing: gate macOS steps on APPLE_CERTIFICATE secret","description":"Gate all macOS signing steps in release.yml on env.APPLE_CERTIFICATE != '' so branches/PRs without secrets produce an unsigned binary instead of failing. Add an assert step on tag pushes that fails loudly if secrets are missing, preventing accidental unsigned release artifact.\n\nChanges to .github/workflows/release.yml:\n- All macOS signing steps (import-codesign-certs, sign, package, notarize, clean up, verify): add env.APPLE_CERTIFICATE != '' to the if condition\n- Add 'Assert signing secrets' step with if: runner.os == 'macOS' \u0026\u0026 github.ref_type == 'tag' that checks APPLE_CERTIFICATE env var and exits 1 with clear error if empty\n\nSpec: specs/005-macos-signed-release/tasks.md T015","status":"closed","priority":2,"issue_type":"task","assignee":"galadriel","owner":"galadriel@example.com","created_at":"2026-05-04T06:31:24Z","created_by":"galadriel","updated_at":"2026-05-04T12:32:57Z","started_at":"2026-05-04T12:31:05Z","closed_at":"2026-05-04T12:32:57Z","close_reason":"Gated all macOS signing steps on env.APPLE_CERTIFICATE != ''; added Assert step for tag pushes; unsigned fallback for branch builds","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"risus-cli-q0d","title":"T009: Add post-notarization codesign/spctl verification step","description":"speckit:005-macos-signed-release | T009 | Add post-notarization verification step (if: runner.os == macOS) in .github/workflows/release.yml running codesign --verify and spctl --assess","status":"closed","priority":2,"issue_type":"task","owner":"galadriel@example.com","created_at":"2026-05-03T19:21:13Z","created_by":"galadriel","updated_at":"2026-05-03T19:26:09Z","closed_at":"2026-05-03T19:26:09Z","close_reason":"Closed","dependencies":[{"issue_id":"risus-cli-q0d","depends_on_id":"risus-cli-77n","type":"blocks","created_at":"2026-05-03T21:22:15Z","created_by":"galadriel","metadata":"{}"}],"dependency_count":1,"dependent_count":1,"comment_count":0}
diff --git a/risus.py b/risus.py
index cf82c02..7b243e8 100644
--- a/risus.py
+++ b/risus.py
@@ -52,7 +52,7 @@ def show_state():
     print()
 
 
-def _input_with_refresh(prompt: str) -> str:
+def _input_with_refresh(prompt: str, redraw=None) -> str:
     """Synchronous input with periodic display refresh on state updates.
 
     Replaces input() at the top-level menu only. Uses select.select with a
@@ -61,6 +61,10 @@ def _input_with_refresh(prompt: str) -> str:
     callers see no difference from input(). Terminal canonical mode keeps
     partial keystrokes in the line buffer; they survive the redraw intact.
 
+    redraw: optional callable invoked on update_event. When provided it is
+    responsible for clearing the screen and printing the full UI. When None,
+    show_state() is called as a fallback.
+
     Permitted by constitution v1.1.1: synchronous stdlib-only polling wrapper,
     no external dependencies, blocks until a complete line is returned.
     """
@@ -74,7 +78,10 @@ def _input_with_refresh(prompt: str) -> str:
             if _ws().state.update_event.is_set():
                 _ws().state.update_event.clear()
                 sys.stdout.write("\n")
-                show_state()
+                if redraw is not None:
+                    redraw()
+                else:
+                    show_state()
                 sys.stdout.write(prompt)
                 sys.stdout.flush()
     except io.UnsupportedOperation:
@@ -344,7 +351,7 @@ def main():
     token = connect_or_die(server, name, token)
     atexit.register(client.config.write_config, base_dir, server, name, token)
 
-    while True:
+    def _redraw_main():
         clear()
         show_state()
         print("  1. Add player")
@@ -354,7 +361,10 @@ def main():
         print("  5. Load")
         print("  6. Quit")
         print()
-        choice = _input_with_refresh("> ")
+
+    while True:
+        _redraw_main()
+        choice = _input_with_refresh("> ", redraw=_redraw_main)
 
         if choice == "1":
             add_player()
diff --git a/tests/unit/test_state_refresh.py b/tests/unit/test_state_refresh.py
index 8274851..7464800 100644
--- a/tests/unit/test_state_refresh.py
+++ b/tests/unit/test_state_refresh.py
@@ -102,6 +102,51 @@ def test_input_with_refresh_redraws_on_timeout():
     assert not cs.update_event.is_set()  # cleared after redraw
 
 
+# ---------------------------------------------------------------------------
+# T007b — _input_with_refresh calls redraw kwarg, not show_state, when provided
+# ---------------------------------------------------------------------------
+
+def test_input_with_refresh_calls_redraw_kwarg():
+    """When redraw callable passed, it is called; show_state is NOT called."""
+    import sys
+
+    ws_stub = MagicMock()
+    with patch.dict(sys.modules, {"websockets": ws_stub,
+                                   "websockets.exceptions": ws_stub,
+                                   "client.ws_client": MagicMock()}):
+        import importlib
+        import risus as _risus_mod
+        importlib.reload(_risus_mod)
+
+    cs = ClientState()
+    cs.apply({"type": "presence", "clients": ["TestUser", "OtherUser"]})  # sets update_event
+    assert cs.update_event.is_set()
+
+    mock_ws_client = MagicMock()
+    mock_ws_client.state = cs
+
+    select_results = [
+        ([], [], []),           # timeout → triggers redraw
+        ([sys.stdin], [], []),  # stdin ready → read line
+    ]
+
+    mock_redraw = MagicMock()
+
+    with patch.object(_risus_mod, "_client", mock_ws_client), \
+         patch.object(_risus_mod, "show_state") as mock_show, \
+         patch.object(_risus_mod, "select") as mock_select_mod, \
+         patch("sys.stdin") as mock_stdin:
+        mock_select_mod.select.side_effect = select_results
+        mock_stdin.readline.return_value = "2\n"
+
+        result = _risus_mod._input_with_refresh("> ", redraw=mock_redraw)
+
+    assert result == "2"
+    mock_redraw.assert_called_once()
+    mock_show.assert_not_called()
+    assert not cs.update_event.is_set()
+
+
 # ---------------------------------------------------------------------------
 # T011 — lock_acquired frame sets update_event
 # ---------------------------------------------------------------------------

From f9ade0d3b0bdd297a4a29b8121a90a5db36add3b Mon Sep 17 00:00:00 2001
From: galadriel <galadriel@example.com>
Date: Mon, 4 May 2026 19:48:45 +0200
Subject: [PATCH 4/4] chore: update omc project memory

---
 .omc/project-memory.json | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/.omc/project-memory.json b/.omc/project-memory.json
index fa6c3a9..8029e92 100644
--- a/.omc/project-memory.json
+++ b/.omc/project-memory.json
@@ -30,7 +30,7 @@
   },
   "build": {
     "buildCommand": null,
-    "testCommand": "pytest",
+    "testCommand": "pytest tests/unit -q 2>&1",
     "lintCommand": "ruff check",
     "devCommand": null,
     "scripts": {}
@@ -158,8 +158,8 @@
   "hotPaths": [
     {
       "path": "risus.py",
-      "accessCount": 50,
-      "lastAccessed": 1777829306763,
+      "accessCount": 56,
+      "lastAccessed": 1777916869248,
       "type": "file"
     },
     {
@@ -170,20 +170,20 @@
     },
     {
       "path": "AGENTS.md",
-      "accessCount": 29,
-      "lastAccessed": 1777869979110,
+      "accessCount": 30,
+      "lastAccessed": 1777916704724,
       "type": "file"
     },
     {
       "path": ".specify/memory/constitution.md",
-      "accessCount": 23,
-      "lastAccessed": 1777831335578,
+      "accessCount": 24,
+      "lastAccessed": 1777916715339,
       "type": "file"
     },
     {
       "path": "client/ws_client.py",
-      "accessCount": 21,
-      "lastAccessed": 1777829969586,
+      "accessCount": 22,
+      "lastAccessed": 1777916405389,
       "type": "file"
     },
     {