v0.7.9.6 — three things the engine knew and the screen did not

Found by looking rather than by being told. Gitea#21, #22, #94 and #96
were four instances of one fault in a row — the engine gains something
that changes what a train may do, and nothing draws it — and every one
was found by a player hitting it. So instead of waiting for the fifth,
every field of GameState and its nested types was enumerated, checked for
a reader in sim/view.ts, src/web/ and sim/narrate.ts, and the survivors
verified BY RUNNING THE ENGINE rather than by trusting the grep.

Four fields had no reader. `movedThisPhase` lives and dies inside one
`advance` call and is nobody's business. The other three are below. What
was ruled out matters as much: `freightWorked`, `drawnThisTurn`,
`freightAgentUsed`, `switchedSince` and `movesUsed` are invisible on
purpose, their effect already showing as legality or as a complement
already on the Frame. A field is not a display gap merely because nothing
renders it.

#98 — the Crew Tray pool. §7 scarcity is called an explicit mechanic and
was explicit only in the engine. The blocked panel had one tray rule,
keyed off the train due out this Stage, so a player who spent a card on
an Extra or ordered a second section got an EMPTY panel while their train
sat behind an exhausted pool — both having been announced once in the log
in a line promising a future event that nothing then confirmed. The
shared table carries the pool and the queue now, so the common board gets
it too, and the panel reports all three with the count beside them.

#99 — a train held at the Limits vanished off the board, and this one had
shipped. The Interlocking stops an inbound train on the Limit Track
rather than colliding with a full Office. `arriveAtOffice` removes the
tray from the Mainline node's `transits` and the Interlocking branch
pushes it onto `heldAtLimits` without assigning `tray.position` — and the
map draws mainline nodes from `transits` and squares from
`position.at === 'grid'`, so between the two it was drawn in NEITHER. It
disappeared on arrival and reappeared in the Office some Stages later.
Fixed in the view: the engine is right, and `position` is left alone
deliberately so nothing treats the train as standing somewhere it could
be switched from.

#100 — the Campaign Train's speeches change its rules, and the card said
the same thing before and after. Worse, the "EXPEDITED ... costs 1
Revenue" warning prints only under `rules.expedite`, so X17 became
subject to a fault whose warning the game shows to every other expedited
train and never to it. `trainRules` reads `speechMade` now and borrows
`isExpedited` from advance.ts rather than restating the test.

#45 — the 0.7.9 dead-field audit, finished, and the answer was different
for each. `overHandLimit` is WIRED: its consumer existed all along and
was inferring the hand limit from the ABSENCE of `draw.end` in the menu,
which is sound only while `check` keeps refusing for exactly three
reasons. `viewerSeat` is DOCUMENTED, with a condition — Gitea#20's board
keys districts by seat, and the note says to delete it if step 2 ships
without using it.

The audit had missed a third limb. `game.mustPlayCard` was assigned on
every submit and read by nothing: deleted. Chasing it turned up the thing
worth fixing — the §6.2 hand-limit test existed in THREE places, all
agreeing, which is the state #96's disagreement started from. One
`overHandLimit(state, player)` in state.ts now, and the other two ask it.
`Session.overHandLimit()` is deleted rather than kept: the Frame already
carries the fact, so the method was a second path to it.

934 tests pass, up from 917. The 17 new ones were written red, and each
fix checked by mutation: reverting `speechMade` fails 2, dropping the
held-train projection fails 4, forgetting the tray queues fails 2. The
empty blocked panel is reported beside its positive control, since an
empty result from a broken function proves nothing.

NOT VERIFIED AT A TABLE. Engine and view work, checked by tests and by
running the engine. #39 and #35 still stand.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y5boPxP6JHRYMm8adXaF5R

src/sim/view.ts

@@ -10,7 +10,7 @@
  * drift into two different pictures of the same board.
  */
 
