docs(termtris): re-run acceptance at the VR319 default

The branch's evidence was captured on an older MAME binary whose frames
were VR150 (1024x864).  Rebuild MAME from this tree's driver and re-run
verify.sh --skip-mame at the VR319 default (1280x1024 active).

All six tests pass.  Event counts, focus=00400001, tick=887 and quit=1
are unchanged; only the main-loop counts moved with the frame cadence:
move 650, panels 648, quit 555 (was 354/346/300).  The evidence PNGs are
regenerated at 1280x1024.  Record the numbers and the geometry change in
VT1200.md, TERMTRIS_REPORT.md and HANDOFF.md, and note the qemu-i386
toolchain fallback.

apps/termtris/HANDOFF.md

@@ -36,39 +36,32 @@ high-score panels, moving/rotating/dropping pieces, and `q` to quit.
 | game integration, scores, COFF | done, `play.sh`/`play_keys.sh` PASS | `41d3cec` |
 | docs + harness report | done | `3e2ddde` |
 | review pass (seed, focus, expose, assertions) | done | `7a2cef5` |
-| handoff script + this note | done | (this commit) |
+| handoff script + this note | done | `a12fb47` |
+| qemu-i386 fallback for kernels without 16-bit LDT | done, `verify.sh` PASS | `ce40582` |
+| VR319 re-run, regenerated evidence, updated numbers | done, `verify.sh` PASS | (this commit) |
 
 `VT1200.md` is the port documentation; `harness/mame/TERMTRIS_REPORT.md` is the
 harness-side report; the design and plan are in
 `docs/superpowers/specs/2026-11-03-termtris-vt1200-design.md` and
 `docs/superpowers/plans/2026-11-03-termtris-vt1200.md`.
 
-## What is *not* done yet — read this first
+## The VR319 re-run — done
 
-All screenshots and the acceptance numbers in the docs were produced with an
-**older MAME binary** (`/home/arti/code/k-space/mame0289/vt1200d`, 30 Oct) that
-predates the driver's VR319 default. That binary has no `VT1200_MONITOR`, and
-its frames are 1024×864, i.e. the old VR150 geometry. The driver in this tree
-defaults to **VR319** (1280×1024 active, 1696×1063 raster), which changes the
-frame cadence and therefore the frame at which the loader and the tests act.
+The screenshots and the acceptance numbers used to come from an **older MAME
+binary** (`/home/arti/code/k-space/mame0289/vt1200d`, 30 Oct) that predates the
+driver's VR319 default. That binary has no `VT1200_MONITOR`, and its frames are
+1024×864, i.e. the old VR150 geometry. The driver in this tree defaults to
+**VR319** (1280×1024 active, 1696×1063 raster), which changes the frame cadence
+and therefore the frame at which the loader and the tests act.
 
-So on the new box, after `harness/mame/build.sh`:
-
-1. Re-run `apps/termtris/verify.sh --skip-mame` and note the new
-   `DIAG: loops=... events=... quit=...` values.
-2. Re-capture the screenshots (the test scripts write them into
-   `apps/termtris/evidence/`) and look at them: the board must still be a
-   bordered well with `[`/`]` tetrominoes, the score/level/lines boxes on the
-   right, and the preview box. The window is positioned at (80,80) inside a
-   larger raster, so the PNGs get bigger but the window content is unchanged.
-3. Update the numbers in `VT1200.md` ("Acceptance values") and in
-   `harness/mame/TERMTRIS_REPORT.md`, and say plainly that the earlier figures
-   were VR150.
-
-If the behaviour itself changes at VR319 (pieces not visible, no events), that
-is a real finding, not a formatting detail — the loader acts at frame 2500 and
-the keys at 3100–3290, which may need re-timing if the new raster shifts the
-frame budget.
+The branch has now been re-run against a fresh MAME 0.289 build of this tree's
+driver at the VR319 default. `apps/termtris/verify.sh --skip-mame` passes all
+six tests, the evidence PNGs were regenerated at **1280×1024**, and the new
+`DIAG` values are in `VT1200.md` and `harness/mame/TERMTRIS_REPORT.md`. The
+behaviour did not change: same events, same window (`focus=00400001`), same
+`quit=1`, board/panels/preview all visible. Only the loop counts moved, because
+the VR319 raster runs at a different emulated frame rate. The loader still acts
+at frame 2500 and the keys at 3095–3190; no re-timing was needed.
 
 ## Prerequisites on the new box
 
