fix: improve endgame clock and gameplay stability

docs/cw-start-randomization-investigation.md

@@ -0,0 +1,44 @@
+# CW start, promotion and 6900 investigation
+
+## Findings (2026-11-02)
+
+- `CurrencyWarsInitialRuns.json` contains one starting capture for each mode,
+  both for division 20101. `buildCurrencyWarsInitialRun` copies that capture;
+  the chosen portal then replaces the run with its recorded outcome from
+  `CurrencyWarsEntryTransitions.json`. Its offered portals, starter roles,
+  route displays and saved boss/camp choices are consequently repeated. The
+  later enemy factory uses those saved boss/camp choices. This is independent
+  of whether the player has been promoted; it is not a procedural start.
+- Terminal victory calls `currencyWarsTerminalSettlement`, which calculates
+  and saves a division increase. Quit and `/cw end` are not wins and do not
+  promote. The present ranking calculation is implementation policy, not a
+  verified original-server formula. A promoted division has no matching
+  initial capture, so a subsequent start for that division is rejected; no
+  successful full-run Client verification is established here.
+- Retcode 6900 is `RET_GRID_FIGHT_CONF_MISS` and covers multiple errors. In
+  the available root `gameserver.log`, the attempted pending action at queue 1
+  with request arm `DCPHLHNLNKF` was rejected as unsupported, followed by a
+  successful portal selection (`MFFCPLBNHCF`). The empty request payload does
+  not by itself prove which button was pressed. It must not be assumed that
+  every reported 6900 has this cause. The isolated `for ship` log instead
+  records a later initial-round rejection on a two-star starter; that defect
+  was fixed in `cwInitialRound`, but the old log cannot prove a newer binary
+  was deployed or that the Client accepted it.
+- The revision-matching xaodev reference leaves portal reroll counts zero and
+  explicitly does not offer rerolls. Its random portal generation depends on
+  general effect handling, while this server only has recorded outcomes for
+  the captured choices. Adding arbitrary portal IDs, returning success without
+  applying their effects, or swapping in a different captured battle would
+  conceal the missing behavior and risk the previously verified Battle route.
+
+## Work still needed
+
+Implement and validate a resource-backed run generator and portal effect
+transactions for each supported choice, with a coherent route, camp, boss,
+starter team, pending actions and battle payload. Cover promoted divisions
+without changing existing confirmed Battle wiring. Resolve the exact meaning
+of request arm `DCPHLHNLNKF` with revision-matching static or recorded evidence
+before implementing it. For a new 6900, identify the active executable and
+the corresponding `CW_PENDING_ACTION` rejection rather than relying on the
+numeric return code alone. Offline tests are necessary but do not establish
+Client gameplay acceptance.