Fix convoy coordination, AI combat and spectator recovery

docs/ai-local-awareness.md

@@ -0,0 +1,73 @@
+# Local observations and HQ response
+
+Mission-owned primary-enemy squads now capture visual evidence in the native
+`SCR_AIGroupPerception.AddOrUpdateTarget` callback, before the next one-second HQ
+update. Capture still requires an enemy target seen within 0.5 seconds, a clear
+native trace and positive exposure. The source, last-seen position, observation
+time and visible equipment are copied immediately. Subsequent movement or gear
+changes do not alter that report.
+
+Each squad keeps at most 16 visual snapshots and one sound report, for at most
+30 seconds. Repeated visual capture is limited to once per second per retained
+target. Sending uses the existing observation watermark, so polling cannot resend
+the same observation. This is local squad knowledge; only successful physical
+radio delivery creates HQ memory. A missing radio route leaves the snapshot
+pending until it expires. An accepted transmission is not duplicated if it fails.
+
+Captured contacts can use the next free uplink, with at most one attempt per five
+seconds. They can precede routine status, but status overdue by 15 seconds gets
+the next free slot. Existing transmissions are allowed to finish. The saved
+report interval still controls the ordinary polling path; the new event path
+works even on an existing server profile with a ten-second report interval.
+A delivered report brings forward the next HQ planning pass.
+
+## Heard fighting
+
+The native `AddOrUpdateGunshot` callback supplies hostile-fire evidence. Native
+weapon danger reactions invoke it for audible shots or incoming fire; grenade
+danger can also notify this native group path. The mission does not scan player
+positions or invent a hearing radius. Capture is scoped to bound, server-owned,
+primary-enemy AI groups during the active post-prison mission. Unregistration
+and round teardown detach the hook and discard pending observations.
+
+A sound report carries a 150-metre grid area's centre, its observation time and
+the reporting squad. Shooter identity, player count, equipment and movement are
+not sent. Sound updates are coalesced to one per second and radio reports to one
+per 30 seconds per squad. Visual evidence takes precedence in the local inbox.
+
+Delivered sound has its own memory kind, keyed by reporting squad rather than an
+unseen shooter. Initial confidence is 0.4, halves every 60 seconds, and positional
+uncertainty starts at 150 metres and grows by 2 metres per second. Repeated sounds
+never infer target velocity. A visual sighting creates a separate stronger track.
+
+HQ can allocate one existing mobile search squad per sound task, within the
+current response radius, total assignment limit and hunt cooldown. This uses the
+ordinary radio downlink, search waypoint and negative-search report. Sound alone
+cannot authorize mortar/aircraft targeting, paratrooper targeting or a hunter
+UAZ precision interception. Permanent objective defenders, mortar crews and
+other reserved specialists remain excluded from mobile assignments. Native
+local combat and the existing defensive waypoints remain responsible for their
+immediate defensive movement.
+
+Maximum AI skill, alerted recognition and Regular aim error are unchanged. No
+additional soldiers or vehicles are spawned by this change.
+
+## Validation
+
+`test_hq_local_awareness.py` executes the production cache and contact scheduler
+with engine/radio adapters: frozen evidence, expiry, coalescing, capacity, duplicate
+rejection, route loss/retry, captured-contact priority and bounded status delay.
+The existing memory, radio fairness and local handoff tests cover the new sound
+kind and retained observation age. The dedicated `hq-awareness` native fixture exercises the
+cache, isolated native gunfire callback, sound confidence/targeting restrictions,
+and production cached-contact intake followed by physical radio delivery. Its
+injected observations do not prove natural hearing/visibility or combat tactics
+in a live multiplayer session.
+
+Validation on 2026-09-25: repository checks passed; the dedicated Workbench
+fixture compiled and completed its awareness, physical radio, memory and teardown
+assertions. The launcher encountered a terminating-process classification race
+while verifying cleanup; a subsequent private-prefix idle check passed. Logs and
+source manifests, including earlier failed fixture attempts, are retained under
+`.local/analysis/ai-awareness-2026-09-25/`. The fixture arranges an isolated local
+inbox so concurrent natural contacts cannot replace its injected payload.