feat(v0.3.1): real survival patterns — biome-aware scout, wedge-relocate, escape-pit-safe

Operator reported the bot wandered the same 50×50 patch for 2 hours
without making any progress toward food. Diagnosis showed three root
causes; this commit addresses all five open improvement_requests
the LLM (postmortem + tuner) flagged automatically.

Research basis (`Voyager`, `Plan4MC`, `GITM`, `Mindcraft`):
  - Coverage / commit-to-cardinal exploration when local scan fails
  - Biome-aware strategy switching using a static affordance table
  - Wedge detector above the skill layer that triggers RELOCATE not
    RETRY (per-skill stuck checks reset on re-entry — useless)
  - Time-in-region bbox heuristic + need-duration AND skill-cycle gate

Concrete changes:

1. `runtime/goal/storyline.js`
   - orient_self.completed: added timeout fallback (HP=full + session
     >120s → done) so barren biomes don't block the bot on step 1.
     Closes improvement #2 'Нет навыка оценки когда сменить район'.
   - first_food.suggestSkill: now picks survive.scout-food (new) when
     no passive mob is nearby; falls back to survive.acquire-food only
     when something is in immediate range.

2. `runtime/biome-affordances.js` (new)
   - Static table: 40+ biomes → {has_passive_mobs, has_trees,
     has_water, has_crops, livable}.
   - Unknown biomes return optimistic defaults to avoid regressions.
   - Closes improvement #1 'Нет навыка целевого поиска еды по биому'.

3. `runtime/skills/scout-food.js` (new — survive.scout-food)
   - Tiered strategy: biome check → scan 32 → scan 64 → commit a
     cardinal for 200 blocks rescanning every 16. On cardinal
     exhaustion, returns code:"exhausted" so the curriculum can
     escalate to village.relocate.
   - In barren biomes (desert/ocean/snowy_plains) the scan is
     SKIPPED — bot walks straight toward the nearest neighbour
     biome that affords passive mobs (8-direction biome probe at
     radius 64).

4. `runtime/awareness/wedge-detector.js` (new)
   - Rolling 10-min position bbox tracker. observe() called every
     tick; isWedged() returns true when bbox<50 AND active need
     unmet >5min AND skill cycles ≥3.
   - markRelocationStarted() suppresses further wedge firings
     until the bot has displaced ≥200b — prevents stack overflow
     of relocate calls.
   - Lives ABOVE the skill layer (in runtime/reflex.js), because
     any per-skill stuck check resets on re-entry.

5. `runtime/skills/relocate.js` (new — village.relocate)
   - 300-block walk in least-recently-used cardinal (per-incident
     memory in ctx.recentRelocations).
   - Re-paths every 32 blocks, soft-tolerates pathfinder failures
     (3 consecutive throws → exit with code:"stuck_in_place").
   - Closes improvement #2 + #4 ('low success rate trigger').

6. `runtime/skills/escape-pit-safe.js` (new — recovery.escape-pit-safe)
   - Surveys 4 cardinals AND ceiling height before committing.
     Picks the direction with most open blocks (≥3, no lava).
     Falls through to pillar-up only if ceiling clear ≥4b. Returns
     code:"no_strategy" if both blocked so curriculum can escalate
     to relocate.
   - Closes improvement #3 'Нет навыка для безопасного выхода'.

7. `runtime/reflex.js`
   - Wedge detector wired before manifesto/storyline. If wedge.wedged
     is true, dispatches village.relocate directly and returns —
     bypasses every other branch.
   - ctx.disableWedge flag for tests.

8. `runtime/coach/advisor-trigger.js`
   - LLM provider outage backoff: 3 consecutive http_400 / timeout /
     network_error → suppress advisor for 10 min. Today's TimeWeb
     gpt-5.4-mini was 400'ing for an hour straight; we were spending
     trigger budget on dead calls. Closes improvement implicit gap
     in #5.

9. `runtime/bot.js`
   - Tracks botSpawnedAt; snapshot._sessionMs exposed for storyline
     orient_self timeout fallback.

