Capture current mission, AI, map and administration development

Include the current addon, terrain integrations, tools, regression tests and recorded development evidence.

docs/cessna-reconnaissance.md

@@ -0,0 +1,109 @@
+# Optional reconnaissance plane
+
+A dedicated server which loads **Cessna 172** (`69BAEE0D439966FE`) and its
+**Propeller Flight Core** dependency (`69A8A34027DA65C5`) can operate one enemy
+reconnaissance plane. Neither addon is an Escape project dependency. Without both
+loaded, Escape does not search for a plane prefab, survey its departure corridor
+or spawn its crew.
+
+Open **HQ → Configure Cessna** for the saved **Enabled / Disabled** choice
+(`planeReconEnabled`, default `1`) and patrol settings. Each numeric field has
+its own Apply button and saved value. All changes apply next round, including
+replacement flights; editing a field alone does not save it. The same authenticated
+command is `/esc mission plane set 0|1`. Enabling the setting does not install an
+addon or promise that the current terrain has a usable airport.
+
+| Setting | Default | Allowed range | Admin command option |
+| --- | --- | --- | --- |
+| Patrol altitude (`planeAltitudeMetres`) | 250 m | 150–500 m | `planealtitude` |
+| Replacement delay (`planeReplacementSeconds`) | 60 s | 30–1800 s | `planereplacement` |
+| New patrol area (`planeSectorSeconds`) | 120 s | 30–600 s | `planesector` |
+
+Use `/esc mission <option> set <value>` with these options. Older saved profiles
+receive the defaults automatically. Altitude is clearance above sampled terrain
+ahead, not a guaranteed height at every instant. The plane selects a new area
+when the interval expires or it reaches the current destination; departure still
+uses its dedicated takeoff leg. These controls do not change the number of planes
+or bypass the crew's native perception and radio reporting.
+
+## Operation
+
+- Airport discovery and departure clearance run in bounded background batches
+  after the mission becomes active. They do not block prisoner admission.
+- A clear, gently graded airport departure corridor and separation from players
+  are required. No airport or no safe corridor means no plane on that terrain.
+- The original Cessna prefab receives a pilot and observer from Escape's existing
+  radio-equipped aircrew prefabs, assigned to the selected enemy faction.
+- Each original crew agent is activated at permanent LOD 0 before boarding.
+  Preparation verifies the exact assigned seat and its occupant, rather than
+  treating an accepted boarding request as success. An unseated, conscious crew
+  member can make at most three native seating requests, at least five seconds
+  apart, within the original 45-second preparation deadline. Requests wait for
+  existing entry/exit transitions and refuse occupied, inaccessible, locked or
+  externally reserved seats. They never replace crew or remove other occupants.
+- A server autopilot drives the addon's controls. PFC remains responsible for
+  flight forces, collision, fuel, damage and replication. The patrol does not
+  teleport the aircraft or write its velocity/transform during flight.
+- Destinations are sampled on land, independently of player positions. Altitude
+  control samples terrain ahead; bank and throttle control follow the patrol.
+- The crew is registered with VirtualHQ as a reserved support group. Its native
+  perception supplies sightings to the existing reporting/radio network. It
+  does not reveal hidden players or inject positions straight into HQ memory.
+  Normal reporting begins after the prison phase; reporting intervals, radio
+  availability and travel time still apply.
+- Destruction, a lost pilot or a disabled aircraft schedules a replacement after
+  the configured minimum delay (one minute by default). Departure may take longer if the area is occupied or a
+  new corridor must be found. Partial, unregistered allocations are rolled back.
+- Three consecutive allocation or pre-service preparation failures pause the
+  patrol for the remainder of the round, avoiding repeated failing aircraft
+  allocations. Successfully entering service resets this streak when that
+  aircraft is retired. Destruction of an operational plane still gets its normal
+  replacement. Preparation failures now identify the blocked crew/seating/radio
+  or engine gate.
+- `PLANE CREW` journal entries record request acceptance/refusal, observed seating
+  state changes and the final timeout snapshot for both crew members. They include
+  actor/seat/occupant identity, ownership, consciousness, entry/exit state, seat
+  availability, AI activation and LOD. Routine state changes are limited to one
+  entry per crew member every five seconds; requests and final timeouts are always
+  recorded. Both crew members are checked even when the first is still boarding.
+- A player entering the plane or a faction/crew takeover releases the autopilot
+  and restores the original input rates. The captured vehicle is retained.
+- Round termination stops all autopilot callbacks. Existing force capacity and
+  a 64-departure round cap bound retained aircraft/crew bookkeeping.
+
+## Optional API boundary
+
+Verified addon versions: Cessna 172 **1.0.0**, Propeller Flight Core **1.0.18**.
+The aircraft exposes engine start publicly but its input receiver is protected.
+A small, fixed `ScriptModule.CompileScript` adapter derives from the loaded PFC
+controller and calls that receiver. It is compiled only on the authoritative
+headless server (or Workbench). No third-party source files, project dependencies
+or player input handlers are modified. Standard listen-server clients do not
+provide this dynamic compiler and skip the patrol.
+
+The adapter also temporarily holds the AI aircraft's input slew rates at zero,
+so PFC's absence-of-human-input handling does not erase its autopilot commands
+between simulation ticks. The original rates are restored when control ends.
+An incompatible future addon API prevents startup and records the reason in the
+HQ journal. The rest of the mission continues.
+
+Native checks use an isolated Reforger 1.8.0.13 dedicated server and private addon
+copies. See [native evidence](evidence/cessna-recon-2026-10-08/README.md) for the tested scenarios and their limits.
+
+The 12 October played round failed all three departures with `crew 0 not seated`;
+the scheduler then paused aircraft for that round. The boarding changes above
+address a missing pre-boarding member-activation step and make incomplete native
+entry observable and recoverable within fixed limits. That log alone does not
+establish whether the pilot never entered or left afterward.
+
+The [13 October boarding check](evidence/cessna-boarding-2026-10-13/README.md)
+compiled the revised controller and passed 19 native assertions on isolated
+Everon: US/West crew boarded and took off after the arranged prison escape;
+forced dismounts exhausted the three attempts and original timeout; preparation
+takeover preserved the aircraft; and a dead pilot caused normal failure and
+cleanup. Focused executable regressions also cover rejected requests, pending
+player control, wrong seats and blocked/reserved compartments. This does not
+reproduce the original Chernarus multiplayer session. The full native report
+retains unrelated engine/resource errors, and the repository-wide check stops
+at the existing `ERRM_AtlasLeaf.et` saved-root-ID error. No live deployment was
+performed by this repair.