@@ -79,13 +72,21 @@ frame budget.
   `tools/tms34010-sdk/1990-11 TMS340 Family SDK/`;
 * `vt1200_v22.bin` in the repo root (the harness ROM dir symlinks to it).
 
+The r5.01 tools are 16-bit OS/2 `NE` programs. If the host kernel was built
+without `CONFIG_X86_16BIT`, `lx_loader` cannot create their 16-bit LDT
+segments and aborts at its first one; `build.sh` detects that and runs the same
+loader under `qemu-i386` (install `qemu-user`), or honours an explicit
+`LX_RUNNER=`. This box's cloud kernel is one of those; the generated COFF is
+unchanged.
+
 `verify.sh` checks the ROM and the 2ine loader before doing anything, and
 `harness/mame/build.sh` re-registers the driver in `mame.lst` and builds the
 single-driver `vt1200` subtarget.
 
 ## Expected results
 
-Last run here (older MAME, VR150 geometry):
+Last full run (MAME 0.289, this tree's driver, **VR319 default**, 1280×1024
+frames; the earlier figures were VR150):
 
 ```
 smoke    PASS   type=2 keycode=194 lookup_n=1 ch=61 ks=0061
@@ -94,9 +95,9 @@ render   PASS   flus=464C5553 progress=00FFFFFF
 input    PASS   bytes 61 9B 41 9B 42 9B 44 9B 43 30 0A 7F 71 70
                 (a/up/down/left/right/0/Return/Delete/q/p)
 play     PASS   DIAG: tick=887 quit=0
-play_keys PASS  move   DIAG: loops=354 events=18 focus=00400001 quit=0
-                panels DIAG: loops=346 events=12 focus=00400001 quit=0
-                quit   DIAG: loops=300 events=10 focus=00400001 quit=1
+play_keys PASS  move   DIAG: loops=650 events=18 last=3 focus=00400001 rev=0 quit=0
+                panels DIAG: loops=648 events=12 last=3 focus=00400001 rev=0 quit=0
+                quit   DIAG: loops=555 events=10 last=3 focus=00400001 rev=0 quit=1
 ```
 
 `focus=00400001` is the window the process created; `quit=1` is the game's own

apps/termtris/VT1200.md

@@ -36,6 +36,16 @@ The 2ine-hosted tools routinely segfault *after* producing their output, so the
 script treats an output file as success and retries a missing one; `gspac` needs
 `-i.` for the angle-bracket shim headers.
 
+The r5.01 programs are 16-bit OS/2 `NE` executables. `lx_loader` is 32-bit but
+maps them through 16-bit LDT segments, and a Linux kernel built without
+`CONFIG_X86_16BIT` rejects those (`modify_ldt` returns `EINVAL`) — the loader
+then aborts at its first segment even though it starts. On such a host
+`build.sh` probes for that failure and runs the same loader through
+`qemu-i386`, whose linux-user `modify_ldt` does implement 16-bit segments. Set
+`LX_RUNNER=qemu-i386` to force a runner, or install `qemu-user` so the fallback
+is available. The generated COFF is unchanged; only its header timestamp
+differs between builds.
+
 Link map (relevant addresses are **bit** addresses, like everything the
 TMS34010 sees):
 
@@ -76,8 +86,8 @@ earlier per-cell version (four requests per cell) filled the X socket faster
 than the in-machine server could drain it, and an `XSync` per row deadlocked
 the client: the debug progress marker stopped at row 20 (`0x00010014`) and the
 game never reached its main loop. Batching the row makes a full 80×24 redraw a
