Navigation & pathfinding — recipes (loop tier)

On-demand recipes (37). Trigger→action heuristics; pull the relevant one when its situation arises.

1. Block ALL interactive-object cells in A* and path to a neighbor + bump

loop

Routing A* transit THROUGH interactive-object cells (extractors, hubs, junctions, gear stations) causes catastrophic stuck loops: moving into an oxygen_extractor triggers its on-use handler and consumes the move WITHOUT displacing the agent, so 'successful' moves never change position (observed stuck 5875 ticks). Excluding only the target's own cell is insufficient because the path can route through OTHER intervening objects. Fix: add ALL solid interactive-object cells (plus currently-visible non-self agents) to the A* blocked set at path-COMPUTATION time only -- in alpha_cog _navigate_astar the blocked set = confirmed walls + interactive_cells + visible agent positions -- but do NOT remove them from the passable-cells topology, because those cells are walkable after interaction and an agent standing on one must be able to leave. EXEMPT the goal cell from the blocked set so A* can still path toward an occupied target. Then path to a cardinal NEIGHBOR via a multi-goal A* (astar_path_to_adjacent terminating when any cardinal neighbor is reached, target excluded) and emit ONE directional bump to interact (the move fails as a move but triggers the object's handler); the empty/already-adjacent path MUST fall through to that bump or the agent does nothing. This dropped max stuck time from 5875 to 11 ticks. When a shared helper blocks ALL tagged cells (including agents), strip agent tags explicitly before pathing through transient obstacles. After the bump, clear ALL cached path state so the next tick re-evaluates fresh. To add a new avoidance (danger cells), extend the blocked-set construction, not the A* heuristic. _{sources: opencode:ses_1ff24a65cffeJSXwU2v6gcXbHQ, opencode:ses_1ffaf088affeFNFwHh4HO98LEn, opencode:ses_1ffa96717ffeq1J1GeKsUpSp3k, opencode:ses_2042c1ff1ffefETImBU5n4D43k (+7)}

2. Two-tier waypoint graph: strategic A* over waypoints, tactical A* per tick

loop

Advance the path-following index only when the agent's position matches the expected next cell (confirmed via the simulator's last-move-succeeded signal); on a failed move, keep position and index unchanged and retry, preventing path corruption and letting transient agent-blocking resolve. Make A* agent-aware: add currently-visible peer positions to the blocked set as TEMPORARY obstacles for that one computation (never permanent walls, never guessed unseen positions) -- without this A* routes through teammate-occupied cells and agents burn 26-54% of ticks failing to move at chokepoints. On a failed move distinguish a wall collision (record the cell, replan immediately) from a transient agent blocker (only force a replan after 2 consecutive blocks). Critical: retry-then-sidestep-then-replan CANNOT break a chokepoint loop if the replan is blocker-UNAWARE -- it recomputes the same path through the blocked cell and oscillates. Working recipe: retry up to 2 ticks, deterministic right-relative sidestep (N->E->S->W) so two head-on agents split with no coordination, then replan FROM THE NEW POSITION with the blocker added. _{sources: opencode:ses_204495c66ffe7u8C8SOiEX1zdH, claude-code:25488cd9-61d5-4231-bd87-e2744b6db043, alpha_cog/AGENTS.md, archive/cogames_playground/alpha_cog/docs/astar-navigation-design.md (+1)}

3. Detect oscillation as its own failure class with NO distance gate

loop · negative result

