EscapistsReintroduced/docs/living-island/T9-pursuit.md

T9 — Pursuit: alert states, hunting, air search and cordons

Read docs/living-island/README.md first, including the rules section. Depends on T5 and T8. Belief (T8) must exist — you cannot hunt what you do not remember.

The problem

An occupied island is not a hunting island. Today HQ answers a sighting with one AIWaypoint_SearchAndDestroy at a predicted position, and releases the unit the moment it perceives anything. Nothing tracks a fleeing player, nothing searches from the air, nothing cuts a route. This task is where the pressure comes from.

1. Alert state

Per sector (reuse the 500 m coverage grid, grouped into ~2 km sectors):

State	Trigger	Behaviour
CALM	default	Garrisons hold, patrols run routes
ALERTED	a belief forms in the sector	Patrols tighten toward it, checkpoints check harder
HUNTING	actionable belief, confidence above threshold	Hunters dispatched, air search eligible
CORDON	high confidence and a known direction of travel	Chokepoints blocked between the contact and its likely objective

States decay downward on alertDecaySeconds (default 420) without new reports. Escalation is the pacing dial for the whole mission — it is what makes the island feel like it is closing in, and what lets it relax when the player breaks contact.

2. Hunting on the ground

Dispatch at most huntMaxUnits (default 3) against one belief. Hunters sweep the uncertainty circle, not a point: take the nearest unswept cells from T8's coverage grid and issue search waypoints outward from the last sighting.

• A hunter that completes its sweep reports back — "area searched, nothing found" — which marks the cells and lowers that belief's confidence. HQ must be able to learn that a search failed. Today it cannot, and that is a core defect.
• Do not release the assignment the instant a unit perceives something. Combat suspends the sweep; when combat ends the sweep resumes or is re-tasked.
• A belief that has been swept out returns the sector to ALERTED, then CALM.

3. Air search — the hunter helicopter

This is a separate role from transport. One at a time (airSearchConcurrent, default 1), drawn from the same aircraft pool, so a helicopter searching is a helicopter not lifting troops.

• Flies a search pattern (expanding box or lane search) over the belief's uncertainty circle at low altitude, using the existing ERR_AircraftService through the same provider interface as air lift.
• It observes under the normal fairness rules — ERR_HQObservation line of sight, exposure and distance gating apply to its crew exactly as to a foot patrol. A helicopter sees more because it is high and moving, not because it cheats.
• It reports by radio like any other unit. Shooting it down denies HQ its best sensor, and the loss is permanent from the pool.
• Fuel/endurance cap (airSearchSeconds, default 420) then it returns to staging. An unlimited eye in the sky is oppressive and expensive.

4. Cordons

When a sector reaches CORDON, place up to cordonChokepoints (default 4) blocking positions between the belief and the objective it is probably heading for — bridges, road junctions, ridge saddles. Not on top of the player.

Cordon positions are authored chokepoints on the site map, selected by which ones lie on plausible routes from the belief to the radio station or helipad. This is the payoff of the staleness problem: HQ knows its picture is old, so it blocks where the player must pass rather than chasing where the player was.

5. Pacing — this decides whether the mission is fun or miserable

Players start with nothing. Unbounded pressure is not difficulty, it is a cutscene about dying. Enforce all of these:

• Never materialise a hunter within minHunterSpawnMetres (default 700) of any player. No unit ever appears close enough to feel teleported in.
• No convergence from all sides. Hunters approach from at most two bearings; leave an escape vector open. A closing ring with no gap is a death sentence.
• Cooldown after contact is lost (huntCooldownSeconds, default 180) before a fresh hunt on the same belief. Breaking contact must be rewarded.
• Hunting spends the pool. Sections hunting are not garrisoning; if HQ commits hard to a hunt, its checkpoints thin and routes open elsewhere. Do not paper over this — it is the strategic trade that makes the system a game rather than a pressure dial.
• Night reduces air search effectiveness and sighting range; it should be the player's window.

Acceptance criteria

1. Being seen and then breaking contact produces a visible search: units sweeping outward from where you were, a helicopter overhead, and then — if you stay hidden and still — the search moving away and the sector calming down.
2. A failed sweep lowers confidence; HQ does not re-search the same cells.
3. The hunter helicopter spots players only under the same LOS/exposure rules as infantry; destroying it measurably degrades HQ's picture.
4. A cordon appears between the player and the objective, not around the player's exact position.
5. No hunter ever materialises within 700 m of a player, and hunters never approach from more than two bearings at once.
6. Heavy hunting visibly thins garrisons elsewhere — verify by checking a checkpoint's strength during a major hunt.
7. Active agents stay inside activeAgentBudget throughout.
8. python3 tools/check.py passes.

Tests to write

tests/test_pursuit.py:

• Alert escalation and decay: state rises with confidence and falls after the decay window with no new reports.
• Hunter dispatch respects huntMaxUnits, the cooldown, and the minimum spawn distance.
• Bearing rule: given four candidate hunters around a belief, at most two distinct approach bearings are selected and an escape vector remains.
• Cordon selection picks chokepoints on the belief→objective path, never the belief's own cell.
• Air search respects concurrency and endurance, and returns to staging on timeout.

Do not

• Do not give hunters or the search helicopter any knowledge the fairness rules would not produce. The pressure must come from good search, not from cheating.
• Do not stack hunts on multiple beliefs simultaneously beyond the unit cap.
• Do not let the cordon seal every route. There is always a way through; it should be slow, exposed or unpleasant, never absent.