Tests: 396 green (was 378, +18):
  - runtime/biome-affordances.test.js — 8 tests
  - runtime/awareness/wedge-detector.test.js — 9 tests
  - runtime/goal/storyline.test.js — 1 new test (orient_self timeout)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

runtime/skills/escape-pit-safe.js

@@ -0,0 +1,159 @@
+// recovery.escape-pit-safe — multi-strategy escape from a hole / pit.
+//
+// Why this exists alongside recovery.tunnel-out and survive.pillar-up:
+//
+// tunnel-out tries to dig sideways through walls — fails on
+// unbreakable terrain or when there's no clear horizontal exit.
+// pillar-up places blocks under the bot and jumps — fails when
+// there's a ceiling block above the column.
+//
+// Both fail silently in a deep cave or 2×2 hole with a ceiling.
+// escape-pit-safe surveys options first, then commits:
+//
+//   1. Scan 4 cardinals at head height + foot height. Pick the one
+//      with the closest open path to surface (defined as: column
+//      with sky visibility above OR ≥3 air blocks horizontal followed
+//      by stairs / slope up).
+//   2. If a clear horizontal path exists → recovery.tunnel-out toward it.
+//   3. If no horizontal path BUT ceiling is open above us → pillar-up.
+//   4. If both blocked → return "stuck" and let the LLM-advisor flag a
+//      genuine improvement (e.g. "need water-bucket-MLG", "need to
+//      mine through stone").
+
+import { info, warn } from "../log.js";
+import { runSkill } from "./index.js";
+
+const SCAN_RADIUS = 6;
+const HEAD_OFFSET_Y = 1;
+
+function blockNameAt(bot, x, y, z) {
+	try {
+		const b = bot.blockAt?.({ x: Math.floor(x), y: Math.floor(y), z: Math.floor(z) });
+		return b?.name ?? null;
+	} catch { return null; }
+}
+
+function isAir(name) { return name === "air" || name === "cave_air" || name === "void_air"; }
+function isWater(name) { return name === "water" || name === "flowing_water"; }
+function isLava(name) { return name === "lava" || name === "flowing_lava"; }
+function isPassable(name) { return isAir(name) || (name && /carpet|button|torch|grass$/.test(name)); }
+
+// Look up to 32 blocks straight up from (x,y,z). Return distance to first
+// non-air block, or Infinity if open all the way (this is a sky-visible
+// column we could pillar-up out of).
+function ceilingDistance(bot, x, y, z) {
+	for (let dy = HEAD_OFFSET_Y + 1; dy <= 32; dy++) {
+		const n = blockNameAt(bot, x, y + dy, z);
+		if (!n) return dy; // unloaded chunk = no info; treat conservatively
+		if (!isAir(n)) return dy;
+	}
+	return Infinity;
+}
+
+// Scan SCAN_RADIUS blocks in each cardinal at head height. Return
+// summary per direction: open-block count, lava/water hits, first
+// non-air block name.
+function scanCardinals(bot) {
+	const pos = bot?.entity?.position;
+	if (!pos) return [];
+	const head = pos.offset?.(0, HEAD_OFFSET_Y, 0) ?? { x: pos.x, y: pos.y + HEAD_OFFSET_Y, z: pos.z };
+	const dirs = [
+		{ name: "N", dx: 0, dz: -1 },
+		{ name: "E", dx: 1, dz: 0 },
+		{ name: "S", dx: 0, dz: 1 },
+		{ name: "W", dx: -1, dz: 0 },
+	];
+	return dirs.map((d) => {
+		let openBlocks = 0;
+		let lavaAt = -1;
+		let waterAt = -1;
+		let firstBlock = null;
+		for (let r = 1; r <= SCAN_RADIUS; r++) {
+			const x = head.x + d.dx * r;
+			const z = head.z + d.dz * r;
+			const n = blockNameAt(bot, x, head.y, z);
+			if (isLava(n) && lavaAt < 0) lavaAt = r;
+			if (isWater(n) && waterAt < 0) waterAt = r;
+			if (isPassable(n)) {
+				openBlocks++;
+				if (firstBlock === null) firstBlock = "(air)";
+			} else {
+				if (firstBlock === null) firstBlock = n ?? "(unknown)";
+				break;
+			}
+		}
+		return { ...d, openBlocks, lavaAt, waterAt, firstBlock };
+	});
+}
+
+export const skill = Object.freeze({
+	id: "recovery.escape-pit-safe",
+	title: "Escape a pit — survey directions and pick the safest exit",
+	timeoutMs: 90_000,
+	preconditions(ctx) {
+		if (!ctx?.bot?.entity?.position) return { ok: false, code: "no_bot", detail: "bot missing" };
+		return { ok: true };
+	},
+	async execute(ctx) {
+		const bot = ctx.bot;
+		const pos = bot.entity.position;
+		const dirs = scanCardinals(bot);
+		const ceiling = ceilingDistance(bot, pos.x, pos.y, pos.z);
+
+		info(
+			"action",
+			`escape-pit-safe: cardinals=${dirs.map((d) => `${d.name}:${d.openBlocks}/${d.firstBlock}`).join(" ")} ceiling=${ceiling === Infinity ? "open" : ceiling + "b"}`,
+		);
+
+		// 1. Choose the direction with most open blocks (≥3) and no lava.
+		const horizontal = dirs
+			.filter((d) => d.openBlocks >= 3 && d.lavaAt < 0)
+			.sort((a, b) => b.openBlocks - a.openBlocks)[0];
+
+		if (horizontal) {
+			info("action", `escape-pit-safe: walking out via ${horizontal.name} (${horizontal.openBlocks}b clear)`);
+			// Delegate to wander step or simple controlled walk. Easier:
+			// invoke recovery.tunnel-out with a hint of the chosen direction.
+			const res = await runSkill("recovery.tunnel-out", ctx, { preferredDir: horizontal.name });
+			return {
+				ok: !!res?.ok,
+				code: res?.code ?? (res?.ok ? "done" : "tunnel_failed"),
+				detail: { strategy: "horizontal_walk", direction: horizontal.name, tunnelResult: res?.detail },
+				worldDelta: res?.worldDelta ?? { strategy: "horizontal_walk", direction: horizontal.name },
+			};
+		}
+
+		// 2. No horizontal exit — try pillar-up only if ceiling is open
+		// for the bot's height (≥3 blocks: head + 1 build + 1 ceiling slack).
+		if (ceiling >= 4) {
+			info("action", `escape-pit-safe: ceiling clear (${ceiling}b), trying pillar-up`);
+			const res = await runSkill("survive.pillar-up", ctx);
+			return {
+				ok: !!res?.ok,
+				code: res?.code ?? (res?.ok ? "done" : "pillar_failed"),
+				detail: { strategy: "pillar_up", ceiling, pillarResult: res?.detail },
+				worldDelta: res?.worldDelta ?? { strategy: "pillar_up" },
+			};
+		}
+
+		// 3. Both blocked — surrender. The LLM-advisor will see this in
+		// recent dispatches and can suggest village.relocate or flag a
+		// new skill request.
+		warn("action", `escape-pit-safe: no viable strategy (horizontal blocked + ceiling ${ceiling}b)`);
+		return {
+			ok: false,
+			code: "no_strategy",
+			detail: { horizontal: dirs.map((d) => ({ d: d.name, open: d.openBlocks, lava: d.lavaAt })), ceiling },
+			worldDelta: null,
+		};
+	},
+	recover(ctx, result) {
+		if (result.code === "no_strategy") {
+			return { hint: "wander", reason: "no viable pit-escape; let curriculum try a different action" };
+		}
+		return null;
+	},
+});
+
+// Test exports
+export const __testing = { scanCardinals, ceilingDistance, isAir, isPassable, SCAN_RADIUS };