Oscillation is a distinct failure from slow progress and from frozen-against-blocker, and a detector based purely on 'position unchanged for N ticks' is too weak -- agents oscillate while CHANGING position every tick (a trapped aligner bounced between two cells; a miner's moves all succeeded yet it never reached its goal). Run THREE detectors in parallel over a position ring buffer: (1) position-stuck (position unchanged ~8 ticks) catches frozen-against-blocker; (2) pacing/cycle-stuck -- position-history cycle matching against period-2/3/4 cycles over a ~12-tick buffer (or confined to <=2 unique cells over the window), firing after ~5 cycles / ~10 ticks with NO distance gate -- catches A->B->A->B oscillation, which moves every tick (X changes, Manhattan distance dips each pass) and resets any per-tick stall counter; (3) axial/distance-staleness -- distance-to-target over a rolling ~80-120 tick buffer stops decreasing -- catches moving-but-not-progressing toward a far goal and distinguishes a true trap from a wall-impeded agent making legitimate slow progress. A single detector misses the others. Detect lack of progress TOWARD THE GOAL over a window, not per-tick position change. Axial-stuck is target-shaped, so keep it OUT of the auto-tabu/auto-blacklist wrapper (callers usually want to re-route to the same goal); only position- and pacing-stuck should auto-blacklist the target. When a gated mechanism 'never fires,' verify the GATE is not the problem before concluding the mechanism is unneeded; gate unsticking on 'about to arrive' (very small distance AND a viable path exists), not a single distance threshold. _{sources: opencode:ses_206bfd18dffe1hUfJBOccuaLDC, alpha_cog/AGENTS.md, archive/cogames_playground/alpha_cog/docs/paper/paper.md, archive/cogames_playground/alpha_cog/docs/temporal-memory-design.md (+6)}

4. Stuck recovery must DISPLACE the agent; gate by distance band + second-stuck + TTL blacklist

loop

For oscillation/stuck recovery the recovery ACTION is the bottleneck, not detection -- a correct distance-to-target detector still regresses if the action disrupts productive agents. Soft recovery (rotating heading 180 degrees, or a single-tick nudge) is DEAD against greedy-nav oscillation: every soft-rotation arm produced worst-in-class A/B means (~-1.50) because greedy nav just picks a different oscillation axis. What works is a bounded ~5-tick blind explore burst that physically DISPLACES the agent ~3-5 cells, changing its observation window enough to re-pick a different target; design recovery around how much spatial displacement changes the agent's information state. Gating: fire the burst only when the agent is >10 cells from its target (the distance gate suppresses false positives near the target, wall-impeded but legitimately close). The >10-cell gate + 5-tick burst turned an unshippable detector into V7: 34W/8T/8L +1.86 mean vs V6 on 50 seeds at 10k, single-seed deltas up to +7.95/+4.73. Use second-stuck gating: on the FIRST stuck use the cheap blind-explore; only on a SECOND stuck on the SAME target trigger aggressive blacklist+re-pick, so 'star seeds' (where staying stuck on the best target beats a worse one) don't collapse. The blacklist must PERSIST with a TTL (~60 ticks = window/2 worked; window/4 ~30 ticks oscillated and was much worse; 1-tick is useless). On re-pick, accept an alternative only if no farther than the stuck target (+0.89 -> +1.38). Shipped as V8/H048: 30W/11T/9L +2.23 mean, the largest single-flag improvement in the project. Refinement: an UNCONDITIONAL displacement burst on every second-stuck repaired three loss-tail seeds but catastrophically regressed two top-win seeds; naive distance-THRESHOLD gating was too coarse (D20/D25/D30 byte-identical), and only a tight distance BAND (30<=stuck_dist<=35) preserved the repairs while skipping both known large-regression triggers (V9/H058, 4W/44T/2L +0.345). Note miners keep the unconditional V7 explore because deficit concentration is load-bearing for that role. _{sources: alpha_cog/AGENTS.md, archive/cogames_playground/alpha_cog/experiments/notebook/hypotheses/H, archive/cogames_playground/alpha_cog/docs/cogs-v-clips-strategy.md, archive/cogames_playground/alpha_cog/docs/experiment-axes.md (+10)}

5. Use sticky targets with progress invalidation to stop per-tick re-rank flips

loop · negative result

Goal oscillation between two near-equidistant targets comes from a target-selector that re-runs best-pick (min) fresh every tick with no memory; each flip resets the goal, wipes the A* cache, forces a replan, and yields net-zero progress (one trace: 23 goal runs / 22 flips over ~638 ticks), and it is especially wasteful under momentum (Crewrift) where the agent slides back and forth. Diagnose by logging the chosen goal per tick and counting distinct goal 'runs' -- rapid flipping is the signature, distinct from wall-stuck or coordinate bugs. Fix with a STICKY target: commit to the chosen target for a minimum window (e.g. swgy_targets/progress_window=12, or TASK_COMMIT_TICKS=48 ~2s at 24 FPS) and snap the destination exactly once (guard with a flag like fleeCoverSet). CRITICAL: a sticky target WITHOUT progress invalidation traps the agent forever on an unreachable target -- always pair it with a progress check that drops it after N ticks of no strictly-closer distance; the progress half is the half that matters. When you do allow re-evaluation, gate the switch on a shouldSwitch predicate that resists oscillation -- switch only on a legitimate reason (target resolved/vanished) or a strict objective UPGRADE (higher value/tier via a fixed priority ladder, e.g. visible on-screen icons beat radar pointers to offscreen tasks) OR a same-tier candidate significantly closer (distance < current * 0.5, a named constant); a bare 'closest wins' thrashes. Throttle re-evaluation to every N ticks (store last re-eval tick), keep commit-window length and re-eval period as two separate documented constants, and scope re-selection to the navigation/approach phase only, never while actively executing the objective (Hold/Confirm). Reuse the existing mode object when the incoming directive still matches_directive so mode-local state (phase, target commitment, waypoint index) is not cleared. _{sources: claude-code:0919285d-1374-4827-b596-6e7107d95526, codex:019e0392-8fae-7b13-80e7-525df2e3de2f, opencode:ses_1fc91aa93ffeMtKpKXfQ6IA01y, opencode:ses_21eb30b06ffeL6353Ov27zhdA1 (+7)}

6. Treat an empty path as UNREACHABLE; never silently emit zero or wall-steer

loop · negative result

A pathfinder that rejects an impassable goal and returns an empty path is a latent DEADLOCK -- if findPath early-returns [] when the goal fails passability and movement is guarded by 'if path.len > 0', the bot emits zero movement forever. Equally bad is collapsing an empty route into 'drive straight at the goal' or a greedy direct-steering fallback: it masks the failed plan while bouncing off walls. Always pair 'reject impassable goal' with EITHER a fix to the plan/graph OR a safe fallback -- and the good fallback when A* returns no path (all known routes walled off) is a DIRECTED explore toward the goal: move in the target's general direction preferring unseen cells, filling spatial memory until a path becomes discoverable or the window sees the target, and let anti-stuck jiggle handle walls (a sibling policy, modulabot/policies/base.py, survived a map a non-fallback policy was paralyzed on precisely because of this -- a degraded-but-moving behavior beats a clean-but-frozen one). Never emit silent zero-movement and never an unsignalled wall-drive: emit an explicit stall/replan signal and give stuck/stalled tasks a status/progress channel back to the policy (not just (memory_update, action)) so it can trigger re-pathing or a strategy change; without it, escalation is impossible. _{sources: opencode:ses_20b7f9058ffeA36rC0WbRQYP6f, opencode:ses_20ba27dfcffetaDrq3FK2cz523, opencode:ses_204495c66ffe7u8C8SOiEX1zdH, codex:019e7174-3079-7351-b8ea-b1bfcb917ff4 (+2)}

7. Fix waypoint-follower wiggle in selection/snap, not the steering symptom

loop · negative result · ⚠ session-derived, unverified

When a waypoint-follower wiggles in one spot, the root cause is usually nearest-waypoint selection using Manhattan/Euclidean distance only, IGNORING walkability, so it picks a waypoint just across a wall; fix the assignment (reachable snap point, or walkability/line-of-sight-aware nearest-waypoint), not the steering. Snap a follower to the nearest path SEGMENT (Euclidean projection) and compute progress as interpolated distance ALONG the segment, not the nearest VERTEX: after DP simplification consecutive vertices can be far apart (a 91px gap with a 30px snap radius), so a bot midway along a long segment is beyond every vertex's snap radius, the 'out of snap range' branch fires, a resync steers it to the segment start, and it oscillates forever; fix this in the perception/lookahead layer (segment-aware snap plus interpolated lookahead in selectLookahead). Path-follow oscillation (distinct from wall-stuck) also comes from a large lookahead combined with localization jitter and aggressive waypoint trimming on a path computed once and never recomputed: with PathLookahead=18 near a corridor turn, trim logic (dropping steps within distance<=2) consumed nearby waypoints so the lookahead pointed PAST the turn across a wall and steering reversed. Fix: (1) shrink lookahead (18->4 or ~8) so steering hugs the A* corridor through turns; (2) periodically recompute the path (every ~24 ticks) so jitter-corrupted trim state self-corrects; (3) add a progress-stall replan if distance-to-goal hasn't decreased in ~48 ticks. Separately, staccato (move-pause-move) means the bot runs out of steering target between expensive replans -- DECOUPLE recompute cadence from steering-point selection: throttle A* to the replan interval but every tick advance a moving lookahead point along the already-stored path. Watch for a 'dead zone' (a walkable region with NO waypoint) which strands any agent that replans there; add a waypoint with edges and re-bake. Audit that tuning constants are read at their use site (a JIGGLE_TICKS knob was silently overridden by a hard-coded literal). _{sources: opencode:ses_1fb1d9989ffeYXiew23WUqo2hw, codex:019e00d7-d212-73a2-8b2e-569efc00f028, opencode:ses_1ff325156ffei2UiDygaVOZo5O, opencode:ses_21a708a4dffeBXpeHY15fnGABP (+1)}

8. Multi-agent navigation: stagger doorway approaches and break symmetry on rendezvous

loop · negative result

When several agents must approach the same one-cell station doorway (opening rush or shared equip), pass an approach_index / stable approach slot so they target different station-adjacent cells, and stage overflow agents on diagonal cells until a route opens -- this prevents duplicates from blocking each other before bumping the station. Two cooperating agents running the same greedy policy can defeat a shared goal (both key partners independently 'created a new whisper' when a partner was nearby, splitting into two solo rooms that never merge): break symmetry with deterministic opener-vs-requester roles for known pairs. In FOG-OF-WAR games rendezvous is the binding bottleneck: across Persephone/Eurydice self-play, agents learned roles and started many probes (72 targets, 41 probes) yet full 10-agent live runs DREW because only ~6 probes completed and 34 hit initiate_timeout with ZERO server-confirmed joins -- the minimap doesn't show whisper status and speech bubbles are visible only within ~30-40px, so by the time an approacher sees a creator's bubble the creator has often timed out (~15s), yielding separate solo whispers; a fixed-coordinate exchange protocol (requesters pulse near a key whisper while openers run blind GRANT windows) ALSO failed across eight server logs. What works is the 'stupid meetup': each ally shouts a FIXED coordinate (e.g. 'meet at 50 50'), all walk there, first to arrive opens a whisper others auto-join -- converging on a known point beats mutual target-chasing (each chasing the other's last-seen position never converged; the minimap self-dot overwrites others). Design coordination around visibility/timing (linger longer, approach to within bubble-visible range BEFORE deciding to create vs join, announce intent on a global channel), not more perception fixes. _{sources: codex:019e28a2-f81d-79b1-a7f7-5f6583c280f1, archive/cogames_playground/bulbacog/designs/STRATEGY_V2.md, archive/cogames_playground/docs/plans/bop-it-localization-equip.md, codex:019e181f-6289-7332-9837-05f0e9cadded (+5)}

9. An energy/cost-stalled failed move is indistinguishable from a wall block; detect intended!=executed and retry

loop · see related: U0611 (other tier)

In a coworld sim where movement has a resource cost (energy) and the engine executes a noop when the cost can't be paid, a stalled failed move is INDISTINGUISHABLE from a wall/agent block in the executed-action token — a navigator that ignores the resource will misread exhaustion as obstruction and thrash. Rather than building heavy resource-management logic, detect the failure (intended move != executed action) and RETRY up to a small cap (e.g. 3), since agents typically auto-regenerate the resource each tick. Trigger retreat on distance-aware vitals (e.g. retreat if a survivability resource < distance-to-safety + margin) and only resource regen that is NOT effectively instant near friendly structure needs a rest ceiling; resource-aware behavior (resting to refill instead of burning failed-move ticks, biasing targets toward regen zones) is a large untapped navigation lever. _{sources: archive/cogames_playground/alpha_cog/docs/cogs-v-clips-rules.md, archive/cogames_playground/bulbacog/COGS_V_CLIPS.md, opencode:ses_219ac1095fferkumOQK8Ph6LTk, optimizers/.cursor/skills/scripted-navigation/SKILL.md (+2)}

10. Exploration: deterministic coverage routes, share map before adding scouts

loop · negative result

Do NOT separate exploration from the productive objective into distinct modes, and do NOT use reactive frontier exploration that re-decides targets each tick: a frontier-picker that only targets cells adjacent to unexplored space keeps agents trapped in a small bubble near spawn (e.g. ~6% of an 88x88 map after 2000 ticks). UNIFY explore with the objective and assign deterministic space-filling/patrol routes — move outward in a boustrophedon/quadrant-snake and capture/interact en route. For pure coverage, snake-scan in strips of width = one observation diameter (e.g. 12 for a radius-6, 13x13 window): assign each agent a quadrant and walk it boustrophedon, giving full coverage in O(area/observation_width) with overlapping vision. For coordinated exploration WITHOUT shared memory, assign exits/directions at the pre-match staging point where agents are co-located (each picks the nearest base exit, tie-broken by agent ID, then spirals outward) instead of relying on not-yet-filled spatial memory; bias the initial direction toward likely structure. NEGATIVE RESULT: do NOT add a scout role (or have producers 'explore') when there is no shared team map — discoveries can't propagate; either make map knowledge shareable first (e.g. a talk channel when agents meet) or fold that body into another role. _{sources: claude-code:19ac76fb-7c48-44a1-81dd-eebcbdc9c19c, claude-code:27984094-3b9e-4e67-92c5-da2a61ceb32a, archive/cogames_playground/bulbacog/designs/ALIGNER_SPIRAL.md, optimizers/.cursor/skills/scripted-navigation/SKILL.md (+2)}

11. Contention: precompute worst-case arrival; pickup full loads from known capacity

loop

When other agents contend for the same resource, replace fragile per-tick timing triggers with a worst-case precomputation: compute the maximum possible travel time, hardcode that buffer, and arrive early once — avoiding race conditions and simpler to reason about. For resource-pickup loops, compute how many items to take up front from a known capacity/maximum rather than the 'keep taking until the count stops incrementing' poll-until-no-change hack that causes wasteful round trips; let one carrier grab a full load in ONE greedy trip (strict fairness isn't worth the cost — one agent filling to capacity beats several making single-item trips). Use threshold comparisons (>=), never equality (== capacity), for quantized resource checks — e.g. a miner with capacity 44 mining in increments of 10 never hits exactly 44, so an '== full' deposit trigger silently never fires. A carrier that reaches a shared deposit with nothing to carry should wait one tile AWAY, not idle adjacent, because adjacent idling blocks other agents trying to deposit. _{sources: codex:019e9656-7cfc-7032-ae70-82b6dbc0a053, claude-code:19ac76fb-7c48-44a1-81dd-eebcbdc9c19c, claude-code:27984094-3b9e-4e67-92c5-da2a61ceb32a, archive/cogames_playground/bulbacog/designs/ALIGNER_SPIRAL.md}

12. Drive menu/cyclic navigation from perceived cursor with press cooldowns

loop

Menu navigation over a laggy client needs press cooldowns, not per-tick re-presses: a MenuNavigator pressed B to open a menu, but it took 2+ frames to appear so on the next cycle it still saw the default bar and pressed B again, toggling the menu closed -- after an open/navigate press, wait a fixed number of ticks for the UI to reflect it (or use a verified fixed sequence like B -> Right x3 -> Down x2 -> A when the layout is stable). Separate 'where the cursor is' from 'what button to press' and drive from the cursor READ from perception; only fall back to an internally-tracked cursor when perception cannot see it, and then advance the remembered index only on rising-edge ticks where a press actually fires (one per tick), or it desyncs. Navigate a cyclic selector (menu ring, L/R picker, U/D/L/R grid, or the voting cursor as a WRAPPED ring of playerCount+1 slots -- player slots plus a SKIP slot) by computing the SHORTER of the two cyclic distances and stepping that way (index 0 adjacent to N-1; for 8 voting players the worst case is 4 cursor moves); always-advance-one-way wastes step-limited actions. This needs the full ring order as a known constant -- ground it in the game's own spec (GAME_API.md), not an invented parallel ordering, and infer UI grid geometry from live counts (row = i // cols, col = i % cols, rows = ceil(count / cols)). Separately, maintain a self-position keyframe history (capped, skipping low-information corridor positions, exposed newest-first) so an agent can later truthfully report where it was and a deceiver is constrained to claim only locations it actually visited. _{sources: claude-code:3b14ac5a-1d66-4524-94c0-59a48466d223, codex:019e04ef-5a71-7851-8ea6-58a19f29b42f, codex:019e04f4-6a98-7553-bed7-caa92e6dd386, personal_cogs/among_them/guided_bot/MEETING_DESIGN.md (+2)}

13. Run A* over the full remembered map (not the obs window); it is cheap, so replan freely

loop

Navigation experiments confined to the agent's 13x13 (169-cell) observation window -- full BFS, biased BFS, territory-aware nav -- all regressed or were byte-identical, because within that tiny window greedy and BFS pick the same first step. Real gains require A* planning over ALL remembered passable cells (thousands by mid-game). Use a Manhattan heuristic (admissible/consistent for 4-connected grids) and treat unknown cells (not in the known-walls set) as PASSABLE so the planner routes through unexplored space; only known walls are permanent obstacles, and stuck-detection re-pathing handles undiscovered walls. This is cheap, not expensive: on an 88x88 grid A* costs roughly 5-20 calls per agent per 10000-tick episode, each well under 1ms with a Python heapq (Crewrift's denser graph is ~0.2ms/call), negligible against per-tick observation parsing. Replanning is therefore nearly free, so re-root the route at the agent's live position every ~8 ticks and whenever the goal changes; this is what eliminates residual approach-wedging at the destination. _{sources: archive/cogames_playground/alpha_cog/docs/astar-navigation-design.md, orpheus/DESIGN.md (Orpheus agent framework design), personal_labs/crewrift_lab/crewrift/crewborg/design.md}

14. Snap goals to passable cells and own grid<->world conversion in one module

loop · negative result · ⚠ session-derived, unverified

Always snap a navigation goal to a passable cell before handing it to the pathfinder: a projected target (e.g. a 'flee away from X' vector) can land inside a wall, A* returns empty, and the agent falls back to jittery greedy mode -- a snapToPassable on every computed goal removes that whole jitter/noop-lock class. When a coarse cell covers both floor and wall pixels, resolve toward the class the consumer least tolerates: apply WALL markings after FLOOR markings so a mixed cell becomes WALL, because a missed wall routes the planner into an obstacle. Have the planner return waypoints at the CENTER of each cell in WORLD coordinates and keep grid<->world conversion owned by the grid module (not duplicated in planner/steering); account for grid downsampling (multiply grid coords by the resolution factor, here ~2x, before A* validation) or off-by-resolution bugs make waypoints fail reachability for no apparent reason. Reject degenerate world dimensions (non-positive room_size from a bad/early frame) before building the grid, or you get a malformed grid and silent pathfinding failure. _{sources: claude-code:940b2eb9-3677-4c05-8754-c9cfa163f531, codex:019e031e-f7d3-7342-a7d9-96993bc91097, opencode:ses_20b7f9058ffeA36rC0WbRQYP6f, opencode:ses_20ba27dfcffetaDrq3FK2cz523 (+3)}

15. Replan A* only on meaningful events, and perturb inputs on a forced replan

loop

Re-plan a path only on meaningful events (target changed, wall discovered on the path, agent sidestepped off-path, path completed), NOT on transient agent-blocking or on observing new passable cells that don't affect the current path -- keeping the path stable across transient blocks avoids thrashing. CRITICAL corollary: a stall/replan timer that re-runs pathfinding with the SAME endpoints reproduces the same failure (an identical still-impassable goal returns an identical empty path), so any forced replan must perturb its inputs (exclude the previous endpoint, try a new target) or it is a no-op loop. For static-goal intents, cheap periodic re-planning every 4-10 ticks re-roots the path at the live position (the kill intent already replans A* every tick at 24Hz with sub-ms steps). _{sources: opencode:ses_1ff242847ffeVjz3nqsCxJnBZg, archive/cogames_playground/alpha_cog/docs/astar-navigation-design.md, opencode:ses_20b7f9058ffeA36rC0WbRQYP6f, optimizers/.cursor/skills/scripted-navigation/SKILL.md (+2)}

16. Advance path index on confirmed moves; distinguish wall vs agent blockers

loop

Advance the path-following index only when the agent's position matches the expected next cell (confirmed via the simulator's last-move-succeeded signal); on a failed move position and index stay unchanged and the agent retries, preventing path corruption and letting transient agent-blocking resolve by retry. On a FAILED move, distinguish causes: a wall collision records the failing cell into spatial.blocked_positions and clears/replans immediately; a transient agent blocker increments a counter and only forces a replan after 2 consecutive blocks (treating a teammate-blocked tick like a wall causes needless full replans). Handle two agents moving into each other with a deterministic right-relative sidestep after >2 blocked ticks (opposite-facing agents sidestep opposite ways and clear with no inter-agent coordination), not infinite retry which deadlocks. Give the act/navigation layer read access to the mode memory holding the path. _{sources: opencode:ses_204b02d32ffe2SDPUmF6liH6gS, opencode:ses_206bfd18dffe1hUfJBOccuaLDC, opencode:ses_1ff242847ffeVjz3nqsCxJnBZg, archive/cogames_playground/alpha_cog/docs/astar-navigation-design.md}

17. Make path simplification wall-aware and bounded inside the recursion

loop · ⚠ session-derived, unverified

Any geometric path simplifier (Douglas-Peucker) on a baked grid path MUST be wall-aware: plain DP collapses a polyline whenever intermediates are within tolerance of the straight start->end line, but a wall-hugging path can be sub-pixel-straight while the simplifying line cuts through a wall. Before collapsing, Bresenham-walk every pixel of the straight line against the walkability mask and force a subdivision if any pixel is non-walkable. Enforce the max-segment constraint INSIDE the recursion as an ordered decision -- (1) deviation > tolerance: split at worst point; (2) length > max: split at midpoint; (3) wall crossing: split at midpoint; (4) else collapse -- NOT as a post-process, because post-process interpolation invents synthetic coordinates not on the verified A* path that could cross walls. A long gap between consecutive waypoints starves a reactive follower (it drifts/sticks on long straights), so keep a max-distance-between-points constraint (e.g. 30px) while keeping real A* coordinates. Diagnostic: a baked edge cost equal to the exact Manhattan distance between endpoints despite known geometry between them is probably an edge cutting through a wall. _{sources: opencode:ses_1facc49fbffeVdd0R01vqH3sfz, opencode:ses_1fb1d9989ffeYXiew23WUqo2hw, opencode:ses_201972733ffexPIP9mq6yEDpqJ}

18. Steer momentum-aware in sims with velocity/friction, not sign-function

loop · negative result

When a sim has acceleration/velocity/carry/friction/collision (e.g. AmongThem, machina), sending a direction for one frame is NOT 'move one tile', and a greedy single-frame screen-space controller (dx,dy = target - center, press whichever axis is larger) ORBITS targets: pixel-perfect arrival flips the dominant axis, momentum carries the agent past, and it emits the reverse next frame (client-server-client latency worsens it). NEGATIVE RESULT: a pure sign-function controller with zero deadband and zero velocity awareness commits full input on a 1-pixel error, overshoots, reverses, oscillates every other tick. Follow a LOOKAHEAD waypoint (not the immediate next pixel) and steer momentum-aware: hold the direction far from the waypoint, COAST (no input) when velocity reaches target, BRAKE (press opposite) 1-2 ticks before a corner/overshoot, use a precise controller near the goal, plus a wider arrival deadband and/or directional hysteresis. Track velocity without sim internals by storing previous position and computing the frame-to-frame pixel delta, but only trust the sample when a movement button was actually held last tick (else reset velocity to zero). _{sources: codex:019e037c-5f9b-7ad1-8bf3-539709c4da15, opencode:ses_1fc949520ffe2UNDsOqbbL5T9a, opencode:ses_21fc35ba9ffeK5TywAEvVvlBBl, bitworld/among_them/players/SMART_BOT_GUIDE.md (+3)}

19. Drive to the true trigger point and gate range on the server's contract

loop · negative result · ⚠ session-derived, unverified

Drive the agent to the true target point (the trigger center) and REMOVE the arrival margin rather than tuning it: an 'arrived within N pixels' tolerance lets the agent start interacting while still outside the server's true trigger zone, so the interaction never registers and it loops approach-hold-fail-reapproach forever; widening the margin worsens it. Interaction/range checks must use the same body COLLISION POINT the server checks (the same point the server's interaction handler uses), not the body sprite placement coordinates — sprite coords make the agent stop and press while still out of server range, so the action silently fails. Align the client-side range gate to the server's collision-point contract. _{sources: claude-code:067e7439-cbd1-4b26-9b3f-d054bde3aa40, codex:019e7174-3079-7351-b8ea-b1bfcb917ff4}

