fix(cockpit): an application subject's wait for the floor is bounded, a late asynchronous hold is released, and a hold never counts as the user's selection

- A subject with no height at all waits at most
  COCKPIT_GROUND_WAIT_TIMEOUT_MS for the floor, its HUD updating and
  reading ACQUIRING SURFACE; then the view ends and the provider gets its
  subject back (there is no height of its own to fall back to).
- A hold that returns a promise is refused as before and released again
  once it settles, unless that subject is being ridden by then; release
  must tolerate a second call.
- Rail and Transit stamp selectedAtMs only for a user's selection (a click,
  focusTrain or focusVehicle); a deselection clears it, and a train or
  vehicle selected only by a hold reads null.

docs/APPLICATION.md

@@ -306,3 +306,18 @@ for a provider placing a train along its line. The frame, HUD view and
 candidate fields are documented in `src/cockpitSubjectProviders.js`; the Rail
 and Transit read APIs in `src/layers/rail/cockpitSubject.js` and
 `src/layers/transit/cockpitSubject.js`.
+
+A candidate's `selectedAt` is a token that changes each time the user selects
+the subject, even the same one again, so entry takes it first. The Rail and
+Transit snapshots give one, `selectedAtMs`: when the user last selected the
+train or vehicle by a click or `focusTrain`/`focusVehicle`. It is null after
+a deselection and for one selected only by a hold, since a hold is not the
+user's selection.
+
+A frame with `heightM: null` stands on the shared floor, or where it last
+stood while that floor is cold. If no height has been known since entry, the
+view waits, showing ACQUIRING SURFACE, for at most five seconds
+(`COCKPIT_GROUND_WAIT_TIMEOUT_MS`), then ends and releases the subject. A
+`hold` that throws or returns a promise refuses entry and is followed by
+`release(id, { restore: false })`, again once a returned promise settles, so
+`release` must be harmless when called more than once.

docs/CURRENT-STATE.md

@@ -2011,7 +2011,9 @@ older subject's.
 
 A frame places the eye `eye.upM` above `heightM` (the shared floor where the
 frame gives none, or where it last stood while that floor is cold; with
-neither the camera waits where it is), slews toward `headingDeg` at the provider's rate, and may
+neither, the camera stays where it is and the HUD reads ACQUIRING SURFACE for
+at most `COCKPIT_GROUND_WAIT_TIMEOUT_MS`, after which the view ends and the
+subject is released: no height stands in for a floor never read), slews toward `headingDeg` at the provider's rate, and may
 turn off the floor clamps (`groundClamp: false`, for a subject inside a
 structure) or keep the anchor exactly on the subject (`anchor: 'exact'`, for a
 layer that already moves it smoothly); `cameraIntervalMs: 0` updates the
@@ -2034,7 +2036,8 @@ The Rail layer offers a read API for such a view: `getSelectedTrain()` and
 `getCockpitSubject()` (a snapshot of the train: where it is along its line,
 which way it runs (`pathBinding.js` learns it), its rail height, speed as
 reported or derived, position source, feed credit and stops, and
-`selectedAtMs`, when the user last selected it, even again),
+`selectedAtMs`, when the user last selected it by a click or `focusTrain`,
+even again; null after a deselection and for a train only a hold selected),
 `setCockpitSubject(key)` (its marker and card hidden, the selection kept, its
 feed held, clicks and Escape left to the view) and `focusTrain(key)`; its pure
 path module is exported as `@gods-eye-view/core/layers/rail/paths`. Transit