-few hundred bytes of requests and the loop runs (measured: 300+ iterations
-between frames 2500 and 3200).
+few hundred bytes of requests and the loop runs (measured at the VR319
+default: 650 iterations between frames 2500 and 3200).
 
 ## Timing and input
 
@@ -133,17 +143,23 @@ which copies the sections to their linked addresses and calls
 | `evidence/termtris_quit_3200.png` | after `q`: same screen, and the run reports `quit=1` |
 | `evidence/render_frame3400.png` | the cell-grid renderer test pattern |
 
-Acceptance values from the last full run (`play_keys.sh`):
+Acceptance values from the last full run (`play_keys.sh`, MAME 0.289 with this
+tree's driver at the **VR319 default**, 1280×1024 frames). The evidence PNGs
+above were regenerated in the same run; they are 1280×1024, where the earlier
+ones were 1024×864 VR150 captures.
 
 ```
-move    DIAG: loops=354 events=18 focus=00400001 quit=0
-panels  DIAG: loops=346 events=12 focus=00400001 quit=0
-quit    DIAG: loops=300 events=10 focus=00400001 quit=1
+move    DIAG: loops=650 events=18 last=3 focus=00400001 rev=0 quit=0
+panels  DIAG: loops=648 events=12 last=3 focus=00400001 rev=0 quit=0
+quit    DIAG: loops=555 events=10 last=3 focus=00400001 rev=0 quit=1
 ```
 
 `focus=00400001` is the window this process created (it is the only one in the
 run), so the key events were delivered to it, and `quit=1` is the game's own
-global after `q`.
+global after `q`. The loop counts are higher than the old VR150 figures
+(`354`/`346`/`300`) only because the VR319 raster runs at a different emulated
+frame rate; the event counts, window, and quit result are unchanged, and the
+loader/keys still act at frames 2500/3095–3190.
 
 ## Limits, stated plainly
 

apps/termtris/build.sh

@@ -32,6 +32,26 @@ if [ ! -x "$WORK/gspac.exe" ]; then
 	unzip -oq "$Z1" -d "$WORK"
 	unzip -oq "$Z2" -d "$WORK"
 fi
+
+# The r5.01 tools are 16-bit OS/2 NE programs, which 2ine runs through 16-bit
+# LDT segments.  A Linux kernel built without CONFIG_X86_16BIT rejects those
+# (modify_ldt returns EINVAL), so the loader aborts at its first segment even
+# though it is a 32-bit binary.  Detect that with a probe run and, when needed,
+# drive the same loader through qemu-i386, whose linux-user emulation does
+# implement the 16-bit LDT.  Set LX_RUNNER to a command prefix (for example
+# "qemu-i386") to force one; leave it unset to auto-detect.
+if [ -z "${LX_RUNNER:-}" ]; then
+	if ( cd "$WORK" && "$LX" ./gspac.exe ) 2>&1 |
+		grep -q 'failed to allocate LDT selector'; then
+		if command -v qemu-i386 >/dev/null 2>&1; then
+			LX_RUNNER=qemu-i386
+		else
+			echo "build.sh: this kernel has no 16-bit LDT support and qemu-i386 is not installed" >&2
+			echo "build.sh: install qemu-user, or set LX_RUNNER to a working runner" >&2
+			exit 1
+		fi
+	fi
+fi
 for so in "$NINE"/lib*.so; do
 	[ -e "$so" ] && ln -sf "$so" "$WORK/"
 done
@@ -78,7 +98,7 @@ run() {
 	shift
 	i=0
 	while [ "$i" -lt 5 ]; do
-		( cd "$WORK" && "$LX" "$@" ) >/dev/null 2>&1 || true
+		( cd "$WORK" && ${LX_RUNNER} "$LX" "$@" ) >/dev/null 2>&1 || true
 		if [ -f "$WORK/$_out" ]; then
 			return 0
 		fi

harness/mame/TERMTRIS_REPORT.md

@@ -12,15 +12,19 @@ Full port documentation: `apps/termtris/VT1200.md`.
 ## Build
 
 ```
-apps/termtris/build.sh src/vt1200/main.c src/game.c src/vt1200/scoredb.c \
-    src/vt1200/x11.c src/vt1200/compat.c src/vt1200/xgfix.c
+OUTNAME=termtris apps/termtris/build.sh src/vt1200/main.c src/game.c \
+    src/vt1200/scoredb.c src/vt1200/x11.c src/vt1200/compat.c \
+    src/vt1200/xgfix.c
 ```
 
 `build.sh` runs `gspac`/`gspopt`/`gspcg`/`gspa` and `gsplnk` through
 `/home/arti/os2-work/2ine/build/lx_loader` against the r5.01 SDK zips under
 `tools/tms34010-sdk/1990-11 TMS340 Family SDK/`. Those 2ine-hosted tools
 frequently segfault after writing their output, so the wrapper treats an output
-file as success and retries a missing one. Two quirks are handled there:
+file as success and retries a missing one. A host kernel without
+`CONFIG_X86_16BIT` cannot give the 16-bit OS/2 tools their LDT segments; the
+wrapper detects that and runs the same loader through `qemu-i386`, whose
+linux-user emulation implements them. Two more quirks are handled there:
 
 * `gspac` needs `-i.` for the angle-bracket shim headers;
 * an empty `.cinit` makes `cinit` point at `.text`, whose first instruction the
@@ -64,8 +68,8 @@ a single `XFlush`. This is not an optimisation for looks:
 * an `XSync` per row **deadlocked the client** — the debug marker
   `_vt_x11_progress` froze at `0x00010014` (row 20), the main-loop counter
   stayed 0 and the game window never got a preview piece. Batching a row makes
-  a full redraw a few hundred bytes and `loops` reached 300+ between frames
-  2500 and 3200.
+  a full redraw a few hundred bytes and `loops` reached 650 between frames
+  2500 and 3200 (VR319 default).
 
 ## Timing and keys
 
@@ -82,7 +86,7 @@ which draws a bogus piece over the top row (blank border plus stray `X` tiles).
 ## Reproduce
 
 ```sh
-cd /home/arti/.local/share/opencode/worktree/26e92e/termtris
+apps/termtris/verify.sh              # the whole acceptance run
 apps/termtris/tests/play.sh          # load, click, snapshot
 apps/termtris/tests/play_keys.sh     # move / panels / quit
 apps/termtris/run.sh                 # interactive MAME session
@@ -93,16 +97,21 @@ The run is `VT1200_SKIP_LEVEL1=1 LOADER_AT=2500` with the loader payload at bit
 `dwt/loader/build/loader.bin`, which places the sections and calls
 `create_process`.
 
-Last full acceptance run:
+Last full acceptance run — MAME 0.289 built from this tree's driver at the
+**VR319 default** (1280×1024 active), which is the real unit's monitor. The
+earlier figures in this report were VR150 (1024×864):
 
 ```
-move    DIAG: loops=354 events=18 focus=00400001 quit=0
-panels  DIAG: loops=346 events=12 focus=00400001 quit=0
-quit    DIAG: loops=300 events=10 focus=00400001 quit=1
+move    DIAG: loops=650 events=18 last=3 focus=00400001 rev=0 quit=0
+panels  DIAG: loops=648 events=12 last=3 focus=00400001 rev=0 quit=0
+quit    DIAG: loops=555 events=10 last=3 focus=00400001 rev=0 quit=1
 ```
 
 `focus=00400001` is the termtris window, and `quit=1` is the game's global after
-`q` — so the keys reached the game, not just the window.
+`q` — so the keys reached the game, not just the window. The event counts and
+the `tick=887` are unchanged from the VR150 run; only the loop counts moved,
+because the VR319 raster changes the emulated frame rate. The evidence PNGs
+were regenerated in this run and are now 1280×1024.
 
 | evidence | file |
 |---|---|