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/awareness/wedge-detector.js

@@ -0,0 +1,135 @@
+// Wedge detector — rolling-10min position bounding box.
+//
+// Sits above the skill layer (per the v0.3.1 design research). The
+// reflex calls observe() with the latest position once per tick; on
+// every call we evict older entries and recompute the bbox over the
+// trailing window. If the bbox stays small for long enough AND a need
+// has been unmet for long enough AND the same skill cycled enough
+// times, isWedged() returns true and the reflex injects a `relocate`
+// task that supersedes the current need until the bot has displaced
+// ≥200 blocks from the wedge centre.
+//
+// This is intentionally NOT inside any single skill — every skill
+// resets its own counters when re-entered, so per-skill stuck checks
+// can't break a multi-skill cycle.
+
+const WINDOW_MS = 10 * 60 * 1000;          // 10 minutes
+const MIN_BBOX_FOR_WEDGE = 50;             // <50 blocks max-dim → wedge
+const MIN_UNMET_NEED_MS = 5 * 60 * 1000;   // need unsatisfied for 5+ min
+const MIN_SKILL_CYCLES = 3;                // same need's skill restarted ≥3x
+
+let _samples = [];                          // { t, x, z }
+let _activeRelocation = null;               // { startedAt, fromCenter:{x,z}, headingName }
+let _needStartedAt = new Map();             // needId → t when first detected
+let _lastNeedId = null;
+
+export function _resetForTest() {
+	_samples = [];
+	_activeRelocation = null;
+	_needStartedAt = new Map();
+	_lastNeedId = null;
+}
+
+/**
+ * observe({ x, z, now, activeNeedId, recentSkillIds })
+ *
+ * Lightweight: called every reflex tick (~1-2s). Updates sliding
+ * window and need-duration accounting.
+ */
+export function observe({ x, z, now = Date.now(), activeNeedId = null, recentSkillIds = [] } = {}) {
+	if (typeof x !== "number" || typeof z !== "number") return;
+	_samples.push({ t: now, x, z });
+	// evict
+	const cutoff = now - WINDOW_MS;
+	while (_samples.length && _samples[0].t < cutoff) _samples.shift();
+
+	// Track need duration
+	if (activeNeedId !== _lastNeedId) {
+		_lastNeedId = activeNeedId;
+		if (activeNeedId && !_needStartedAt.has(activeNeedId)) {
+			_needStartedAt.set(activeNeedId, now);
+		}
+	}
+	if (activeNeedId && !_needStartedAt.has(activeNeedId)) {
+		_needStartedAt.set(activeNeedId, now);
+	}
+
+	// If a relocation is in progress, check whether we've travelled
+	// far enough to clear it.
+	if (_activeRelocation && typeof _activeRelocation.fromCenter?.x === "number") {
+		const dx = x - _activeRelocation.fromCenter.x;
+		const dz = z - _activeRelocation.fromCenter.z;
+		if (Math.hypot(dx, dz) >= 200) {
+			_activeRelocation = null;
+			// Reset all need-duration timers so the post-relocation env
+			// gets a fair shot at being labelled satisfied / unsatisfied.
+			_needStartedAt = new Map();
+		}
+	}
+}
+
+/**
+ * isWedged({ activeNeedId, recentSkillIds, now })
+ *   → { wedged: true, bboxDim, needAgeMs, skillCycles, centerX, centerZ } | { wedged: false }
+ */
+export function isWedged({ activeNeedId, recentSkillIds = [], now = Date.now() } = {}) {
+	if (_activeRelocation) return { wedged: false, reason: "relocating" };
+	if (_samples.length < 8) return { wedged: false, reason: "insufficient_samples" };
+
+	let xs = Infinity, xb = -Infinity, zs = Infinity, zb = -Infinity, cx = 0, cz = 0;
+	for (const s of _samples) {
+		if (s.x < xs) xs = s.x;
+		if (s.x > xb) xb = s.x;
+		if (s.z < zs) zs = s.z;
+		if (s.z > zb) zb = s.z;
+		cx += s.x; cz += s.z;
+	}
+	cx /= _samples.length; cz /= _samples.length;
+	const bboxDim = Math.max(xb - xs, zb - zs);
+	if (bboxDim >= MIN_BBOX_FOR_WEDGE) return { wedged: false, reason: "bbox_ok", bboxDim };
+
+	const needAgeMs = (activeNeedId && _needStartedAt.has(activeNeedId))
+		? now - _needStartedAt.get(activeNeedId)
+		: 0;
+	if (needAgeMs < MIN_UNMET_NEED_MS) return { wedged: false, reason: "need_recent", needAgeMs, bboxDim };
+
+	// Skill cycle count: how many distinct dispatches of the same skill
+	// appear in the recent rolling window.
+	const skillCycles = countCycles(recentSkillIds);
+	if (skillCycles < MIN_SKILL_CYCLES) return { wedged: false, reason: "few_cycles", skillCycles, bboxDim };
+
+	return { wedged: true, bboxDim, needAgeMs, skillCycles, centerX: cx, centerZ: cz };
+}
+
+/**
+ * markRelocationStarted({ x, z, heading })
+ *   The reflex calls this when it dispatches village.relocate. While
+ *   a relocation is in flight, isWedged() returns false (relocating)
+ *   so we don't fire a SECOND relocation on top.
+ */
+export function markRelocationStarted({ x, z, heading } = {}) {
+	_activeRelocation = {
+		startedAt: Date.now(),
+		fromCenter: { x, z },
+		headingName: heading?.name ?? "?",
+	};
+}
+
+export function activeRelocation() { return _activeRelocation; }
+
+function countCycles(ids) {
+	if (!Array.isArray(ids) || ids.length === 0) return 0;
+	// A "cycle" = a transition like A → B → A. Count those.
+	let cycles = 0;
+	for (let i = 2; i < ids.length; i++) {
+		if (ids[i] === ids[i - 2] && ids[i] !== ids[i - 1]) cycles++;
+		if (ids[i] === ids[i - 1] && ids[i - 1] === ids[i - 2]) cycles++;
+	}
+	return cycles;
+}
+
+// Test exports
+export const __testing = {
+	WINDOW_MS, MIN_BBOX_FOR_WEDGE, MIN_UNMET_NEED_MS, MIN_SKILL_CYCLES,
+	countCycles,
+};