20. Gate target switching on an evidence-tier ladder and re-validate latched targets

loop · negative result · ⚠ session-derived, unverified

Make target switching deliberate by gating on an evidence-tier ladder plus a distance ratio: switch only when the candidate is a HIGHER evidence tier (e.g. directly-confirmed > latched-from-a-prior-cue > geometry-guess) OR the same tier at less than HALF the current remaining distance. Record at EVERY lock site (initial selection, post-completion re-select, post-timeout re-select) which tier the locked target was acquired under, or the 'is the new candidate better' comparison silently uses wrong data. NEGATIVE RESULT: a tiered scheme can leak across tiers via a STALE LATCH — a mid-tier latch acquired when a transient cue pointed at a target persisted after the cue changed, bypassing a later exclusion check; re-validate a latched target against CURRENT perception each tick or it outlives the evidence that justified it. A speculative selection call that does NOT switch can pollute scratch state, so restore any fields it mutated (e.g. the selection-tier field) when the switch is rejected. Treat a directional cue vanishing without an agent action as a strong signal the target became visible/close, and hold the target through a brief grace window (~5 ticks). _{sources: opencode:ses_1fc91aa93ffeMtKpKXfQ6IA01y, opencode:ses_1fa63b520ffeQP7WMCZiDebllG}