runtime/skills/index.js

@@ -30,11 +30,14 @@ import { skill as flee } from "./flee.js";
 import { skill as sleep } from "./sleep.js";
 import { skill as tunnelOut } from "./recovery-tunnel-out.js";
 import { skill as pillarUp } from "./pillar-up.js";
+import { skill as escapePitSafe } from "./escape-pit-safe.js";
 import { skill as diagPhysics } from "./diagnose-physics.js";
 import { skill as diagScan, matchSkill as diagMatch } from "./diagnose-scan.js";
 import { skill as gatherStone } from "./gather-stone.js";
 import { skill as gatherWool } from "./gather-wool.js";
 import { skill as acquireFood } from "./acquire-food.js";
+import { skill as scoutFood } from "./scout-food.js";
+import { skill as relocate } from "./relocate.js";
 import { skill as chooseBase } from "./choose-base.js";
 import { skill as buildShelter } from "./build-shelter.js";
 import { skill as placeChest } from "./place-chest.js";
@@ -74,12 +77,15 @@ register(flee);
 register(sleep);
 register(tunnelOut);
 register(pillarUp);
+register(escapePitSafe);
 register(diagPhysics);
 register(diagScan);
 register(diagMatch);
 register(gatherStone);
 register(gatherWool);
 register(acquireFood);
