docs: file #339 — stuck in portal space, destination reveal never becomes ready

Captured live 2026-08-07 with the raw log attached rather than
summarised. Generation 2 to cell 0x3032001C: render, composites and
collision are all False at begin and still all False at cancel, so
complete and world-visible never fire and the five-second wait cue sits
there until the client is closed.

Filed rather than chased, per user direction. Two things recorded
because they will otherwise be assumed: the same destination succeeded
TWICE in the previous session, so it is intermittent rather than a
broken landblock; and while it is mechanically very likely unrelated to
the #32 contact-plane change landed minutes earlier (different
subsystem, different thread), it fired on the first run after it, so the
entry says to A/B against a binary without #32 before ruling it out
rather than asserting independence.

Also flags, without assuming either way, that #280's D-1 was an
unrecoverable portal hang with the same visible symptom — this is either
that regressing or a second mechanism wearing its face.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/ISSUES.md

@@ -24,6 +24,66 @@ What does NOT go here:
 - Every session: scan OPEN issues at start; promote/close anything we touched during the session before ending.
 - Promoting to a Phase: mark as `DONE (promoted to Phase X)` + commit SHA where the Phase entry landed.
 
+## #339 — Stuck in portal space: the destination reveal generation never becomes ready
+
+**Status:** OPEN — observed live 2026-08-07, evidence captured. **Not chased**;
+user directed it be fixed later.
+**Severity:** HIGH when it fires — the session is unrecoverable without closing
+the client. The player never leaves portal space.
+**Component:** streaming / world reveal (NOT physics — see below).
+
+### What the log shows
+
+`session-a2.log`, generation 2, destination cell `0x3032001C` (landblock
+`0x3032`, Rithwic):
+
+```
+245: world-reveal event=begin      gen=2 kind=Portal cell=0x3032001C render=False composites=False collision=False ready=False
+246: world-reveal event=readiness  gen=2 kind=Portal cell=0x3032001C radius=12 render=False composites=False collision=False ready=False
+265: world-reveal event=wait-cue   elapsedMs=5004  (AP-150's five-second arming)
+285: world-reveal event=cancel     gen=2  render=False composites=False collision=False ready=False
+```
+
+**The three readiness flags never flipped.** `render`, `composites` and
+`collision` are False at `begin` and still False at `cancel` — the destination
+never completed, so `complete` and `world-visible` never fired and the wait cue
+sat there until the user closed the client. The `cancel` at line 285 is the
+shutdown, not a recovery.
+
+### What makes this worth a separate issue
+
+**The same destination succeeded twice in the previous session.** In
+`session-a.log`, generations 2 and 3 both teleported to this exact cell
+`0x3032001C` and both reached `world-visible`. So it is not a permanently
+broken landblock — it is intermittent, which is the harder shape.
+
+### NOT established
+
+- **Whether it is related to the #32 fix landed minutes earlier.** The user
+  called it unrelated and mechanically that is very likely right: #32 changes
+  `CollisionInfo`'s per-transition contact-plane writes, while the `collision`
+  flag in these lines is the *prepared-collision publication* for the
+  destination landblock — a different subsystem on a different thread. But
+  "very likely" is not "established", and this fired on the first run after
+  that change. **Reproduce once on a binary WITHOUT #32 before ruling it out**;
+  that is one A/B run, far cheaper than being wrong.
+- Which of the three flags is the blocker, or whether all three stall on a
+  common upstream dependency. The readiness line reports them together and
+  nothing here separates them.
+- Whether it is the same class as **#280's D-1** (the unrecoverable portal hang
+  found and fixed at the C5c review). D-1 was a reveal-gate hang with the same
+  visible symptom. If this is D-1 recurring, that is a regression in a fix
+  already accepted; if it is a second mechanism with the same symptom, it needs
+  its own name. **Do not assume either.**
+
+### Related
+
+AP-149 / AP-151 (reveal-gate strictness versus retail's prefetch predicate),
+AP-150 (the five-second wait-cue arming, which is what produced line 265),
+#280 and its D-1 fix.
+
+---
+
 ## #338 — The player resolves with stepUp/stepDown 0.400 where Setup 0x02000001 authors 0.600 / 1.500
 
 **Status:** OPEN