# Supply convoys

The production HQ now uses `ERR_SupplyConvoySystem`, `ERR_SupplyConvoyService`, `ERR_SupplyConvoyColumn` and `ERR_SupplyConvoyTactics`, adapting the owned original `EAI_SupplyConvoys.c` to the combined mod's native AI and force ledger.

## Configuration

Esc → Mission settings → HQ → **Convoys next round** accepts **0–20** or **Random** (uniformly 0–20). The original default is **3**. The server resolves and freezes this count when the round is created. `/esc convoys show`, `/esc convoys set 3` and `/esc convoys set random` use the same authenticated command service. `/esc hq convoy count ...` is an alias. Changes do not create or delete an active convoy.

The existing `automaticConvoyEnabled` switch remains supported. A saved zero continues to disable automatic startup. `/esc hq convoy start` can consume the next unused slot in the current round's configured allowance; it cannot replace a consumed slot. The settings importer preserves the original exact `convoyCount`, including zero, rather than reducing it to one convoy.

## Vehicles, soldiers and cargo

Each USSR convoy uses the original order: PKM UAZ, ammunition Ural, troop Ural, PKM UAZ, BMP-1, PKM UAZ. There are **25 original soldiers**: eleven vehicle crew and all fourteen Ural passenger seats, alternating between two independent seven-person infantry teams. Drivers and gunners stay in separate vehicle groups. The groups use the successor's memberless prefab, not the original framework's group-spawn hooks.

One finite receipt reserves eight groups and 25 bodies before creation. Partial creation consumes that slot and preserves surviving entities. The production budget permits the existing 60-body allowance plus 25 bodies per configured convoy, within the shared 256-formation ledger. Losses never refund convoy slots. This is an admission ceiling, not a performance guarantee for twenty simultaneous convoys.

The ammo truck receives eight random weapons from the convoy faction's native arsenal and six matching magazines/projectiles per muzzle of each successfully inserted weapon. The batch has a 96-ammunition-request ceiling and is issued once. Storage failures reduce the actual load; there is no refill after looting. Vehicle contents, casualties and surviving soldiers remain physical after controller release. The later [infantry resupply integration](multiconvoy-resupply.md) captures actual faction-independent magazine identities after both cargo phases and supports each admitted convoy's original ammo truck, with shared demand replay/cooldown guards.

## Optional finite mine cargo (1 October 2026)

Each original admitted ammunition truck now attempts to load up to **two PMN4 mines once**, after all initial weapon, infantry-ammunition and mounted-ammunition callbacks finish. This is a conservative successor allowance; the predecessor grants two carried mines per soldier but does not define this fixed convoy mine batch. Remaining physical inventory and combined request headroom limit insertion. Missing storage, unavailable capacity, refusal or timeout can reduce the actual load to zero; they never trigger a retry or replacement.

The optional batch has its own callbacks and fixed 90-second window. It cannot delay normal convoy admission or the infantry/mounted magazine-stock snapshot. Original truck ownership, exact callback item identity, prefab, reciprocal storage custody, damage and inactive trigger state are checked before freezing at most two original identities. Preexisting inventory, duplicate callback identities and late/unknown results cannot enlarge or reopen that snapshot. Physical uncertain items are retained.

These frozen originals now feed the existing coordinator's narrow [one-to-two mine top-up](infantry-resupply.md#finite-mine-top-ups-1-october-2026), sharing its spent ledger. Zero-stock recovery and repeated placement remain unfinished. The stock-only checkpoint evidence below predates that delivery integration. [Review, mutation control and full regression evidence](evidence/convoy-mine-stock-2026-10-01/review.json) cover the batch and its independence from primary ammunition. All 265 regression programs pass. The normal native route compiles and completes 63 assertions with zero script/runtime failures and thirteen retained installed-resource errors; it does not qualify physical mine insertion, delivery or multiplayer.

## Travel and combat

After prison escape and existing force admission, automatic deployment begins after a 30-second grace period. Every five seconds it tests up to eight road formations, for at most 120 startup passes. It uses friendly military outpost, depot and radio-site road approaches within 500 metres, deduplicated at 300 metres. Starting formations are separated by up to one kilometre and retain all existing road, terrain and obstruction checks.