+register(scoutFood);
+register(relocate);
 register(chooseBase);
 register(buildShelter);
 register(placeChest);

runtime/skills/relocate.js

@@ -0,0 +1,139 @@
+// village.relocate — commit-and-walk skill that breaks the bot out of
+// "I've been wandering the same 50×50 area for 2 hours" failure mode.
+//
+// Heuristic: when the wedge-detector says we're stuck, this skill is
+// dispatched with no biome preference; it picks the least-recently-
+// visited cardinal (or any cardinal if no history) and walks ~300
+// blocks toward it, with a hard time budget. While it runs, the
+// reflex's wedge-detector knows a relocation is in flight and won't
+// fire another one on top.
+//
+// The skill ignores the active need entirely for its duration — its
+// only job is to displace the bot far enough that the surrounding
+// biome is fresh and skills like survive.acquire-food / gather.logs
+// have new local context to work with.
+
+import pathfinderPkg from "mineflayer-pathfinder";
+const { pathfinder, goals, Movements } = pathfinderPkg;
+
+import { info } from "../log.js";
+import { markRelocationStarted } from "../awareness/wedge-detector.js";
+
+const CARDINALS = [
+	{ name: "N", dx: 0, dz: -1 },
+	{ name: "E", dx: 1, dz: 0 },
+	{ name: "S", dx: 0, dz: 1 },
+	{ name: "W", dx: -1, dz: 0 },
+];
+const DEFAULT_DISTANCE = 300;
+const STEP_BLOCKS = 32;            // re-path every N blocks for liveness
+const STEP_TIMEOUT_MS = 30_000;
+
+let pluginLoaded = new WeakSet();
+function ensurePathfinder(bot) {
+	if (pluginLoaded.has(bot)) return;
+	bot.loadPlugin(pathfinder);
+	pluginLoaded.add(bot);
+}
+function setMovementsForTravel(bot) {
+	const m = new Movements(bot);
+	m.canDig = false;
+	m.allow1by1towers = false;
+	bot.pathfinder.setMovements(m);
+}
+
+function pickCardinal(ctx, args) {
+	// Explicit override wins
+	if (args?.heading) {
+		const found = CARDINALS.find((c) => c.name === args.heading);
+		if (found) return found;
+	}
+	// Otherwise pick a cardinal not recently used. ctx may carry a
+	// recentRelocations array {name, ts}; default = N.
+	const recent = new Set((ctx?.recentRelocations ?? []).map((r) => r.name));
+	const untried = CARDINALS.filter((c) => !recent.has(c.name));
+	return untried[0] ?? CARDINALS[Math.floor(Math.random() * CARDINALS.length)];
+}
+
+export const skill = Object.freeze({
+	id: "village.relocate",
+	title: "Walk 300 blocks in a fresh cardinal to break a wedge",
+	timeoutMs: 180_000,
+	preconditions(ctx) {
+		if (!ctx?.bot?.entity?.position) {
+			return { ok: false, code: "no_bot", detail: "bot or entity missing" };
+		}
+		return { ok: true };
+	},
+	async execute(ctx, args = {}) {
+		const bot = ctx.bot;
+		const distance = Math.max(64, Math.min(args?.distance ?? DEFAULT_DISTANCE, 600));
+		const cardinal = pickCardinal(ctx, args);
+		const start = { x: bot.entity.position.x, z: bot.entity.position.z };
+		markRelocationStarted({ x: start.x, z: start.z, heading: cardinal });
+		ctx.recentRelocations = (ctx.recentRelocations ?? []).slice(-3);
+		ctx.recentRelocations.push({ name: cardinal.name, ts: Date.now() });
+
+		ensurePathfinder(bot);
+		setMovementsForTravel(bot);
+		info("action", `relocate: heading ${cardinal.name} for ${distance}b from (${Math.round(start.x)}, ${Math.round(start.z)})`);
+
+		let travelled = 0;
+		const errors = [];
+		while (travelled < distance) {
+			if (ctx?.abortSignal?.aborted) {
+				return {
+					ok: travelled >= distance / 2, // partial counts if we got at least half
+					code: travelled >= distance / 2 ? "partial" : "preempted",
+					detail: { travelled: Math.round(travelled), heading: cardinal.name },
+					worldDelta: { moved: Math.round(travelled), heading: cardinal.name },
+				};
+			}
+			const stepDist = Math.min(STEP_BLOCKS, distance - travelled);
+			const targetX = start.x + cardinal.dx * (travelled + stepDist);
+			const targetZ = start.z + cardinal.dz * (travelled + stepDist);
+			const targetY = Math.floor(bot.entity.position.y);
+			try {
+				await Promise.race([
+					bot.pathfinder.goto(new goals.GoalNear(Math.floor(targetX), targetY, Math.floor(targetZ), 4)),
+					new Promise((_, rej) => setTimeout(() => rej(new Error("step timeout")), STEP_TIMEOUT_MS)),
+				]);
+			} catch (e) {
+				errors.push(e?.message ?? String(e));
+				if (errors.length >= 3) break;
+				// brief pause then keep trying
+				await new Promise((r) => setTimeout(r, 500));
+			}
+			// Measure actual progress (pathfinder might have routed around)
+			const dx = bot.entity.position.x - start.x;
+			const dz = bot.entity.position.z - start.z;
+			travelled = Math.hypot(dx, dz);
+		}
+
+		const endPos = bot.entity.position;
+		const finalDist = Math.hypot(endPos.x - start.x, endPos.z - start.z);
+		if (finalDist < 50) {
+			return {
+				ok: false,
+				code: "stuck_in_place",
+				detail: { travelled: Math.round(finalDist), heading: cardinal.name, errors: errors.slice(0, 3) },
+				worldDelta: { moved: Math.round(finalDist) },
+			};
+		}
+		return {
+			ok: true,
+			code: "done",
+			detail: { travelled: Math.round(finalDist), heading: cardinal.name },
+			worldDelta: { moved: Math.round(finalDist), heading: cardinal.name, mode: "relocate" },
+		};
+	},
+	recover(ctx, result) {
+		if (result.code === "stuck_in_place") {
+			return { hint: "wander", reason: "relocate could not gain ground; let wander try a new tactic" };
+		}
+		return null;
+	},
+});
+
+// Test exports
+export const __testing = { CARDINALS, DEFAULT_DISTANCE, pickCardinal };