runtime/awareness/wedge-detector.test.js

@@ -0,0 +1,104 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+	observe,
+	isWedged,
+	markRelocationStarted,
+	activeRelocation,
+	_resetForTest,
+	__testing,
+} from "./wedge-detector.js";
+
+const { WINDOW_MS, MIN_BBOX_FOR_WEDGE, MIN_UNMET_NEED_MS, MIN_SKILL_CYCLES, countCycles } = __testing;
+
+test("countCycles: empty / short → 0", () => {
+	assert.equal(countCycles([]), 0);
+	assert.equal(countCycles(["a"]), 0);
+	assert.equal(countCycles(["a", "b"]), 0);
+});
+
+test("countCycles: A→B→A counts as cycle", () => {
+	assert.equal(countCycles(["a", "b", "a"]), 1);
+	assert.equal(countCycles(["a", "b", "a", "b", "a"]), 3);
+});
+
+test("countCycles: same skill 3+ times in a row also counts", () => {
+	assert.equal(countCycles(["a", "a", "a"]), 1);
+	assert.equal(countCycles(["a", "a", "a", "a"]), 2);
+});
+
+test("isWedged: insufficient samples → not wedged", () => {
+	_resetForTest();
+	const r = isWedged({ activeNeedId: "food" });
+	assert.equal(r.wedged, false);
+	assert.equal(r.reason, "insufficient_samples");
+});
+
+test("isWedged: large bbox → not wedged", () => {
+	_resetForTest();
+	const t0 = 1_000_000_000_000;
+	// scatter across 200 blocks
+	for (let i = 0; i < 12; i++) {
+		observe({ x: i * 30, z: i * 25, now: t0 + i * 1000, activeNeedId: "food", recentSkillIds: [] });
+	}
+	const r = isWedged({ activeNeedId: "food", recentSkillIds: ["a", "b", "a", "b"], now: t0 + 13_000 });
+	assert.equal(r.wedged, false);
+	assert.equal(r.reason, "bbox_ok");
+});
+
+test("isWedged: tight bbox + old need + cycles → WEDGED", () => {
+	_resetForTest();
+	const t0 = 1_000_000_000_000;
+	// 12 samples within a 30-block bbox, spread across ~9 min so they
+	// stay inside the 10-min sliding window.
+	for (let i = 0; i < 12; i++) {
+		observe({
+			x: 500 + (i % 4) * 8,
+			z: 500 + Math.floor(i / 4) * 8,
+			now: t0 + i * 45_000,
+			activeNeedId: "food",
+			recentSkillIds: ["acquire-food", "explore.far", "acquire-food", "explore.far", "acquire-food"],
+		});
+	}
+	const r = isWedged({
+		activeNeedId: "food",
+		recentSkillIds: ["acquire-food", "explore.far", "acquire-food", "explore.far", "acquire-food", "explore.far"],
+		now: t0 + 12 * 45_000,
+	});
+	assert.equal(r.wedged, true, `expected wedged, got ${JSON.stringify(r)}`);
+	assert.ok(r.bboxDim < MIN_BBOX_FOR_WEDGE);
+	assert.ok(r.needAgeMs >= MIN_UNMET_NEED_MS);
+	assert.ok(r.skillCycles >= MIN_SKILL_CYCLES);
+});
+
+test("isWedged: recent need (under threshold) → not wedged", () => {
+	_resetForTest();
+	const t0 = 1_000_000_000_000;
+	for (let i = 0; i < 12; i++) {
+		observe({ x: 500, z: 500, now: t0 + i * 10_000, activeNeedId: "food" });
+	}
+	const r = isWedged({ activeNeedId: "food", recentSkillIds: ["a", "b", "a", "b"], now: t0 + 60_000 });
+	assert.equal(r.wedged, false);
+});
+
+test("markRelocationStarted blocks subsequent wedge for 200b", () => {
+	_resetForTest();
+	const t0 = 1_000_000_000_000;
+	markRelocationStarted({ x: 500, z: 500, heading: { name: "N" } });
+	assert.ok(activeRelocation());
+	// Stay tight bbox after relocation start
+	for (let i = 0; i < 12; i++) {
+		observe({ x: 510, z: 510, now: t0 + i * 60_000, activeNeedId: "food" });
+	}
+	const r = isWedged({ activeNeedId: "food", recentSkillIds: ["a", "b", "a", "b"] });
+	assert.equal(r.wedged, false);
+	assert.equal(r.reason, "relocating");
+});
+
+test("relocation clears after travelling ≥200 blocks", () => {
+	_resetForTest();
+	markRelocationStarted({ x: 0, z: 0, heading: { name: "N" } });
+	observe({ x: 250, z: 0, activeNeedId: "food" });
+	assert.equal(activeRelocation(), null, "relocation cleared after 250b displacement");
+});