The initial road route feeds an ongoing circuit between different friendly bases. One travel controller paces each column: the lead vehicle follows the route and each follower targets the preceding surviving vehicle. After combat or a new base leg, travel order follows physical approach to the destination while vehicle identities and combat roles remain unchanged. The leader waits when a neighbour gap exceeds 160 metres and resumes below 90 metres; followers regulate their speed and retain stable movement targets. Arrival requires the lead vehicle to physically reach the route endpoint and the followers to close up in order. A timeout never counts as arrival. Commanded vehicles with no five-metre progress retry native navigation after 45 seconds; after three minutes without progress they leave the column, preserving their physical crew and cargo. Combat, boarding, intentional spacing waits and supply stops do not consume that timer. Convoys pause 45–90 seconds after physical arrival before selecting their next destination. The original carried supplies between bases but did not unload or regenerate them; no artificial unloading is added here.

Combat starts from fresh identified native group perception within 400 metres of a surviving convoy vehicle or a delivered HQ sighting. Mounted group origins are not used for this distance, because native groups can retain their original spawn position. Infantry dismounts, approaches the left and right flanks, then searches those sectors. Armed escorts provide cover while the ammo truck withdraws; the troop truck waits until the passengers have dismounted and cleared it by 25 metres. Convoy vehicles slow to 8 km/h within 45 metres of their fit dismounted teams and restore cruising speed for travel. Contact-driven tactical orders refresh no more often than every thirty seconds and only after the contact moves at least forty metres; unchanged sightings retain the existing manoeuvres. Combat and boarding suspend column travel, and surviving vehicles regroup before resuming. Still-mounted infantry receives at most six dismount retries, ten seconds apart, to recover from busy doors or a braking truck. Native boarding waypoints require all surviving members and use a 100-metre approach radius; actual compartment membership determines readiness. Crew retention suppresses both group and individual abandonment priorities only for the original mounted vehicle crew and releases on critical damage or drivetrain failure, allowing native emergency abandonment.

After three minutes without a fresh contact, the teams reboard under escort cover. While contact is lost, each team can make two additional sweeps around the last observed position, on opposite sides of the original approach. A sweep requires the leader to reach the preceding search sector; a team still travelling or dismounting keeps its orders. Checks run at most once every 45 seconds. New sightings can redirect the hunt, while replayed reports cannot restart it. Failed terrain placement or waypoint allocation preserves existing flank orders. A new contact interrupts boarding. While soldiers approach or board, their native orders are preserved. A team with no approach or seat progress for thirty seconds can receive up to three boarding retries, with one tick between cancellation and reissue so native reservations can settle. A five-minute hard deadline releases genuinely stranded survivors and lets the remaining vehicles continue. A lost troop truck releases the infantry. Player capture stops convoy control permanently, preserving the actors and loot.

## Validation

`tests/test_convoy_column.py` executes the production spacing, stable-target, physical-arrival, leader-promotion, supply-ownership and stuck-recovery controller against native-boundary doubles. `tests/test_supply_convoys.py` executes production startup, base selection, arrival, circuit timing, contact freshness and perception boundaries, scoped crew-abandonment priorities, combat quiet time, boarding interruption, timeout and truck-loss policies. The receipt tests cover all eight groups and configured fleets through twenty convoys, including no replacement after losses. Existing dispatch, native seat allocation, cargo, HQ radio and force-ledger regressions remain in the main check suite.

`tools/headless_workbench.py --project chat --smoke supply-convoys --rounds 1 --timeout 900` exercises production automatic startup and physical AI in an isolated Workbench profile. Its final controlled contact explicitly tests native dismount/reboarding rather than claiming that an injected report proves perception. Remote-client replication and twenty-convoy performance require dedicated-server testing. Earlier one-convoy evidence in `convoy-migration.md` and `convoy-startup.md` remains historical evidence for those earlier sources.

The legacy `convoy` and `hq-memory` Workbench smoke fixtures explicitly select their previous single-convoy controller under `WORKBENCH` and `errSmoke=1`, preserving those fixtures' existing assertions. Normal play, ordinary Workbench use, and the `supply-convoys` fixture use the full configured fleet.

### Bounded current-source observation — 3 October 2026

The separate opt-in `--project chat --smoke supply-travel --rounds 1 --timeout 480` fixture watches the first naturally ready production convoy. It gives automatic admission 120 seconds, then fixes a 180-second travel window. All six original vehicles must move at least twenty metres from their first-ready positions while exact crew, driver seats, eight force records and two original infantry rosters remain valid. It never substitutes another convoy or renews a deadline. The scripted admitted observer alone is damage-protected; Stop restores its prior flag. Enemy perception, force budgets, routes and radio orders remain ordinary. The older full-fleet `supply-convoys` fixture is unchanged.

