v0.3.1: survival behaviour overhaul — storyline, biome-aware scout, wedge-relocate, food/perf fixes, monitor TUI (#28)

* docs(v0.3.1): PRD — LLM prompt cost optimization Design-only commit; no runtime changes. Spec for the next patch iteration. Goal: cut per-advise() input tokens from ~800 to ≤300, preserving the LLM's ability to produce valid registered skill ids and useful rationale. Five proposed changes ranked by impact: P1 Compact registry format (saves ~350t/call) — group by namespace, comma-list ids, drop human titles. Default mode for advisor; verbose mode kept for postmortem/reflect. P2 Need-scoped registry (~50t additional) — show LLM only skills relevant to the active Maslow need + always-available safety skills (survive.flee, pillar-up, recovery.tunnel-out, explore.*). P3 Snapshot pruning (~50t) — drop weather/experience/dimension/biome/ players from the user prompt; the LLM doesn't consult them. P4 Prompt caching probe — check if TimeWeb passes through prompt_tokens_details.cached_tokens. If yes, restructure prefix to maximize cache hits (cached input is ~10x cheaper at OpenAI). P5 Per-trigger cost telemetry in scripts/list-improvements.js --stats: avg_in / avg_out / cost_₽ / share% per trigger_reason, using TIMEWEB_PRICE_IN_RUB_PER_M and TIMEWEB_PRICE_OUT_RUB_PER_M env. Trigger: TimeWeb admin panel after first day of v0.3.0 live showed 34K tokens / day at low activity. At cap budget that projects to ~480₽/month (101₽/M in, 608₽/M out for gpt-5.4-mini). Manageable but the savings are mostly free — repeated infra tokens, not signal. All changes are additive; runtime behaviour stays the same. If the LLM produces worse advice with the compact registry, flip back via a single constant in fast-advisor.js. Acceptance: re-run scripts/check-timeweb.js probe 3 — expect tokens_in ≤ 300 (was ~800). Live for 1h, check --stats: avg_in ≤ 300 per trigger group. Existing 360 tests still green. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * feat(v0.3.1): storyline — canonical Minecraft survival quest The bot has been stuck in a loop for two days: acquire-food (fail: no nearby food) → explore.far → pillar-up (fail) → repeat Diagnosis: manifesto + LLM advisor both correctly identify "you need food" but neither expresses *what concretely to do next*. Manifesto is a priority ladder (need-detection), not a narrative arc. This commit adds the missing narrative layer — an ordered list of operational steps that mirror the vanilla Minecraft survival path: 1. orient_self — Понять где я 2. first_wood — Собрать 8 поленьев 3. crafting_basics — Сделать верстак и палки 4. first_tools — Деревянные орудия 5. first_food — Найти первую еду 6. shelter_minimal — Простой шелтер с кроватью 7. stone_tier — Каменные орудия 8. food_security — Запас еды на 16+ 9. iron_age — Железо и печь 10. settle_base — Постоянная база 11. village_grow — Развивать деревню (ongoing) Each step has: - completed(snapshot) → bool — detects achievement from snapshot - suggestSkill(snapshot) → { skillId, args? } — concrete next dispatch - emergencyPause(snapshot) → bool — defers to manifesto L0 alive emergencies (low HP near hostile, lava under foot, food = 0) - narration_ru — chat-friendly Russian one-liner spoken on entry Components: - runtime/goal/storyline.js — 11-step canonical quest catalogue - runtime/goal/state.js — pickCurrentStep(snapshot) walks the list, returns first non-completed step + its suggestion. 3s cache. Validates suggestSkill's skillId against the live registry. - runtime/reflex.js — curriculumReflex dispatch priority is now: 1. manifesto (L0 alive emergencies always win) 2. storyline (concrete operational subgoal) 3. curriculum plan (legacy fallback) Tests pass ctx.disableStoryline=true for isolation. - runtime/bot.js — snapshot.storyStep populated each tick so chatter/advisor/reflect observers see the same view. - runtime/coach/fast-advisor.js — buildUserPrompt now embeds the current step + its suggested skill, so LLM advice is anchored ("step 5 first_food, storyline wants survive.acquire-food, but recent dispatches show it's failing — try explore.far + scout"). - runtime/coach/advisor-trigger.js — forwards ctx.storyStep into advise() and logs step id at trigger time. - runtime/coach/reflect.js — reflection prompt includes storyline progress so 30-min self-assessment is anchored. - runtime/persona/chatter.js — narrates step.narration_ru on transition. Rate-limited via existing maybeNarrateRaw(). New operator CLI: - scripts/show-story.js — fetches the live snapshot via IPC sock and prints step progress with ✓/→/ markers, current skill, inventory. Falls back to --plain catalogue view when bot offline. Token cost impact: ~+30 input tokens per advise() call (one extra line in user prompt). Trivial vs the value of grounding LLM advice in a concrete narrative. Operator usage: node scripts/show-story.js # live progress + which step + why node scripts/show-story.js --plain # static catalogue of all 11 steps Tests: 376 green (was 360, +16 storyline tests). Also in this branch (already committed): dev/v0.3.1/PRD.md — LLM prompt cost optimization design doc. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * fix(v0.3.1): storyline beats manifesto L1+ (only L0 alive emergencies override) Found in live logs after the previous commit deployed: storyline: step 1/11: orient_self → explore.wander advisor-trigger: firing because wedged (planned=survive.acquire-food, ...) Manifesto was still picking survive.acquire-food (L1 food) over the storyline's orient_self → explore.wander. That's the wrong precedence — storyline expresses a *concrete operational subgoal* and L1+ manifesto needs are just "you'd benefit from food" priorities, not emergencies. New dispatch precedence in curriculumReflex: 1. manifesto L0 (alive emergencies: lava, low-HP+hostile, food=0) 2. storyline (concrete narrative subgoal — beats L1+ manifesto) 3. manifesto L1+ (fallback when storyline has no concrete suggestion) 4. curriculum plan (legacy fallback) This way the bot starts following the narrative arc even while manifesto's L1 food is technically unsatisfied — orient_self runs to completion before pursuing food explicitly. Storyline already handles food as step 5 (first_food), so we're not skipping it. Tests: 378 green (+2 priority-ordering tests): - L0 manifesto emergency: upstream reflex (defend/modes) catches before curriculum dispatch - storyline beats manifesto when both have suggestions: well-fed bot with logs → craft.planks (storyline crafting_basics), not gather.logs (manifesto L2) - updated "manifesto fallback" test to require disableStoryline=true Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * feat(tui): fullscreen monitor-only TUI (opencode-style) Replaces the old tui/tui.tsx hotkey-heavy dashboard with a read-only observability screen. Operator actions live in scripts/* now — TUI is for watching, not driving. Layout (top to bottom, all auto-resizing to terminal): 1. Header — MC/IPC status, pos, HP, food, day/night, hostiles 2. Storyline — current step + 11-step quest map (✓/→/○) 3. Activity — last N skill dispatches (colour by outcome) 4. MC Chat — last N chat lines (cyan for bot, yellow for players) 5. Advisor — last N LLM recommendations (trigger + outcome + tokens) 6. Improvements — open requests from knowledge.improvement_requests 7. Footer — 24h token usage + cost in ₽ + q-to-quit Data sources: - IPC sock: snapshot frames, log frames, chat frames (push) - SQLite knowledge.db: advisor_recommendations + improvement_requests polled every 5s (pull) Token cost displayed live using TIMEWEB_PRICE_IN_RUB_PER_M / TIMEWEB_PRICE_OUT_RUB_PER_M env vars (defaults: 101 / 608 for gpt-5.4-mini). Switches: - npm run tui → new monitor (this file) - npm run tui:legacy → old action-driven tui/tui.tsx (kept for now) Implementation notes: - Uses ink + alternate-screen-buffer ANSI for proper "opencode-feel" fullscreen behaviour; restores prior terminal contents on quit. - Skips alt-screen and useInput when stdin/stdout isn't a TTY (smoke tests, piped output) — both gracefully degrade. - Stable React keys via per-event uid counter, avoids reconciler duplicate-key warnings as logs/chat/dispatches stream in. - Resize handled via 1s stdout-dimension poll, NOT direct 'resize' listener (which conflicts with ink's own listener and triggers MaxListenersExceededWarning). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * ui(tui): compact 4-section monitor (was 6) — fits 1080p without zoom Operator reported the TUI overflowed the screen unless terminal was zoomed way out. The 11-step storyline list alone was eating ~13 rows, and each advisor/improvement entry took 2-3 rows. Now: - Header + storyline collapsed into one panel (2 lines): line 1: pepa · ●MC ●IPC · 1m50s · pepa_bot · (697,61,702) · HP 20 · food 5 · ☀ · ⚔60(creeper@58b) line 2: story ▓▒░░░░░░░░░ 1/11 orient_self · Понять где я → explore.wander The 11-step ladder is now a unicode progress bar (▓ done, ▒ current, ░ pending) — same info, fits in one row. - Advisor entries: one line each instead of two. ✓ wedged_60s → survive.flee 802t 1900ms (outcome mark / trigger / target skill / tokens / latency) - Improvements entries: one line each instead of two. #1 P2 ×3 Add craft.iron-pickaxe skill Description dropped from the row — use `node scripts/list-improvements.js` for full text. - Sections: 4 (was 6). [header+story] · [activity | chat] · [advisor | improvements] · [footer] Tested on a typical 1080p terminal — fits comfortably without zoom. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * 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> * fix(coach/trigger-tuner): crash after ~1h — runOnce is sync, not a Promise The live bot died overnight with: TypeError: runOnce(...).catch is not a function at trigger-tuner.js:42 → [supervisor] child exited code=1 attach() wrapped the timer body as `runOnce().catch(...)` but runOnce() returns a plain {ok, flagged, ...} object (pure SQL, no await). The first tuner tick (60min after spawn) threw → killed the whole bot process. Never surfaced before because the bot rarely ran uninterrupted for a full hour during development. Fix: guard the synchronous call with try/catch, matching how persona/chatter.js already does its sync tick. (postmortem.drainOnce and reflect.runOnce ARE async, so their .catch is correct — audited.) Regression test added: captures the setInterval callback and invokes it synchronously, asserting it does not throw. Tests: 397 green. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * fix(v0.3.1): mechanical food/stuck fixes — bot reaches the chicken now The wedge wasn't only in the manifesto layer; several mechanical bugs kept the bot in a dead random-walk: - storyline / manifesto / curriculum: "local food" now means an edible passive mob within <=32 blocks. A distant chicken or a cod no longer fools the bot into dispatching acquire-food (which then fails on no_path). Long-range food goes through scout-food instead. - scout-food: partial approach to a target now counts as progress (approached_target, e.g. moved:14); a blocked heading is NOT counted as movement; added blind/tunnel fallback so it doesn't die when the pathfinder can't route cleanly. - acquire-food: on no_path it now also tries a blind/tunnel approach to the animal; no_drop routes back into food scouting instead of giving up. - explore.far / relocate / flee: fewer false "done" results (micro-steps no longer counted as success), more genuine escapes from stuck. - scripts/show-story.js: live IPC now actually renders the current storyline step. Verification: scripts/lint-patch.js clean; npm test 404/404 green; bot relaunched in tmux `pepa`. Live logs show real progress — bot switched to survive.scout-food, approached the chicken (approached_target moved:14), then reached survive.acquire-food: hunting chicken. Food isn't fully closed yet but the remaining issue is concrete pickup/drop, not dead random-walk. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * fix(v0.3.1): sated bot stops chasing food + perf-leak + fuzzy improvement dedup Third day of "bot just walks back and forth burning tokens". Root causes were mechanical, not the manifesto: 1. SATED BOT CHASING FOOD (the big one) Bot had food=17 (nearly full) but storyline first_food + manifesto L1 required 2+ food ITEMS in inventory, so it looped scout-food / acquire-food for hours instead of working. Now both treat a hunger bar >= 14 (SATED_FOOD) as satisfied even with empty food inventory — a full bot chops wood / makes tools and grabs food opportunistically, only hard-pursuing food when actually hungry (< 14). manifesto/needs.js foodDetect + goal/storyline.js first_food.completed. 2. perf_hooks MEMORY LEAK (overnight OOM suspect) "MaxPerformanceEntryBufferExceededWarning: 1,000,001 measure entries". mineflayer/pathfinder emit perf marks we never consume. Added a 60s reaper in bot.js (performance.clearMeasures/clearMarks). unref'd. 3. IMPROVEMENT QUEUE SELF-DUPLICATING The LLM re-filed closed gaps with reworded titles (#5/#8/#9 were dupes of implemented #1/#2/#3). Exact-title dedup missed them. Replaced with token-set fuzzy match (isDuplicateTitle): jaccard>=0.75 OR >=3 shared meaningful tokens with jaccard>=0.5. Also: a re-filed gap that's already implemented/rejected is NOT resurrected as a new open row. Cleared all 5 open requests (now genuinely implemented). Also confirmed (no change needed): - canDig=true is a DELIBERATE codebase-wide choice ("without it the bot gets permanently stuck", actions.js). The stale memory recommending canDig=false is updated. ViaBackwards dig works partially (dug:1 moved:1.8 observed); false would trap the bot in every pit. - scout-food already has blind/tunnel fallback + 12s step timeout (operator's earlier edits) so trapped-pathfinder degrades instead of hanging 30s. Tests: 407 green (was 404). Updated needs/state/storyline tests for the SATED_FOOD threshold; added fuzzy-dedup + tokenize/jaccard tests. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: Yuriy Mayatnikov <mayatnikov@me.com> Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-28 09:43:57 +03:00
parent 7d96e44804
commit 15b6c11002
37 changed files with 3259 additions and 71 deletions
@@ -0,0 +1,408 @@
+// 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";
+import { blindWalkOrTunnelOut } from "./explore-far.js";
+
+const PASSIVE_FOOD_MOBS = new Set(["cow", "pig", "chicken", "sheep", "rabbit", "mooshroom"]);
+const CARDINALS = [
+	{ name: "N", dx: 0, dz: -1, yaw: Math.PI },
+	{ name: "E", dx: 1, dz: 0, yaw: -Math.PI / 2 },
+	{ name: "S", dx: 0, dz: 1, yaw: 0 },
+	{ name: "W", dx: -1, dz: 0, yaw: Math.PI / 2 },
+];
+const PATROL_TICK_DISTANCE = 16;
+const PATROL_STEP_TIMEOUT_MS = 12_000;
+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 = true;
+	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;
+}
+
+function scoutState(ctx, bot) {
+	const here = bot?.entity?.position;
+	const now = Date.now();
+	const prev = ctx.scoutFoodState;
+	const expired = !prev || now - (prev.ts ?? 0) > 10 * 60_000;
+	const displaced = prev?.origin && here
+		? Math.hypot(here.x - prev.origin.x, here.z - prev.origin.z) > 128
+		: false;
+	if (expired || displaced) {
+		ctx.scoutFoodState = {
+			ts: now,
+			origin: here ? { x: here.x, z: here.z } : null,
+			tried: new Set(),
+		};
+		return ctx.scoutFoodState;
+	}
+	prev.ts = now;
+	if (!(prev.tried instanceof Set)) prev.tried = new Set(prev.tried ?? []);
+	return prev;
+}
+
+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")), PATROL_STEP_TIMEOUT_MS)),
+			]);
+		} catch (e) {
+			info("action", `scout-food: path step failed (${e?.message ?? e}); blind fallback ${cardinal.name}`);
+			try { bot.pathfinder?.stop?.(); } catch {}
+			const blind = await blindWalkOrTunnelOut(bot, {
+				yaw: cardinal.yaw ?? -Math.atan2(cardinal.dx, cardinal.dz),
+				dirName: cardinal.name,
+				blindMs: 12_000,
+				minMove: 6,
+				reason: `scout-food ${cardinal.name}`,
+			});
+			const progress = cardinalProgress(start, bot.entity.position, cardinal);
+			travelled = progress.along;
+			const target = nearestPassiveFoodMob(bot, 32);
+			if (target) return { aborted: false, travelled, target };
+			if (progress.total >= 4 && progress.along < 4) {
+				info("action", `scout-food: ${cardinal.name} blocked; drifted ${progress.driftName ?? "sideways"} ${progress.total.toFixed(1)}b`);
+				return {
+					aborted: false,
+					travelled,
+					blocked: true,
+					drifted: progress.driftName,
+					error: `blocked_${cardinal.name}`,
+				};
+			}
+			if (!blind.ok && progress.total < 4) {
+				return { aborted: false, travelled, error: e?.message ?? String(e) };
+			}
+			continue;
+		}
+		const progress = cardinalProgress(start, bot.entity.position, cardinal);
+		travelled = Math.max(travelled + PATROL_TICK_DISTANCE, progress.along);
+		// Rescan after every step.
+		const target = nearestPassiveFoodMob(bot, 32);
+		if (target) return { aborted: false, travelled, target };
+	}
+	return { aborted: false, travelled };
+}
+
+function cardinalProgress(start, pos, cardinal) {
+	const dx = (pos?.x ?? 0) - (start?.x ?? 0);
+	const dz = (pos?.z ?? 0) - (start?.z ?? 0);
+	const along = Math.max(0, dx * cardinal.dx + dz * cardinal.dz);
+	const total = Math.hypot(dx, dz);
+	return { along, total, driftName: dominantCardinal(dx, dz, cardinal.name) };
+}
+
+function dominantCardinal(dx, dz, fallback = null) {
+	if (Math.abs(dx) < 0.5 && Math.abs(dz) < 0.5) return fallback;
+	if (Math.abs(dx) >= Math.abs(dz)) return dx >= 0 ? "E" : "W";
+	return dz >= 0 ? "S" : "N";
+}
+
+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 state = scoutState(ctx, bot);
+		const triedCardinals = new Set([...(args?._triedCardinals ?? []), ...(state.tried ?? [])]);
+
+		// 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);
+		}
+		if (result.blocked) {
+			state.tried.add(next.heading.name);
+			return {
+				ok: false,
+				code: "blocked_heading",
+				detail: `blocked ${next.heading.name}, drifted ${result.drifted ?? "sideways"}`,
+				worldDelta: { moved: Math.round(result.travelled), heading: next.heading.name, drifted: result.drifted ?? null },
+			};
+		}
+		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];
+		state.tried.add(cardinal.name);
+		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);
+	if (result.blocked) {
+		return {
+			ok: false,
+			code: "blocked_heading",
+			detail: { tried: cardinal.name, travelled: Math.round(result.travelled), drifted: result.drifted ?? null, error: result.error ?? null },
+			worldDelta: { moved: Math.round(result.travelled), heading: cardinal.name, drifted: result.drifted ?? null, from_biome: biome },
+		};
+	}
+	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 === "blocked_heading") {
+			return { hint: "scout-food", reason: "chosen scout heading is blocked; retry another cardinal" };
+		}
+		if (result.code === "approached_target" || result.code === "no_path") {
+			return { hint: "scout-food", reason: "made or attempted progress toward food target; rescan from current position" };
+		}
+		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);
+	const start = bot.entity.position.clone?.() ?? { ...bot.entity.position };
+	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) {
+		try { bot.pathfinder?.stop?.(); } catch {}
+		const moved = horizontalDistance(start, bot.entity.position);
+		if (moved >= 6) {
+			return {
+				ok: false,
+				code: "approached_target",
+				detail: { target: target.entity.name, moved: Math.round(moved), mode: "pathfinder_partial", error: e?.message ?? "path failed" },
+				worldDelta: { moved: Math.round(moved), target: target.entity.name, mode: "pathfinder_partial" },
+			};
+		}
+		const yaw = yawToward(bot.entity.position, target.entity.position);
+		if (yaw !== null) {
+			const blind = await blindWalkOrTunnelOut(bot, {
+				yaw,
+				dirName: `toward-${target.entity.name}`,
+				blindMs: 8_000,
+				minMove: 4,
+				reason: `scout-food target ${target.entity.name}`,
+			});
+			const afterBlind = horizontalDistance(start, bot.entity.position);
+			if (blind.ok || afterBlind >= 4) {
+				return {
+					ok: false,
+					code: "approached_target",
+					detail: { target: target.entity.name, moved: Math.round(afterBlind), mode: "blind_target", error: e?.message ?? "path failed" },
+					worldDelta: { moved: Math.round(afterBlind), target: target.entity.name, mode: "blind_target" },
+				};
+			}
+		}
+		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 },
+	};
+}
+
+function horizontalDistance(a, b) {
+	return Math.hypot((b?.x ?? 0) - (a?.x ?? 0), (b?.z ?? 0) - (a?.z ?? 0));
+}
+
+function yawToward(from, to) {
+	if (!from || !to) return null;
+	const dx = to.x - from.x;
+	const dz = to.z - from.z;
+	if (Math.hypot(dx, dz) < 0.5) return null;
+	return -Math.atan2(dx, dz);
+}
+
+// Test exports
+export const __testing = {
+	CARDINALS, PATROL_TICK_DISTANCE, DEFAULT_COMMIT_DISTANCE, PATROL_STEP_TIMEOUT_MS,
+	nearestPassiveFoodMob, currentBiomeName, scanForFoodCapableNeighbourBiome,
+	cardinalProgress, dominantCardinal, horizontalDistance, yawToward,
+};