21. Re-validate saved waypoints against memory and give pruned sets a wander recovery

loop · negative result · ⚠ session-derived, unverified

A strategy/mode layer must re-validate its own saved targets against spatial memory; relying on the action layer refusing to move is not enough. In crewrift PatrollingMode restored a saved waypoint on a far map-edge tile (87,43); after exploration learned it was unpathable, resolve_intent returned noop but patrol only advanced when within distance <=1, so it re-issued the impossible target forever -- skipping adjacent/impassable/unpathable waypoints and generating waypoints one tile inside the map border jumped seed-42 reward ~3.002 -> 7.6517 and junction gains 30 -> 64. NEGATIVE RESULTS: a policy that prunes its candidate set needs an explore/wander recovery for when the set empties (after exclusion pruned all targets, selectTarget() returned -1 and the bot sat idle for thousands of frames; a soft-exclusion fix raised 5/8 -> 7/8 but the last task stuck with no 'wander and re-check' to move where geometry re-includes it); and precondition-blocked modes must move TOWARD their enabling condition rather than surrendering, since a mode that signals mode-complete and returns idle when its precondition is unmet deadlocks the outer loop into re-selecting it every tick. _{sources: codex:019e1355-fd7e-77b2-8af2-3f93c0ae623a, opencode:ses_1fc4cec1bffe16bZw4eHP3SDBL, opencode:ses_1fa65507bffexDcakAPT4pHA1d}