runtime/skills/scout-food.js

@@ -0,0 +1,276 @@
+// survive.scout-food — longer-range, biome-aware food search.
+//
+// Why this exists alongside survive.acquire-food:
+//
+// acquire-food is the "I see a cow, hunt it" skill. Its precondition
+// requires a passive food mob within ~32 blocks; if there isn't one,
+// the skill bails immediately. In v0.3.0 that produced two failure
+// modes that kept the bot looping for hours:
+//
+//   1. Biome with NO passive mobs (desert, ocean, snowy peaks, deep
+//      caves). acquire-food can never succeed there — the bot just
+//      kept scanning the same 32-block sphere.
+//
+//   2. Biome WITH passive mobs but the immediate area is empty. The
+//      bot wandered 1-8 blocks at a time around the same 50×50 patch
+//      and never committed to a direction long enough to leave it.
+//
+// scout-food applies the "commit-to-cardinal" pattern (per the v0.3.1
+// design research): scan(32) → patrol(64, time-budget) → if still
+// nothing, walk a chosen cardinal for ~200 blocks, rescanning every
+// 16 blocks. On exhaustion of all 4 cardinals it surrenders to the
+// curriculum so the operator-driven `village.relocate` or LLM advisor
+// can pick up.
+//
+// Biome-awareness:
+// - If current biome's affordance table has has_passive_mobs=false
+//   AND has_water=false, skip the local scan entirely and pick the
+//   most plausible "leave biome" heading: sample neighbour biomes at
+//   radius 64 in 8 directions, pick the first one whose affordances
+//   say has_passive_mobs=true.
+// - In water-bearing barren biomes (ocean shores, frozen rivers)
+//   fishing isn't implemented yet — operator-facing improvement.
+
+import pathfinderPkg from "mineflayer-pathfinder";
+const { pathfinder, goals, Movements } = pathfinderPkg;
+
+import { info, warn } from "../log.js";
+import { foods } from "./groups.js";
+import { affordancesFor, hasPassiveMobs, isBarren } from "../biome-affordances.js";
+
+const PASSIVE_FOOD_MOBS = new Set(["cow", "pig", "chicken", "sheep", "rabbit", "mooshroom"]);
+const CARDINALS = [
+	{ name: "N", dx: 0, dz: -1 },
+	{ name: "E", dx: 1, dz: 0 },
+	{ name: "S", dx: 0, dz: 1 },
+	{ name: "W", dx: -1, dz: 0 },
+];
+const PATROL_TICK_DISTANCE = 16;
+const DEFAULT_COMMIT_DISTANCE = 200;
+
+let pluginLoaded = new WeakSet();
+function ensurePathfinder(bot) {
+	if (pluginLoaded.has(bot)) return;
+	bot.loadPlugin(pathfinder);
+	pluginLoaded.add(bot);
+}
+
+function setMovementsForTravel(bot) {
+	const m = new Movements(bot);
+	m.canDig = false;
+	m.allow1by1towers = false;
+	bot.pathfinder.setMovements(m);
+}
+
+function foodCount(bot) {
+	const allowed = foods(bot);
+	return bot.inventory.items().reduce((sum, item) => allowed.has(item.name) ? sum + item.count : sum, 0);
+}
+
+function nearestPassiveFoodMob(bot, maxDistance) {
+	const here = bot?.entity?.position;
+	if (!here) return null;
+	let best = null;
+	for (const e of Object.values(bot.entities ?? {})) {
+		if (!e?.position || !PASSIVE_FOOD_MOBS.has(e.name)) continue;
+		const d = e.position.distanceTo(here);
+		if (d > maxDistance) continue;
+		if (!best || d < best.distance) best = { entity: e, distance: d };
+	}
+	return best;
+}
+
+function currentBiomeName(bot) {
+	try {
+		const block = bot.blockAt?.(bot.entity?.position);
+		const b = block?.biome;
+		if (typeof b === "string") return b;
+		if (b?.name) return b.name;
+		return null;
+	} catch { return null; }
+}
+
+function biomeNameAt(bot, x, y, z) {
+	try {
+		const block = bot.blockAt?.({ x: Math.floor(x), y: Math.floor(y), z: Math.floor(z) });
+		const b = block?.biome;
+		if (typeof b === "string") return b;
+		if (b?.name) return b.name;
+		return null;
+	} catch { return null; }
+}
+
+// Sample biomes in 8 compass directions at the given radius; return
+// the heading whose biome has passive mobs.
+function scanForFoodCapableNeighbourBiome(bot, radius = 64) {
+	const here = bot?.entity?.position;
+	if (!here) return null;
+	const dirs = [
+		{ name: "N",  dx: 0,    dz: -1   },
+		{ name: "NE", dx: 0.71, dz: -0.71 },
+		{ name: "E",  dx: 1,    dz: 0    },
+		{ name: "SE", dx: 0.71, dz: 0.71 },
+		{ name: "S",  dx: 0,    dz: 1    },
+		{ name: "SW", dx: -0.71, dz: 0.71 },
+		{ name: "W",  dx: -1,   dz: 0    },
+		{ name: "NW", dx: -0.71, dz: -0.71 },
+	];
+	for (const d of dirs) {
+		const b = biomeNameAt(bot, here.x + d.dx * radius, here.y, here.z + d.dz * radius);
+		if (b && hasPassiveMobs(b)) return { heading: d, biome: b };
+	}
+	return null;
+}
+
+async function patrolCardinal(bot, cardinal, distance, ctx) {
+	ensurePathfinder(bot);
+	setMovementsForTravel(bot);
+	const start = bot.entity.position.clone?.() ?? { ...bot.entity.position };
+	let travelled = 0;
+	while (travelled < distance) {
+		if (ctx?.abortSignal?.aborted) return { aborted: true, travelled };
+		const tx = start.x + cardinal.dx * (travelled + PATROL_TICK_DISTANCE);
+		const tz = start.z + cardinal.dz * (travelled + PATROL_TICK_DISTANCE);
+		const goal = new goals.GoalNear(Math.floor(tx), Math.floor(bot.entity.position.y), Math.floor(tz), 2);
+		try {
+			await Promise.race([
+				bot.pathfinder.goto(goal),
+				new Promise((_, rej) => setTimeout(() => rej(new Error("patrol step timeout")), 30_000)),
+			]);
+		} catch (e) {
+			return { aborted: false, travelled, error: e?.message ?? String(e) };
+		}
+		travelled += PATROL_TICK_DISTANCE;
+		// Rescan after every step.
+		const target = nearestPassiveFoodMob(bot, 32);
+		if (target) return { aborted: false, travelled, target };
+	}
+	return { aborted: false, travelled };
+}
+
+export const skill = Object.freeze({
+	id: "survive.scout-food",
+	title: "Scout for food at long range (biome-aware)",
+	timeoutMs: 240_000,
+	preconditions(ctx) {
+		if (!ctx?.bot) return { ok: false, code: "no_bot", detail: "bot missing" };
+		if (foodCount(ctx.bot) > 0) {
+			return { ok: false, code: "already_have", detail: "already carrying edible food" };
+		}
+		return { ok: true };
+	},
+	async execute(ctx, args = {}) {
+		const bot = ctx.bot;
+		const before = foodCount(bot);
+		const triedCardinals = new Set(args?._triedCardinals ?? []);
+
+		// Step 0: biome check. If barren, head toward a food-capable neighbour.
+		const biome = currentBiomeName(bot);
+		const aff = affordancesFor(biome);
+		info("action", `scout-food: biome=${biome ?? "?"} mobs=${aff.has_passive_mobs} barren=${isBarren(biome)}`);
+
+		if (!aff.has_passive_mobs) {
+			const next = scanForFoodCapableNeighbourBiome(bot, 64);
+			if (next) {
+				info("action", `scout-food: leaving barren biome ${biome} → ${next.biome} via ${next.heading.name}`);
+				const result = await patrolCardinal(bot, next.heading, DEFAULT_COMMIT_DISTANCE, ctx);
+				if (result.aborted) return { ok: false, code: "preempted", worldDelta: null };
+				if (result.target) {
+					return await tryHunt(bot, result.target, before);
+				}
+				return {
+					ok: false,
+					code: "no_target",
+					detail: `walked ${Math.round(result.travelled)}b ${next.heading.name} toward ${next.biome}, still no food`,
+					worldDelta: { moved: Math.round(result.travelled), heading: next.heading.name, from_biome: biome, to_biome: next.biome },
+				};
+			}
+			// Ringed by barren biomes; pick the first cardinal not yet tried.
+		}
+
+		// Step 1: scan radius 32 (cheap).
+		let target = nearestPassiveFoodMob(bot, 32);
+		if (target) return await tryHunt(bot, target, before);
+
+		// Step 2: scan radius 64 — entities frequently spawn just outside
+		// our local horizon.
+		target = nearestPassiveFoodMob(bot, 64);
+		if (target) return await tryHunt(bot, target, before);
+
+		// Step 3: commit to a cardinal we haven't tried in this incident.
+		const untried = CARDINALS.filter((c) => !triedCardinals.has(c.name));
+		if (untried.length === 0) {
+			return {
+				ok: false,
+				code: "exhausted",
+				detail: "tried all 4 cardinals without finding a food mob — switch to village.relocate",
+				worldDelta: null,
+			};
+		}
+		const cardinal = untried[0];
+		info("action", `scout-food: commit cardinal ${cardinal.name} for ${DEFAULT_COMMIT_DISTANCE}b`);
+		const result = await patrolCardinal(bot, cardinal, DEFAULT_COMMIT_DISTANCE, ctx);
+		if (result.aborted) return { ok: false, code: "preempted", worldDelta: null };
+		if (result.target) return await tryHunt(bot, result.target, before);
+		return {
+			ok: false,
+			code: "no_target",
+			detail: { tried: cardinal.name, travelled: Math.round(result.travelled), error: result.error ?? null },
+			worldDelta: { moved: Math.round(result.travelled), heading: cardinal.name, from_biome: biome },
+		};
+	},
+	recover(ctx, result) {
+		if (result.code === "exhausted") {
+			return { hint: "relocate", reason: "scout-food exhausted all 4 cardinals; needs a long jump" };
+		}
+		if (result.code === "no_target") {
+			return { hint: "wander", reason: "scout completed leg without finding mob; try another cardinal" };
+		}
+		return null;
+	},
+});
+
+async function tryHunt(bot, target, before) {
+	ensurePathfinder(bot);
+	setMovementsForTravel(bot);
+	try {
+		await Promise.race([
+			bot.pathfinder.goto(new goals.GoalFollow(target.entity, 2)),
+			new Promise((_, rej) => setTimeout(() => rej(new Error("path-to-mob timeout")), 30_000)),
+		]);
+	} catch (e) {
+		return { ok: false, code: "no_path", detail: e?.message ?? "path failed", worldDelta: null };
+	}
+	info("action", `scout-food: engaging ${target.entity.name}@${target.distance.toFixed(1)}b`);
+	for (let i = 0; i < 8; i++) {
+		const current = Object.values(bot.entities ?? {}).find((e) => e.id === target.entity.id);
+		if (!current) break;
+		if (current.position.distanceTo(bot.entity.position) > 4) {
+			try {
+				await Promise.race([
+					bot.pathfinder.goto(new goals.GoalFollow(current, 2)),
+					new Promise((_, rej) => setTimeout(() => rej(new Error("repath timeout")), 8_000)),
+				]);
+			} catch {}
+		}
+		bot.attack(current);
+		await new Promise((r) => setTimeout(r, 700));
+	}
+	await new Promise((r) => setTimeout(r, 1_000));
+	const after = foodCount(bot);
+	if (after <= before) {
+		return { ok: false, code: "no_drop", detail: `hunted ${target.entity.name} but no edible drop`, worldDelta: null };
+	}
+	return {
+		ok: true,
+		code: "done",
+		detail: { source: "hunt", mob: target.entity.name, gained: after - before },
+		worldDelta: { acquiredFood: after - before, source: "hunt", mob: target.entity.name },
+	};
+}
+
+// Test exports
+export const __testing = {
+	CARDINALS, PATROL_TICK_DISTANCE, DEFAULT_COMMIT_DISTANCE,
+	nearestPassiveFoodMob, currentBiomeName, scanForFoodCapableNeighbourBiome,
+};