The [archived current run](evidence/native-2026-10-03-supply-travel/report.json) **fails** that bounded movement requirement: slots 0, 1 and 5 crossed twenty metres; slots 2, 3 and 4 did not before expiry. The production task was ready, not stopped, and in fighting state; the journal records combat entry, which suspends ordinary column travel. No original-identity validation failed before the terminal deadline. This does not establish a driving defect or qualify all-six travel, tactics, boarding, interception or a complete route. No test report/contact was injected. [Review, fixed scope and regression evidence](evidence/supply-travel-2026-10-03/review.json).

The historical September21 claim below is preserved as history. Its cited raw log/report files were not available during the October3 audit, so it cannot independently qualify current source or replace the retained failed result above.

### Local native result — 2026-09-21

`/tmp/erri-supply-native10/logs/logs_2026-09-21_16-50-45` completed one `supply-convoys` smoke round with 36 common smoke assertions, no script/runtime failures, unchanged launch sources, and confirmed runner cleanup. The supply fixture additionally verified three automatically started convoys (18 vehicles, 75 original soldiers), exact ledger admission, 174 successful cargo insertions matched to physical inventory, all 18 vehicles driving at least 20 metres, both seven-person teams dismounting and reboarding, and the original troop truck driving the next base leg after the normal pause. The contact and expiry of the preceding trip deadline were explicitly injected test inputs; startup, native AI, seating, cargo, the pause and subsequent driving remained production-owned. RHS content was disabled in this isolated fixture, while its installed dependencies remained loaded.

Launch source fingerprint: `380aec8a078825b165593fc4445b603f80b5d1ec51360c018d34973d65302b62`. Raw logs remain outside the repository. Strict engine qualification still fails on nine pre-existing dependency errors: four RHS/WCS localization GUID errors and five inherited vehicle-catalog keyword errors (`SlidingTrackMaterial`/`Parent`). This is a successful convoy smoke scenario, not a clean-engine or multiplayer qualification.

`python3 tools/check.py` passed for this production source; the additional bounded-retry regression also passed afterward. Earlier native iterations exposed partial dismounts, premature healthy-crew abandonment and a crowded boarding approach; the final source contains the bounded exit retries, scoped group/individual priority guards and widened native boarding approach validated above.


## Shared-budget startup diagnostics (30 September 2026)

The configured count is a maximum startup allowance, not a guaranteed number of
convoys. Existing garrisons and support soldiers share the same body ceiling. With
the default three-convoy setting, that ceiling is 135 and each new convoy needs
25 available bodies. At 108 committed bodies one convoy fits; at 112 it does not.
The allocator tests exercise both cases without changing the limit or refunding
consumed receipts.

Convoy status now shows committed bodies, ceiling and per-convoy requirement.
Failed startup distinguishes force-admission waits, missing road approaches,
blocked formations and insufficient body/formation capacity. The journal records
reason changes once, keeps identical five-second retries quiet, and reports the
actual last reason when the existing 120-attempt cap is reached. A success clears
the failure-message latch. Spawn timing, formation limits and finite stock are
unchanged.

The [first alarm-hearing run](evidence/native-2026-09-30-alarm-hearing-initial/report.json)
incidentally observed one original convoy followed by a native journal refusal at
**134/135 committed bodies, 25 required**. That is direct evidence for the reported
budget boundary, not qualification of a full three-convoy fleet. Earlier zero/
one-convoy runs lacked this live diagnostic; reconstructing their logs suggested
competition with other forces but did not prove every failed survey's cause.


## Skip impossible new-body terrain surveys (1 October 2026)

Automatic startup now checks the original source's body allowance before querying
road approaches or formation geometry. A new convoy that cannot fit the current
shared body budget does no terrain/world survey; the existing five-second retry,
120-attempt ceiling and change-only journal remain. This removes demonstrated
unnecessary native queries, but is not a measured FPS improvement.

The query preserves existing receipt reuse. If 108 bodies are committed, reserving
25 leaves 133; a failed road preflight may retain that unconsumed receipt. Its next
attempt must reuse the same reservation, rather than add 25 a second time and
refuse. Only new sources add their planned bodies in this early check. Original
Reserve and Consume remain authoritative for all body, formation and one-use
limits, including capacity changes after the early check. No refund, extra convoy
or replacement stock was added.

The actual pool accounting and startup methods execute together in the regression.
The preceding StartOne fails its zero-survey assertion; the corrected version
passes, including the 108-to-133 retry, exact-limit admission, later growth to 136,
consumed-receipt refusal and the unchanged bounded cadence. Independent review
caught the double-counting hazard before integration.


## Finite initial mounted stock (1 October 2026)

The supply convoy captures the exact magazines originally installed in its own mounted weapons after admission and before its first weapon-cargo request. It retains the original root, gun, mount, muzzle, loaded magazine, slots and actual prefab. Delayed issuance revalidates those identities, the original crew, receipt and existing HQ binding. Replacements and loose/projectile defaults cannot provide stock types; unsupported or incomplete installations are skipped.