22. Diagnose oscillation/camping from layer interaction, not the steering layer

loop · negative result · ⚠ session-derived, unverified

When a two-layer policy oscillates (outer strategy loop flip-flopping exploration targets while inner filtering looks fine), give the outer/strategy loop read access to the current mode and its parameters so it can see the state it is destabilizing; inner-loop directive filtering alone will not stop the outer loop thrashing. A parent navigation/probe mode can also sabotage a child handshake mode by mutating shared state underneath it (a probe_systematic mode pulsing entry buttons mid-handshake flipped a partner's view and broke the protocol), so suppress the outer loop's position/entry pulses while a sub-protocol needs a stable view. Conversely, a distance-penalty term in a station-scoring heuristic can DOMINATE all other terms and cause camping (a seeking patrol degenerated to camping the central high-traffic room) -- when a scoring heuristic produces degenerate stationary behavior, suspect one term is swamping the others. _{sources: claude-code:19ac76fb-7c48-44a1-81dd-eebcbdc9c19c, claude-code:aae25940-ade3-41bc-b817-517dc86ccebf, claude-code:91f456a7-41e8-4a89-98e9-44e379160b15}

23. Never overload one flag across modes; gate its meaning on the actual prior mode

loop · ⚠ session-derived, unverified

Never let one multipurpose boolean flag carry context-dependent meaning across unrelated mode strategies. A mode_stalled flag set by many modes (equipping, retreating, capturing, gathering) but read by the miner strategy as 'extractors depleted' regardless of which mode set it made a freshly-equipped miner wander ~15 ticks with direction=None. Gate the interpretation on the actual previous mode (read the current_mode_name fact) so the flag only means 'extractors depleted' when the prior mode was gathering. Relatedly, decouple the recency window for target SELECTION from the threshold for committing an ACTION: a longer window to move toward/consider a target, a stricter fresher signal (current-tick) to commit an irreversible action -- a single 72-tick window pressed B at stale targets while a current-tick-only check never pressed B because the triggering bubble was visible while approaching but not at arrival range. _{sources: claude-code:c6fec691-565c-406d-b7dd-37e9387f5475, claude-code:3b14ac5a-1d66-4524-94c0-59a48466d223}

24. Avoid danger at plan-time via finite A* cost; measure productive output per life

loop

When A* runs over remembered terrain with damaging enemy/danger zones, weight danger cells with a finite path-cost MULTIPLIER (a danger cell costs 3 path units instead of 1, or +10 additive -- not infinite block) so the planner prefers short detours but does not refuse enemy cells. In alpha_cog this ~3-line danger-cost change produced the largest tournament surprise gain (+5.79 mean; +0.178 in a narrower A/B) and a 7x reduction in score variance by keeping agents alive on high-value trips, because A* commits to a full plan at plan-time so intermediate positions do not flip every tick on a territory signal. CONFLICT/CAUTION: a separate result (E037) found navigation-level territory danger costs REGRESS, and an over-defensive danger_cost=3 made agents avoid contested territory instead of holding it (the worst replay had FEWER deaths than the best); V15's territory-weighted A* produced MORE deaths than uniform-cost yet was a net win (+27% junctions, +22% territory-time) because each life did more productive work. Net: territory-in-A* is not reliably positive -- measure deaths AND productive output per life per build, and do not reject a pathing change on a raw death-count regression. _{sources: codex:019e14de-cdca-7482-88fa-81716ee830ae, codex:019e19a7-8605-7992-9b28-cb4d2ca9132e, archive/cogames_playground/alpha_cog/docs/paper/paper.md, archive/cogames_playground/alpha_cog/experiments/notebook/submissions/ (+4)}

25. Defer A* to the single chosen target; rank candidates with cheap local geometry

loop · ⚠ session-derived, unverified · tool: frontier.py · see related: U0637 (other tier)

Per-tick target ranking that runs A* across many candidate cells is the dominant compute cost, not the cheaper objective math, so rank candidates with cheap local geometry (e.g. Manhattan distance, local connectivity) and defer the full A* to the final action resolver on the single chosen target. Running A* across all candidates every tick is a performance trap that can dominate the per-tick budget in a scripted game-policy navigator. _{sources: codex:019e147f-2fcd-7e83-93ab-fab57ce504b4, codex:019e1355-fd7e-77b2-8af2-3f93c0ae623a, codex:019e1357-835f-7442-bd46-7e911617621f}

26. Grid-aware exploration: prefer UNKNOWN cells with a fallback chain to blind sampling

loop · ⚠ session-derived, unverified

For exploratory navigation over an occupancy grid (cells UNKNOWN/FREE/WALL), treat UNKNOWN cells as first-choice waypoints since they are both optimistically traversable and information-rich. Use a fallback chain: reachable UNKNOWN cells first, then reachable FREE cells outside a recent-visit ring (track recently-walked cells and exclude them -- cheaper than global LRU and an obvious unit-test seam), then blind random-coordinate sampling with an A* reachability check. ALWAYS keep the blind fallback to cover cold-start (grid empty) and the case where every reachable cell is explored; a grid-aware heuristic with no fallback silently stalls the agent before the map is mapped. Reject collision-avoidance logic premised on an agent 'bumping into a wall it didn't see' when the agent perceives a fixed radius around itself (e.g. 13 tiles) and therefore already sees walls many tiles ahead -- any 'move forward, detect wall on failure' handling is wrong by construction. _{sources: codex:019e04ef-2bc1-7ad1-b86f-ce28b8fe1aeb, claude-code:19ac76fb-7c48-44a1-81dd-eebcbdc9c19c}

27. When play rules change, give the new capability its own intent and audit old assumptions

loop · ⚠ session-derived, unverified

A capability that removes a constraint should get its OWN navigation intent rather than reusing the constrained one: navigate_to routes through the nav graph and filters to reachable anchors, but a ghost that clips through walls needs navigate_to_noclip targeting the task center directly and ignoring reachability, because reusing the wall-aware intent silently keeps the old constraint. When play rules change, audit which existing primitives still encode the old assumption. Relatedly, a normal-mode behavior that discovers task candidates only from live task signals/arrows idles forever when arrows are disabled and all assigned tasks are off-screen -- fall back to a baked-map sweep over known task locations so the bot still makes progress without on-screen cues. _{sources: codex:019ea961-a6a9-7f42-ba2e-c8b65df11c22, codex:019e7174-3079-7351-b8ea-b1bfcb917ff4}

28. Build the coworld spatial map by fusing viewport pixels with minimap, viewport wins

loop · ⚠ session-derived, unverified

Build a coworld player's pathfinding map by fusing exact viewport pixels with lossy minimap data, and let VIEWPORT observations win for static occupants: once a cell is confirmed in the viewport, lock its static passability and ignore minimap wall/obstacle claims for it, but keep updating dynamic occupants (other players) from the minimap since players move into areas after you leave. Verify the game's native grid resolution before choosing yours (a 2:1 belief-grid-to-pixel resolution lets pathing route around partial obstacles). Give the player an internal world model the raw frame does not provide: an occupancy grid (UNKNOWN/FREE/WALL) updated from each viewport observation plus A* over it, which converts noisy local observations into a stable map the decide phase can plan over. _{sources: opencode:ses_209613a85ffeqO1Gq9NEDobBYi, opencode:ses_1fed7bbaaffe4qARc9KvRdpGAC}

29. Score round-trip targets by total cost, and express preferences as biases not tie-breaks

loop

Account for the return leg when selecting round-trip targets: sorting aligner junction targets by frontier distance PLUS a weighted hub-return distance was inert at 2000 steps but improved monotonically at 10000 steps and shipped at weight 1.0, because a junction near the frontier but far from the hub wastes cycle time walking back. This is target-selection-level so it composes safely, BUT it was inert until the REMEMBERED-target code path (_pick_remembered_target) was changed, not just the visible-target path -- the 13x13 window rarely contains sparse junctions, so most selections happen via spatial-memory search. A tie-break-only rule (e.g. prefer a friendly junction over the hub at EXACTLY equal distance) rarely fires and is near-neutral/byte-identical; to express a real preference use a within-N-distance bias instead. _{sources: archive/cogames_playground/alpha_cog/experiments/notebook/hypotheses/H, archive/cogames_playground/alpha_cog/experiments/notebook/hypotheses/H, opencode:ses_21b3c677dffe3YCY8JnACrbDmu}

30. Break the localize-vs-move deadlock with bootstrap motion; emit moves only when localized

loop

Localization and movement are a chicken-and-egg deadlock: the localizer needs varied map pixels to lock, but if the bot won't move until localized the camera stays fixed and localization never improves. Add a bootstrap exploratory-movement behavior that runs BEFORE localization to feed the estimator, instead of gating all movement on the state movement is required to reach. Once locked, emit movement ONLY when localized -- world-space steering targets are meaningless without a position lock, so non-moving modes must press no buttons. Give navigation graceful degradation: use A* world-space pathing when localized and the map is available, fall back to screen-space greedy movement when the map is missing or the bot is not yet localized, so a missing map degrades rather than crashes. _{sources: opencode:ses_21ab38af3ffeCyRfclXzAswGm1, opencode:ses_21fc35ba9ffeK5TywAEvVvlBBl, players_checkouts/players/users/james/personal_cogs/among_them/guided_, players_checkouts/players/users/james/personal_cogs/among_them/guided_}

31. Store spatial memory with per-cell timestamps; pre-populate known static layout

loop

Store per-cell spatial memory with a last_seen_tick INTEGER timestamp rather than a binary fresh/stale flag, so each consumer derives its own decay (e.g. 'treat cells unseen for 50 ticks as unknown for pathing'; 'never trust enemy positions older than 5 ticks'). Pre-populate memory with any fixed deterministic layout known a priori (walls, hub, fixed extractors, stations, spawn pads) at episode start, but first confirm the agent doesn't build wall knowledge lazily (e.g. nottoodumb.nim:3112) before assuming a map file is preloaded. Track depletable sites by observable remaining count -- when a former extractor cell is observed with no tags, treat it as exhausted passable floor so harvesters skip it; prioritize re-scouting mutable objects (capturable junctions) while treating immutable structure as permanently known. Walls are exempt from fog-of-war darkening (the renderer skips wall color when shadowing) so an agent can always read walls regardless of fog and lock them as confirmed terrain. _{sources: archive/cogames_playground/alpha_cog/docs/agent-architecture.md, archive/cogames_playground/bulbacog/designs/MEMORY.md, bitworld/among_them/players/lively_lecun/ROADMAP.md, orpheus/DESIGN.md (Orpheus agent framework design)}

32. Spread agents off shared targets with deterministic backoff, claims, and trail repulsion

loop

Because simultaneous-action agents all act at once with unspecified order, reduce hub/station/junction congestion by design: assign only 1-2 agents per gear station, spread miners across extractors, use deterministic agent-ID tie-breaks, and add a short cooldown after a failed move before retrying the same blocked direction. Scatter pile-ups with asymmetric DETERMINISTIC backoff (no comms): detect dwell-without-progress (adjacent to a non-producing anchor for >=25 ticks) and back off by side so an agent NW of the anchor retreats NW and opposites land in opposite quadrants -- and never park ON a shared hub tile (it blocks teammate deposits); wait on an adjacent cell and noop until global team counts say the action is possible, then bump. Spread off shared targets via an inferred claim filter (yield only when no teammate is closer or equidistant-lex-smaller within proximity_K) or a published ClaimBook -- ClaimBook for own-team, inferred filter to also avoid contesting enemy intent. Fix head-on cell-swap deadlocks by hard-blocking a teammate's just-vacated cell (team-trail tail-1 repulsion >= max_repulsion_per_step=400). _{sources: archive/cogames_playground/alpha_cog/docs/cogs-v-clips-strategy.md, optimizers/.cursor/skills/scripted-navigation/SKILL.md, optimizers/.cursor/skills/scripted-navigation/reference.md, archive/cogames_playground/bulbacog/designs/ALIGNER_SPIRAL.md}

33. Tabu failed targets by destination cell, with strikes, TTL, and a geometry-only escape route

loop

When an agent re-chases a dead extractor or empty junction, use a failure-strike tabu: N consecutive failures (strike_threshold=2) promote the key to a TTL blacklist filtered out of candidates, cleared on first success (strike_window=0 accumulates over lifetime; >=1 requires consecutive). Make the tabu COST land on the move's DESTINATION cell, not the cell the agent stands on, so an agent standing on a tabu cell with its goal one step away still moves toward it (cost on the current cell would trap the start). For in-a-hurry paths like retreat or regear use direct=True (geometry-only routing that ignores accumulated blocked cells and soft fields) so stale soft state can't trap the agent; for long return-to-hub paths also pass use_tabu=False so the agent's own trail doesn't wall it in. _{sources: optimizers/.cursor/skills/scripted-navigation/SKILL.md, optimizers/.cursor/skills/scripted-navigation/reference.md}

34. An outer priority layer dominates any inner direction bias; check the active layer

loop

In an explore routine, a priority/outer layer dominates any inner direction-bias ranking: a 'prefer unvisited cells' outer loop always beat a 'prefer distance-reducing direction' inner ranking. To make a direction bias actually override, apply it at the SAME level or higher, not nested beneath. Put new explore-direction heuristics in the single chokepoint (alpha_cog's navigation.explore_action(), which ranks 4 directions from explore_direction_index and can split into safe vs enemy-territory rankings) so both bare-explore and pursue-fallback callers benefit instead of duplicating per caller, and update the navigation tests since expected action sequences change. _{sources: alpha_cog/AGENTS.md, opencode:ses_1fb831c9fffeKY47cyKQE2t53a, opencode:ses_1fb1787afffemhwtF09UMzPc5V}

35. Configure A* correctly: heuristic by attractor presence, right distance metric, calibrated repulsion

loop

Choose the A* heuristic by attractor presence: Manhattan when none are active (fast, admissible), Dijkstra/zero-heuristic when attractors are present (attraction makes Manhattan inadmissible); the 'auto' mode does this, only force weighted if you knowingly accept inadmissibility for speed. Break tied first-move choices with a per-agent direction_rotation so a whole team doesn't drift the same way. Use the correct metric per purpose in a 4-connected env: bump-target arrival is Manhattan==1 (treating a diagonal at Chebyshev-1/Manhattan-2 as arrived is a one-tick-early bug); range/AOE disks are Euclidean compared as euclidean_sq<=RR to stay integer; nav heuristics and grid-step attribution are Manhattan; Chebyshev only for observation-window bounding boxes. Calibrate repulsion against per-step terrain cost (at base_terrain_weight=50.0, ~one terrain weight of repulsion = ~one cell of detour) and precompute the repulsion grid for O(1) lookup. Default knobs to neutral/off (all-zero weights + base_terrain_weight=1.0 reproduces vanilla A) so behavior is opt-in -- and when expected avoidance is missing, check the weight is non-zero before assuming the feature is on. Pick the best candidate with multi-pass relaxation: apply filters most-essential-first and drop the last (loosest) each pass until something matches, so filter ORDER encodes priority. _{sources: optimizers/.cursor/skills/scripted-navigation/SKILL.md, optimizers/.cursor/skills/scripted-navigation/reference.md}

36. Use per-bot home as fallback goal; treat stuck/idle as low-priority loop-breakers

loop

Record each scripted-game agent's first reliably-localized position as its 'home' and use home as the fallback goal when no task is known -- return an agent to its OWN home (e.g. not the single shared emergency-button pixel) so multiple agents spread out instead of piling up. Detect 'stuck' when position is unchanged ~30 frames and 'idle' when it stays in one region/room ~200 frames, and use these as LOW-priority loop-breaking triggers, not primary decision drivers. _{sources: bitworld/among_them/players/how_to_make_a_bot.md, bitworld/among_them/players/SMART_BOT_GUIDE.md, bitworld/among_them/bot-policies/sidecar/triggers.py}

37. Partition cross-tick nav state, model 'follow' as a stable task, and bound approach modes

loop

Partition cross-tick navigation state into two homes: (1) per-MODE scratch that persists across ticks and resets on mode switch, so A* paths aren't recomputed every loop iteration; (2) the ACT/navigation layer's OWN persistent memory separate from per-mode scratch, because momentum, jiggle, and step-by-step path following need the act phase to remember state -- decide ownership carefully since the act layer needs read access to the mode's stored path. Model 'follow target' as its own task with stable identity (follow, player_index, stop_distance) regardless of target position, rather than re-issuing move_to(target_pos) each tick, so ActionMemory and the A* path aren't cleared and recomputed as the target moves. Give interrupt/approach modes bounded give-up conditions: an approach timeout (~240 ticks/10s no-progress) catches unreachable targets and an in-range timeout (~72 ticks/3s in range without the expected state change) catches actions that didn't register; on give-up force an immediate switch back to the default directive rather than idling until TTL expires. _{sources: opencode:ses_21e58aef7ffeoJ7uZeDgGBCfIh, orpheus/DESIGN.md (Orpheus agent framework design), players_checkouts/players/users/james/personal_cogs/among_them/guided_}