-import { regionOfTransit } from '../engine/advance.ts';
+import { isExpedited, regionOfTransit } from '../engine/advance.ts';
 import {
   areaAtSeat,
   areaOf,
@@ -35,6 +35,7 @@ import {
   REALIGNMENTS,
   OFFICE_ORDER,
   SPACE_USE_CARDS,
+  crewTrayCount,
   enhancementRule,
   enhancementText,
   industryProfile,
@@ -47,7 +48,7 @@ import {
 } from '../engine/content.ts';
 import type { Intent } from '../engine/intents.ts';
 import type { Facility, GameConfig, GameState, PlayerIndex, SeatIndex, TrackCard, TurnoutOrientation } from '../engine/state.ts';
-import { actingPlayer, carsOn, playerAtSeat, railFacingOf, seatOf, turnOf } from '../engine/state.ts';
+import { actingPlayer, carsOn, overHandLimit, playerAtSeat, railFacingOf, seatOf, turnOf } from '../engine/state.ts';
 import type { Direction, Hand, HouseRules, TrackGeometry } from '../engine/content.ts';
 import type { Port } from '../engine/track.ts';
 import { connectionsFor, slopeOfPair, variantsFor } from '../engine/track.ts';
@@ -104,6 +105,15 @@ export type CellView = {
      * standing in front of them — the card is face down in a box somewhere by then.
      */
     what: string;
+    /**
+     * HELD AT THE LIMITS BY AN INTERLOCKING, rather than standing on this square (#99).
+     *
+     * The engine keeps these in `OfficeArea.heldAtLimits` and deliberately does NOT move
+     * `tray.position` onto the grid — a held train is not on a square anything may switch it from.
+     * So the map has to draw it from the held list, and mark it, or it reads as an ordinary arrival
+     * the player could work.
+     */
+    heldAtLimits?: true;
   }[];
   /**
    * Office card only: how many A/D tracks the tier has — null everywhere else.
@@ -457,7 +467,17 @@ export type Frame = {
    * there is only one; the first thing you want to know at a four-player table.
    */
   viewer: number;
-  /** The viewer's position in the west-to-east chain, which is not their player index (§4.4). */
+  /**
+   * The viewer's position in the west-to-east chain, which is not their player index (§4.4).
+   *
+   * CARRIED AHEAD OF ITS CALLER, DELIBERATELY (#45). Nothing renders this today — the 2026-08-30
+   * dead-field audit found it read only by one test, and Jesse deferred the delete-or-document
+   * call. Documenting rather than deleting, because Gitea#20's common board keys every district by
+   * SEAT and resolves the player through `playerAtSeat` (§Employee Rotation moves players between
+   * districts), so a client that must pick its own district out of a seat-keyed board needs exactly
+   * this and cannot derive it from `viewer`. If step 2 ships without using it, delete it then —
+   * this note is the reason it survived one audit, not a permanent exemption from the next.
+   */
   viewerSeat: number;
   /**
    * §4.4's opening D12 per player, and the roll that chose the Superintendent — kept so a client
@@ -750,6 +770,39 @@ function baseOf(
  */
 function trainsOnCard(s: GameState, viewerSeat: SeatIndex, key: string): CellView['trains'] {
   const out: CellView['trains'] = [];
+
+  /**
+   * TRAINS HELD AT THE LIMITS — drawn here or drawn nowhere (#99).
+   *
+   * `arriveAtOffice` takes the tray out of the Mainline node's `transits` and, when an Interlocking
+   * saves it from Gap 2d's collision, pushes it onto `heldAtLimits` without giving it a grid
+   * position. The map draws mainline nodes from `transits` and squares from `position.at === 'grid'`
+   * — so between the two the train was drawn in NEITHER, and simply vanished off the board until an
+   * A/D track freed some Stages later.
+   *
+   * At WHICH Limits: the end it came in by. An eastbound train entered from the west, so it is held
+   * at `limitsWest`; a westbound one at `limitsEast`.
+   */
+  const area = areaAtSeat(s, viewerSeat);
+  for (const id of area.heldAtLimits) {
+    const t = s.trays.get(id);
+    if (!t) continue;
+    const at = t.direction === 'east' ? area.limitsWest : area.limitsEast;
+    if (`${at.row},${at.col}` !== key) continue;
+    out.push({
+      trayId: id,
+      label: t.trainNumber === null ? 'crew' : `T${t.trainIsExtra ? 'X' : ''}${t.trainNumber}`,
+      cars: t.consist.map((c) => carLabel(c, viewerSeat)),
+      engineAt: Math.max(0, Math.min(t.consist.length, t.engineAt)),
+      facing: railFacingOf(t),
+      what:
+        'HELD AT THE LIMITS — the Interlocking stopped it on the Limit Track instead of letting it ' +
+        'collide with a full Office. It takes the first A/D track that frees, ahead of any train ' +
+        `arriving after it. ${trainRules(t)}`,
+      heldAtLimits: true,
+    });
+  }
+
   for (const [id, t] of s.trays) {
     if (t.position.at !== 'grid' || t.position.seat !== viewerSeat) continue;
     if (`${t.position.coord.row},${t.position.coord.col}` !== key) continue;
@@ -1515,6 +1568,27 @@ export function projectSharedTable(s: GameState) {
             ? `Mainline card ${t.position.index}`
             : `Office Area (${t.position.coord.col},${t.position.coord.row})`,
     })),
+    /**
+     * THE CREW TRAY POOL, WHICH IS §7's SCARCITY MECHANIC (#98).
+     *
+     * `state.ts` calls it explicit, and it was explicit only in the engine: there are fewer trays
+     * than there are trains wanting one, and nothing said how many were left. Public without
+     * question — the trays are physical objects in the middle of the table, and this is a count
+     * beside the deck and yard counts already here.
+     */
+    crewTrays: { free: s.freeTrays.length, total: crewTrayCount(s.players.length) },
+    /**
+     * THE TRAINS QUEUED FOR ONE — the other half, and the half that had been promised in words.
+     *
+     * Playing an Extra says "it runs once as soon as a Crew Tray frees up"; ordering a second
+     * section says "an identical train will run right behind it". Both were announced once in the
+     * log and then existed only in the engine, so neither promise was ever visibly kept. Who played
+     * an Extra is public: §7 gives the train to the player who played the card, in the open.
+     */
+    queued: {
+      extras: s.pendingExtras.map((x) => ({ trainNumber: x.trainNumber, player: x.player })),
+      secondSections: [...s.pendingSecondSections],
+    },
   };
 }
 
