v0.7.4 — Red Flags hold a train out of your Limits (Gitea#19)

"If played, asked FLAG EAST or FLAG WEST. That stops all trains from entering your
limits from that direction (i.e. Flag East holds westbound trains). You can do this
if you see a problem or wish to complete switching."

REPLACES the old rule outright, per Jesse's call. Red Flags used to be played on a
stopped train out on the Mainline and protected it from a rear-ender: offered 4,212
times and played 4 across 600 games, a mechanic nobody used, and ABS Signals already
does that job better. The flag is now planted on one side of your own district and
holds the next train arriving from that side.

SPENT ON THE TRAIN IT STOPS. One card, one train, so there is no lifting action to
build, nothing to forget, and a flag cannot quietly strangle the Division. The held
train loses one Mainline Phase and comes in on the next — it buys a Stage to clear
the lead, which is what "wish to complete switching" asks for.

PLAYABLE OUT OF PHASE, which is the other half of the issue: when an arrival would
certainly collide and the district's owner holds the card, the phase breaks in and
asks. Offered ONLY to somebody holding one — a prompt with a single button is not a
choice, and it would leak that a collision is coming. The danger is read from §8.3's
own two triggers rather than restated, so the prompt cannot offer a flag against a
collision that will not happen.

Built on the decision union Gitea#5 introduced: this adds a `redFlag` case and
nothing else structural.

THE BOT STILL NEVER PLAYS IT, AND I MEASURED RATHER THAN ASSUMED. It now takes the
out-of-phase prompt unconditionally — the engine has already established the danger,
so there is nothing left to judge — and over 200 solitaire games `redFlagsSet` fires
ZERO times. The prompt needs an arrival that would collide (0.14 per game, about one
game in seven) to coincide with holding the card from a three-card hand out of 121.
So the anomaly exemption in sim.test.ts stays, but its comment no longer claims the
bot is unwilling: it is measuring deck luck. What is left to fix is the half of the
card a human would use, planting a flag on purpose to buy switching time, and TODO.md
now says that instead of the old finding.

A BUG WORTH RECORDING, because the next interruption will meet it too: the flag was
originally taken down in a `reduce` case, which never fires for an event advance.ts
emits — the phase driver mutates state and then describes it. The flag stayed up and
held every train that came. test/events.test.ts's unreduced-event registry is what
makes that class of mistake visible, and `redFlagSpent` is on it deliberately now,
with the reasoning.

858 tests pass.

Closes #19

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

src/engine/advance.ts

@@ -974,13 +974,22 @@ function moveTrain(s: GameState, id: TrayId, tray: CrewTray, events: GameEvent[]
      * half-applied. Asking after the `transits` filter below cost the train its place on the card
      * and it was never seen again — the question was asked and the answer had nowhere to land.
      */
-    if (dest?.kind === 'office' && yardOfficeQuestion(s, id, tray, dest.seat, events) === 'ask') {
-      return 'needsClearance';
+    if (dest?.kind === 'office') {
+      /**
+       * §Q, RED FLAGS (Gitea#19) — asked and answered before the train leaves the card, for exactly
+       * the reason the Yard Office offer is (see below): `needsClearance` unwinds the phase.
+       *
+       * Order matters. A flag stops the train OUTSIDE the Limits, so it never reaches the point
+       * where the Yard Office would be offered — flagging is about keeping a train out altogether.
+       */
+      const flagged = redFlagStop(s, id, tray, dest, events);
+      if (flagged === 'ask') return 'needsClearance';
+      if (flagged === 'held') return 'held';
+
+      if (yardOfficeQuestion(s, id, tray, dest.seat, events) === 'ask') return 'needsClearance';
     }
 
     node.transits = node.transits.filter((t) => t.tray !== id);
-    // Red Flags protect a train while it is stopped here; once it rolls, the flags come in.
-    if (node.redFlagged) node.redFlagged = node.redFlagged.filter((t) => t !== id);
 
     if (!dest) return 'held';
 
@@ -1087,10 +1096,10 @@ function evaluateClearance(
     // from moving". Flagging is per-train rather than per-card, so it protects one specific train
     // where ABS Signals protects everything on the card.
     //
-    // Both of these read the card the OTHER train is standing on rather than the card being
-    // entered. They were the same card while this only looked one card ahead; across a Subdivision
-    // they are not, and the protection belongs where the train it protects actually is.
-    if (onNode?.kind === 'mainline' && (onNode.redFlagged ?? []).includes(other)) return 'blocked';
+    // Red Flags used to protect a stopped train here as well. Gitea#19 replaced that rule outright
+    // (Jesse, 2026-08-29): a flag is now planted on a district's Limits and holds trains coming from
+    // one direction, so it never applies out on the Mainline. ABS Signals is what protects a train
+    // standing on a Mainline card now, and it always did the job better.
 
     /**
      * ABS Signals — "this is played on a mainline card to prevent collisions. If a collision would
@@ -1147,6 +1156,103 @@ function evaluateClearance(
  * way the train is already facing. Reversing is a separate Move (§A.5), so a Yard Office that can
  * only be reached by backing up is correctly "not in one move".
  */
+/**
+ * The flag comes down as it stops the train — one card, one train (Gitea#19).
+ *
+ * MUTATES RATHER THAN EMITTING A REDUCED EVENT, because this is the phase driver: `advance.ts`
+ * changes state directly and then describes what it did, and roughly a third of the event types are
+ * never reduced at all (`README.md`, and `tally.ts` on the same asymmetry). A `redFlagSpent`
+ * reducer case looked right and never fired — the flag stayed up and held every train that came.
+ */
+function spendFlag(
+  office: Extract<DivisionNode, { kind: 'office' }>,
+  tray: CrewTray,
+  side: Direction,
+  events: GameEvent[],
+): 'held' {
+  delete office.redFlag;
+  events.push({ type: 'redFlagSpent', seat: office.seat, side, trainNumber: tray.trainNumber ?? 0 });
+  events.push({
+    type: 'trainHeld',
+    trainNumber: tray.trainNumber ?? 0,
+    reason: 'Red Flags — held short of the Limits',
+  });
+  return 'held';
+}
+
+/**
+ * §Q, RED FLAGS (Gitea#19) — does a flag stop this train, and should its owner be offered one?
+ *
+ * Two jobs, because they are the same moment seen twice: a flag already planted stops the train
+ * outright, and a train about to run into trouble is the cue to offer a flag to somebody holding
+ * the card. "You can play the card normally or out of phase, but only if you need it."
+ *
+ *   - `held`    — a flag was up on the side this train is coming from. It loses this Mainline
+ *                 Phase and the flag comes down with it: one card, one train (Jesse, 2026-08-29).
+ *   - `ask`     — entering would collide and the district's owner holds a Red Flags card.
+ *   - `proceed` — neither.
+ *
+ * WHICH SIDE. A train running WEST arrives from the east, so `FLAG EAST` is what holds it — which
+ * is the example the issue gives, and the reason the flag names a side rather than a heading.
+ */
+function redFlagStop(
+  s: GameState,
+  id: TrayId,
+  tray: CrewTray,
+  dest: Extract<DivisionNode, { kind: 'office' }>,
+  events: GameEvent[],
+): 'held' | 'ask' | 'proceed' {
+  const from: Direction = tray.direction === 'east' ? 'west' : 'east';
+
+  // The answer to a prompt already put. Consumed here so the driver cannot ask twice.
+  const answer = s.clock.decisionAnswer;
+  if (answer && answer.kind === 'redFlag' && answer.train === id) {
+    s.clock.decisionAnswer = null;
+    if (!answer.flag) return 'proceed';
+    // The card was spent planting the flag; it stops this train and comes down again at once.
+    return spendFlag(dest, tray, from, events);
+  }
+
+  if (dest.redFlag === from) return spendFlag(dest, tray, from, events);
+
+  /**
+   * "In actual cases of danger… if there is a train or cars on the track and there will be a
+   * collision, then you break in with a dialog." The two ways an arrival collides are §8.3's own:
+   * no free A/D track, and cars fouling the Running Track. Asked only of a player who can actually
+   * answer — offering a flag to somebody holding no card is a prompt with one button.
+   */
+  const owner = playerAtSeat(s, dest.seat);
+  const holdsFlag = (s.decks.hands.get(owner) ?? []).some((cid) => {
+    const c = s.cards.get(cid);
+    return c?.kind.kind === 'maneuver' && c.kind.key === 'redFlags';
+  });
+  if (!holdsFlag) return 'proceed';
+  if (!arrivalWouldCollide(s, id, tray, dest.seat)) return 'proceed';
+
+  s.clock.pendingDecision = { kind: 'redFlag', train: id, seat: dest.seat, from };
+  return 'ask';
+}
+
+/**
+ * Would this arrival collide? §8.3's two triggers, asked before the train commits.
+ *
+ * Deliberately a READ of the same conditions `arriveAtOffice` enforces rather than a second rule:
+ * if these two ever diverge, the prompt offers a flag against a collision that will not happen, or
+ * stays silent before one that will.
+ */
+function arrivalWouldCollide(s: GameState, id: TrayId, tray: CrewTray, seat: SeatIndex): boolean {
+  const area = areaAtSeat(s, seat);
+  const hasInterlocking = [...area.grid.values()].some((c) => c.enhancements.includes('interlocking'));
+  const full = area.adOccupancy.length >= officeProfile(area.tier).adTracks;
+  // Interlocking turns a full Office into a hold rather than a collision, so it is not danger.
+  if (full && !hasInterlocking) return true;
+
+  // A coach may legally stand at the Office while its engine switches (§A.4's carve-out), so it is
+  // not a hazard to the next arrival. Anything else on the Running Track is.
+  const officeCard = area.grid.get(coordKey(area.officeCoord));
+  return officeCard !== undefined && officeCard.standing.some((c) => c.type !== 'coach');
+}
+
 /**
  * §11 (Gitea#5) — should the district's owner be asked about the Yard Office, and is there
  * anything to ask about?
@@ -1396,7 +1502,6 @@ function collide(
       if (n.kind !== 'mainline') continue;
       n.transits = n.transits.filter((t) => t.tray !== id);
       if (n.holding) n.holding = n.holding.filter((t) => t !== id);
-      if (n.redFlagged) n.redFlagged = n.redFlagged.filter((t) => t !== id);
     }
     /**
      * AND OFF THE A/D TRACK, for exactly the same reason as the transit above.