The existing random weapon ammunition batch has priority. Remaining allowance can request two magazines per eligible mounted type, at most eight types overall, once only. Extra requests share the 96-ammunition-attempt and 128-callback limits, and reserve conservative room using the inventory snapshot before primary magazine requests: existing magazines plus attempts must fit 96, and existing items plus attempts must fit 128. If an original weapon callback is still unresolved after its deadline, mounted extras are omitted because a later completion could invalidate that snapshot. Failed insertions consume their attempt; there is no retry or refill. Resupply waits for the same complete callback set before freezing actual stock identities.

The source tests execute the actual seed capture/revalidation, one-shot issuance, HQ ownership lookup and stock barrier with controlled native boundaries. They cover alternate loaded prefabs, stale/replaced components, physical headroom, callback timeout/refusal, inline callbacks and the existing infantry priority. This initial-stock change does not implement a mounted transfer or prove a soldier can reach and service a turret.

The hidden/muted native run completes 34 assertions and one eligibility-only round with zero script/runtime failures. The production journal records two initial mounted-magazine requests after 48 primary requests. The read-only diagnostic finds a real 100-round PKM box in the original truck, with the same prefab as the original loaded magazine. `CanSwapItemStorages` returns true once, and both original slots remain unchanged. No original soldier is on foot at the required location; this proves neither physical access nor a transfer. The 13 known installed-resource errors retain the strict failed verdict. Cleanup and unchanged source/external inputs are confirmed. [Native report](evidence/native-2026-10-01-mounted-initial-stock/report.json).


## Optional native mine-stock check (1 October 2026)

`tools/headless_workbench.py --mine-stock` is restricted to Chat `mounted-ammo`, one round and at least 360 seconds, and cannot combine with the swap or courier variants. It uses the established hidden/muted runtime. The observer pins the first ordinarily eligible convoy and its initial optional batch within the existing fixed deadline. It requires one or two exact inactive PMN4s from successful startup callbacks, reciprocal original-truck custody and settled primary cargo callbacks. The same identities and custody must survive the existing natural mounted-ammunition radio proof. It never creates, moves, replaces or arms an item.

The first [native check](evidence/native-2026-10-01-convoy-mine-stock/report.json) stops after 39 passing assertions at the earlier ammunition-truck snapshot completeness check. The mine assertions are not reached; insertion, transfer and placement remain unqualified. Both explicit test failures and thirteen underlying installed-resource errors are retained. All current registered regression programs pass, including actual candidate/callback/custody/snapshot methods and CLI scope/exclusion checks. [Independent review and preservation](evidence/convoy-mine-native-2026-10-01/review.json).


## Loaded-truck traversal correction and mine-stock evidence (1 October 2026)

The follow-up diagnostic reproduced the earlier failure: the original loaded truck filled the mounted sampler's shared 128-node queue while only 59 nodes entered its allowed hierarchy. Excluded deposit cargo was consuming the same allowance. The sampler now permits 128 structural nodes and 128 known cargo roots, with a hard 256-identity queue bound. Crew and unknown storage consume structural allowance; character/cargo subtrees remain pruned, and cycles, ambiguity or any overflow still mark the observation incomplete.

The [corrected native run](evidence/native-2026-10-01-mounted-traversal-fixed/report.json) completes 202 assertions and one fixture round. Its automatically deployed original truck returns a complete zero-mounted-weapon snapshot, contains two exact callback-proved inactive PMN4s, and retains both identities and reciprocal inventory custody through real mounted-ammunition radio delivery. The same 64 primary callbacks remain settled and unchanged. Zero script/runtime failures and thirteen retained installed-resource errors are recorded, with unchanged source/external inputs and confirmed hidden/muted cleanup.

This is initial physical stock evidence for one convoy. The fixture neither moves nor arms a mine; walking rendezvous, transfer, deployment, three-convoy reliability and real multiplayer remain unqualified. The original failed diagnostic and source regressions are retained in the [review](evidence/mounted-traversal-2026-10-01/review.json).

2026-10-04 hunt verification: actual-method regressions cover opposing approach geometry, transactional waypoint allocation, arrival-gated two-step continuation, search cadence/cap, replay rejection and three-minute quiet expiry. An isolated Nogova dedicated fixture injected one contact into an ordinarily spawned convoy and observed both original teams physically dismount with native flank/search orders. It did not run the complete three-minute hunt/reboard cycle or prove organic perception. All 314 registered repository checks passed. Evidence: [review](evidence/hunter-search-2026-10-04/review.json).