Colony Bootstrap

Colony bootstrap executes an exact acquisition authorized by the operator. It does not select candidates or decide expansion timing.

Operator workflow

debug.colonize("E48N14", "E48N13")
debug.colonization("E48N14")
debug.cancelColonization("E48N14")

The start command validates both room names, visible ownership of the bootstrapper, distinct rooms, target non-ownership, and duplicate or conflicting active operations. Its console invocation is the authorization. Cancellation is terminal and idempotent; a later attempt receives a new operation sequence.

Ownership and memory

The durable record lives at Memory.rooms[bootstrapper].colonization.operations[operationId]. It contains the target, console attribution, controller observations, assignments, spawn plan, blocker, transition timestamps, terminal state, and at most twenty recent events. Empty or older room memory initializes lazily.

Before handoff the bootstrapper owns every operation decision. Colonizers and pioneers keep memory.homeRoom set to the bootstrapper even while physically in the target. CIA may provide remembered facts for inspection but never starts or controls the operation.

Lifecycle

The deterministic phases are:

surveying -> contesting-controller -> claiming -> securing-controller
-> planning-bootstrap -> clearing-spawn-site -> placing-spawn
-> building-spawn -> establishing-local-workforce -> handoff -> complete

Phases may skip forward when the world already satisfies their objective. Visibility loss, GCL capacity, safe mode, controller cooldown, missing creeps, spawn energy/busy state, and construction legality are blockers, not terminal failures. They are reevaluated without a resume command.

A CLAIM/MOVE colonizer attacks a foreign owner or reservation before claiming a neutral controller. It is replaced while acquisition demand remains. Once the controller is ours, two parent-owned pioneer builders fill their carry from target-room containers, ruins, tombstones, or dropped energy when available, fall back to local harvesting until full, and then build until empty. They also prioritize downgrade protection below 5,000 ticks and clear a recorded blocker. Pioneer losses retain bounded replacement demand. Pioneer actions write current colonyBootstrap intents for live diagnosis.

First spawn and selective clearance

The spawn tile is selected once from visible terrain. Candidates avoid walls, exits, and controller/source/mineral exclusion ranges; deterministic scoring balances controller and source distance and strongly prefers an empty tile. The position remains stable across visibility loss and missing sites. Site creation is deduplicated and a vanished site is recreated at the same position.

Dismantling is limited to a non-road structure occupying the recorded first-spawn tile, or a foreign spawn that exhausts the claimed room's RCL spawn limit and directly causes ERR_RCL_NOT_ENOUGH. Useful roads and all unrelated containers and room structures are preserved. This milestone does not implement room cleanup or a general combat campaign.

Ordinary builders select only owned construction sites, and hauler delivery validates ownership for spawns, extensions, towers, storage, and links. Foreign sites and foreign energy structures are therefore never treated as colony work.

Handoff

Handoff requires an owned target controller, the completed planned spawn, and a recent ordinary target RoomManager execution. That proves target room memory is initialized and its spawn can participate in normal local workforce demand. The operation completes once, parent acquisition and pioneer demand become zero, and surviving pioneers become ordinary target-owned builders. The historical record remains inspectable. Storage, mature infrastructure, terminals, and inter-colony balancing are not handoff requirements.

After handoff, a stranded-colony recovery guard covers the gap before the first local energy worker exists. Target-owned builders use normal local withdrawal or harvest fallback, then fill owned spawn/extension capacity to 300 energy. The guard stops as soon as a non-spawning local harvester or hauler exists, so ordinary builder policy resumes without a permanent inter-colony assignment.

CPU and verification

Active operations are evaluated once per bootstrapper tick within the existing remoteOperations room CPU section. The full spawn-tile scan occurs only when a visible claimed target has no stored plan. While an active target has no owned spawn, the main loop defers its ordinary RoomManager; the bootstrapper remains the sole policy owner, avoiding mature economy, infrastructure, logistics, and spawn-planning work before handoff. The ordinary manager automatically resumes as soon as an owned spawn exists, allowing the existing handoff proof to run.

Pioneers retain a valid reusable-energy target and local source in creep memory. When no container, ruin, tombstone, or dropped energy is available, that broad discovery is retried every 25 ticks rather than every tick; cached movement paths continue between retries. Creep execution remains bounded by the small requested workforce, and event history is capped.

Run:

npm run verify:colony-bootstrap
npm run check

Autonomous candidate evaluation, expansion petitions, dormancy inference, strategic timing, generalized Operations, military planning, and inter-colony resource policy remain deferred.