@@ -1647,8 +1721,7 @@ export function snapshot(
     viewer,
     viewerSeat,
     handCount: (s.decks.hands.get(viewer) ?? []).length,
-    overHandLimit:
-      (s.decks.hands.get(viewer) ?? []).length > (s.decks.redFlags.get(viewer) ? HAND_LIMIT + 1 : HAND_LIMIT),
+    overHandLimit: overHandLimit(s, viewer),
     objective: objectiveOf(s, viewer),
     runningRow,
     limits,
@@ -1825,6 +1898,12 @@ export function cardDescription(s: GameState, id: string): string {
 export function trainRules(t: {
   trainNumber: number | null;
   trainIsExtra: boolean;
+  /**
+   * X17 only — whether the speeches are made, which is what decides which HALF of its printed rule
+   * the train is currently living under (#100). Optional because the timetable renders a train
+   * number with no tray behind it; absent means "not yet", which is the state a train starts in.
+   */
+  speechMade?: boolean;
 }): string {
   const p = trainProfile(t.trainNumber ?? 0, t.trainIsExtra);
   if (!p) return '';
@@ -1869,11 +1948,25 @@ export function trainRules(t: {
   if (p.rules.pickUpEmptiesOnly) {
     parts.push('EMPTIES ONLY — it may not couple a loaded car. A caboose is not a load.');
   }
+  /**
+   * WHICH HALF OF ITS RULE THE CAMPAIGN TRAIN IS IN (#100).
+   *
+   * "One turn at station (speeches) then expedite" is two states, not one sentence. This used to
+   * print the sentence and stop, so the chip read identically before and after the speeches — while
+   * the fault the second half creates was warned about only under `expedite`, i.e. to every train
+   * EXCEPT the one that had just become subject to it.
+   */
   if (p.rules.stopThenExpedite) {
-    parts.push('STOPS ONCE FOR SPEECHES, then runs expedited from its next Office onward');
+    parts.push(
+      t.speechMade
+        ? 'SPEECHES MADE — it runs EXPEDITED from here on'
+        : 'STOPS ONCE FOR SPEECHES at its first Office, then runs expedited from the next one onward',
+    );
   }
 
-  if (p.rules.expedite) {
+  // `isExpedited` (advance.ts) is the engine's own test, borrowed rather than restated: a card that
+  // described a rule the engine did not apply — or the reverse — is the whole failure this is in.
+  if (isExpedited(t)) {
     // It is released and switched exactly like any other train — the restriction is on where it may
     // be LEFT, not on when it leaves.
     parts.push(