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,367 @@
+// Storyline — canonical Minecraft survival quest the bot lives inside.
+//
+// Why this exists (rationale, 2026-05-27 evening):
+//
+// After v0.3.0 went live the bot got stuck in a loop:
+//   acquire-food (fail: no nearby food) → explore.far → pillar-up (fail) → repeat
+//
+// Manifesto + LLM advisor both correctly say "you need food" but
+// neither expresses *what concretely to do next*: scout 64 blocks N
+// for cows; chop oak nearby; place a crafting table. The bot has no
+// narrative arc, just a priority ranking of unsatisfied needs.
+//
+// Storyline fixes this by laying down the classic vanilla Minecraft
+// survival path as an ordered list of *concrete* steps. Each step
+// owns:
+//   - id, title, narration_ru (chat-friendly Russian one-liner)
+//   - completed(snapshot) → bool — detects if this step's goal has
+//     been achieved purely from snapshot
+//   - suggestSkill(snapshot) → { skillId, args? } | null — the
+//     concrete next dispatch for the step's pursuit
+//   - emergencyPause(snapshot) → bool — true if a higher-priority
+//     condition (low HP near hostile, lava under foot, etc.) means we
+//     should drop story progression for a tick
+//
+// The runtime/goal/state.js picker walks the list and returns the
+// first non-completed step, with its suggestSkill. That feeds into:
+//   - reflex.js dispatch picking (storyline overrides curriculum, but
+//     manifesto L0 alive emergencies still win)
+//   - persona/chatter.js — narrates step start in MC chat
+//   - coach/fast-advisor.js — user prompt includes current step so
+//     the LLM advice is anchored in the actual narrative
+//   - postmortem / reflect — the LLM can flag missing skills using
+//     the current step as concrete context
+//
+// Storyline order mirrors manifesto levels but is more *operational*:
+// where manifesto says "L2 tools_wood satisfied if you have a wood
+// pickaxe", storyline says "step first_tools: place crafting table,
+// craft wooden pickaxe + axe + sword, with these specific subgoals."
+
+const PICKAXE_WOOD = new Set(["wooden_pickaxe", "stone_pickaxe", "iron_pickaxe", "diamond_pickaxe", "netherite_pickaxe"]);
+const AXE_WOOD = new Set(["wooden_axe", "stone_axe", "iron_axe", "diamond_axe", "netherite_axe"]);
+const SWORD_WOOD = new Set(["wooden_sword", "stone_sword", "iron_sword", "diamond_sword", "netherite_sword"]);
+const PICKAXE_STONE = new Set(["stone_pickaxe", "iron_pickaxe", "diamond_pickaxe", "netherite_pickaxe"]);
+const BED_ITEMS = [
+	"white_bed", "orange_bed", "magenta_bed", "light_blue_bed", "yellow_bed",
+	"lime_bed", "pink_bed", "gray_bed", "light_gray_bed", "cyan_bed",
+	"purple_bed", "blue_bed", "brown_bed", "green_bed", "red_bed", "black_bed",
+];
+const FOOD_ITEMS = [
+	"bread", "cooked_beef", "cooked_porkchop", "cooked_chicken", "cooked_mutton",
+	"cooked_rabbit", "cooked_cod", "cooked_salmon", "baked_potato",
+	"apple", "carrot", "potato", "beetroot", "melon_slice", "sweet_berries",
+	"golden_apple", "golden_carrot",
+];
+const PASSIVE_FOOD_MOBS = new Set(["cow", "pig", "chicken", "sheep", "rabbit", "mooshroom"]);
+
+function hasSetItem(inv, set) {
+	if (!inv) return false;
+	for (const name of Object.keys(inv)) {
+		if (set.has(name) && inv[name] > 0) return true;
+	}
+	return false;
+}
+
+function hasAny(inv, names) {
+	if (!inv) return false;
+	for (const n of names) if ((inv[n] ?? 0) > 0) return true;
+	return false;
+}
+
+function countAny(inv, names) {
+	if (!inv) return 0;
+	let total = 0;
+	for (const n of names) total += inv[n] ?? 0;
+	return total;
+}
+
+function countLogs(inv) {
+	if (!inv) return 0;
+	let total = 0;
+	for (const [name, count] of Object.entries(inv)) {
+		if (name.endsWith("_log")) total += count;
+	}
+	return total;
+}
+
+function countPlanks(inv) {
+	if (!inv) return 0;
+	let total = 0;
+	for (const [name, count] of Object.entries(inv)) {
+		if (name.endsWith("_planks")) total += count;
+	}
+	return total;
+}
+
+function woodBudget(inv) {
+	if (!inv) return 0;
+	const placedOrCarriedTable = (inv.crafting_table ?? 0) > 0 ? 4 : 0;
+	return countLogs(inv) * 4 + countPlanks(inv) + placedOrCarriedTable;
+}
+
+function blockCount(snap, kind) {
+	const v = snap?.nearbyBlocks?.[kind];
+	if (typeof v === "number") return v;
+	if (v && typeof v.count === "number") return v.count;
+	return 0;
+}
+
+function hasLocalFoodMob(snap, maxDistance = 32) {
+	for (const e of snap?.nearbyEntities?.passives ?? []) {
+		if (!PASSIVE_FOOD_MOBS.has(e?.name)) continue;
+		if ((e.distance ?? Infinity) <= maxDistance) return true;
+	}
+	return false;
+}
+
+function emergencyPause(snap) {
+	if (!snap?.connected) return false;
+	const hp = snap.health ?? 20;
+	const food = snap.food ?? 20;
+	const hostile = snap.closestHostile;
+	if (hp <= 5) return true;
+	if (food <= 0) return true;
+	if (hostile && (hostile.distance ?? Infinity) <= 5 && hp <= 12) return true;
+	if (snap.hazards?.footBlock === "lava") return true;
+	return false;
+}
+
+// ---------------------------------------------------------------------------
+
+export const STORYLINE = Object.freeze([
+	{
+		id: "orient_self",
+		title: "Понять где я",
+		narration_ru: "Где я? Осмотрюсь и оценю место.",
+		completed(snap) {
+			if (!snap?.connected) return false;
+			const hp = snap.health ?? 20;
+			// Two completion paths: (a) classic — full HP + saw tangible
+			// blocks within 16 blocks. (b) timeout — HP=full + session
+			// >120s. Path (b) exists because in desert/ocean biomes the
+			// scan radius might never see logs/stone/crops/beds, and we
+			// were getting stuck on step 1 for hours.
+			if (hp < 18) return false;
+			const sawBlocks = blockCount(snap, "logs")
+				+ blockCount(snap, "stone")
+				+ blockCount(snap, "crops")
+				+ blockCount(snap, "beds") > 0;
+			if (sawBlocks) return true;
+			// Fallback: settled for long enough → call orient done and let
+			// later steps drive forward into the biome.
+			const sessionMs = snap._sessionMs ?? 0;
+			return sessionMs > 120_000;
+		},
+		suggestSkill(snap) {
+			// Look around — wander a bit to get a snapshot of what's nearby.
+			return { skillId: "explore.wander", args: { radius: 12 } };
+		},
+		emergencyPause,
+	},
+
+	{
+		id: "first_wood",
+		title: "Собрать стартовое дерево",
+		narration_ru: "Нужно дерево для первого крафта. Доберу минимум и сразу к верстаку.",
+		completed(snap) {
+			const inv = snap?.inventory ?? {};
+			return woodBudget(inv) >= 16
+				|| hasSetItem(inv, PICKAXE_WOOD)
+				|| hasSetItem(inv, AXE_WOOD)
+				|| hasSetItem(inv, SWORD_WOOD);
+		},
+		suggestSkill(snap) {
+			const trees = blockCount(snap, "logs");
+			if (trees > 0) return { skillId: "gather.logs" };
+			// No tree in sight — scout further. In a biome with no trees
+			// (desert, ocean) the bot must commit to a long heading; the
+			// curriculum's wedge detector (v0.3.1+) elevates this to
+			// village.relocate after a few cycles.
+			return { skillId: "explore.far", args: { searchFor: "logs" } };
+		},
+		emergencyPause,
+	},
+
+	{
+		id: "crafting_basics",
+		title: "Сделать верстак и палки",
+		narration_ru: "Делаю верстак и палки — без них ничего не скрафтить.",
+		completed(snap) {
+			const inv = snap?.inventory ?? {};
+			return ((inv.stick ?? 0) >= 2 && countPlanks(inv) >= 4)
+				|| hasSetItem(inv, PICKAXE_WOOD)
+				|| hasSetItem(inv, AXE_WOOD)
+				|| hasSetItem(inv, SWORD_WOOD);
+		},
+		suggestSkill(snap) {
+			const inv = snap?.inventory ?? {};
+			if (countPlanks(inv) < 4) return { skillId: "craft.planks" };
+			if ((inv.stick ?? 0) < 2) return { skillId: "craft.sticks" };
+			return null;
+		},
+		emergencyPause,
+	},
+
+	{
+		id: "first_tools",
+		title: "Деревянные орудия",
+		narration_ru: "Крафчу деревянный пикакс, топор и меч.",
+		completed(snap) {
+			const inv = snap?.inventory ?? {};
+			return hasSetItem(inv, PICKAXE_WOOD)
+				&& hasSetItem(inv, AXE_WOOD)
+				&& hasSetItem(inv, SWORD_WOOD);
+		},
+		suggestSkill(snap) {
+			const inv = snap?.inventory ?? {};
+			if (countPlanks(inv) < 4) {
+				if (countLogs(inv) > 0) return { skillId: "craft.planks" };
+				return { skillId: "gather.logs" };
+			}
+			if ((inv.stick ?? 0) < 2) return { skillId: "craft.sticks" };
+			if (!hasSetItem(inv, PICKAXE_WOOD)) return { skillId: "craft.wooden-pickaxe" };
+			if (!hasSetItem(inv, AXE_WOOD)) return { skillId: "craft.wooden-axe" };
+			if (!hasSetItem(inv, SWORD_WOOD)) return { skillId: "craft.wooden-sword" };
+			return null;
+		},
+		emergencyPause,
+	},
+
+	{
+		id: "first_food",
+		title: "Найти первую еду",
+		narration_ru: "Нужна еда — ищу корову, курицу или ягоды.",
+		completed(snap) {
+			// Done if we have a stock (≥2 food items) OR the hunger bar is
+			// comfortable (≥14). A sated bot should be chopping wood, not
+			// chasing a chicken it doesn't need — it'll grab food
+			// opportunistically when one wanders close.
+			if (countAny(snap?.inventory, FOOD_ITEMS) >= 2) return true;
+			if ((snap?.food ?? 20) >= 14) return true;
+			return false;
+		},
+		suggestSkill(snap) {
+			// Only reached when the bot is actually hungry (food < 14) and
+			// has no stock. Local mob → acquire-food; else long-range scout.
+			if (hasLocalFoodMob(snap)) return { skillId: "survive.acquire-food" };
+			return { skillId: "survive.scout-food" };
+		},
+		emergencyPause,
+	},
+
+	{
+		id: "shelter_minimal",
+		title: "Простой шелтер с кроватью",
+		narration_ru: "Поставлю кровать и стены — пережить ночь.",
+		completed(snap) {
+			return blockCount(snap, "beds") > 0;
+		},
+		suggestSkill(snap) {
+			const inv = snap?.inventory ?? {};
+			if (!hasAny(inv, BED_ITEMS)) {
+				const wool = countAny(inv, [
+					"white_wool", "orange_wool", "magenta_wool", "light_blue_wool",
+					"yellow_wool", "lime_wool", "pink_wool", "gray_wool",
+					"light_gray_wool", "cyan_wool", "purple_wool", "blue_wool",
+					"brown_wool", "green_wool", "red_wool", "black_wool",
+				]);
+				if (wool >= 3 && countPlanks(inv) >= 3) return { skillId: "craft.bed" };
+				if (wool < 3) return { skillId: "gather.wool" };
+			}
+			return { skillId: "village.build-shelter" };
+		},
+		emergencyPause,
+	},
+
+	{
+		id: "stone_tier",
+		title: "Каменные орудия",
+		narration_ru: "Шахта по камню — нужен каменный сет.",
+		completed(snap) {
+			return hasSetItem(snap?.inventory, PICKAXE_STONE);
+		},
+		suggestSkill(snap) {
+			const inv = snap?.inventory ?? {};
+			const cobble = inv.cobblestone ?? 0;
+			if (cobble < 4) return { skillId: "gather.stone" };
+			if ((inv.stick ?? 0) < 2) return { skillId: "craft.sticks" };
+			if (!hasSetItem(inv, PICKAXE_STONE)) return { skillId: "craft.stone-pickaxe" };
+			if (!hasAny(inv, ["stone_axe"])) return { skillId: "craft.stone-axe" };
+			return { skillId: "craft.stone-sword" };
+		},
+		emergencyPause,
+	},
+
+	{
+		id: "food_security",
+		title: "Запас еды на 16+",
+		narration_ru: "Делаю ферму или загон — еды должно быть с запасом.",
+		completed(snap) {
+			return countAny(snap?.inventory, FOOD_ITEMS) >= 16;
+		},
+		suggestSkill(snap) {
+			const inv = snap?.inventory ?? {};
+			if ((inv.wheat_seeds ?? 0) > 0 && blockCount(snap, "crops") > 0) {
+				return { skillId: "farm.wheat" };
+			}
+			return { skillId: "survive.acquire-food" };
+		},
+		emergencyPause,
+	},
+
+	{
+		id: "iron_age",
+		title: "Железо и печь",
+		narration_ru: "Иду за железом — пора в шахту глубже.",
+		completed(snap) {
+			const inv = snap?.inventory ?? {};
+			return (inv.iron_ingot ?? 0) >= 3 || (inv.iron_pickaxe ?? 0) > 0;
+		},
+		suggestSkill(snap) {
+			// No iron-specific gather skill yet — operator-facing improvement.
+			return { skillId: "gather.stone" };
+		},
+		emergencyPause,
+	},
+
+	{
+		id: "settle_base",
+		title: "Постоянная база",
+		narration_ru: "Выбираю место под деревню — нужно нормальное основание.",
+		completed(snap) {
+			return blockCount(snap, "beds") >= 1 && blockCount(snap, "storage") >= 1;
+		},
+		suggestSkill(snap) {
+			const inv = snap?.inventory ?? {};
+			if ((inv.chest ?? 0) === 0 && countPlanks(inv) >= 8) return { skillId: "craft.chest" };
+			if ((inv.chest ?? 0) > 0) return { skillId: "village.place-chest" };
+			return { skillId: "village.choose-base" };
+		},
+		emergencyPause,
+	},
+
+	{
+		id: "village_grow",
+		title: "Развивать деревню",
+		narration_ru: "Стою на ногах — теперь строю по плану деревни.",
+		completed() { return false; }, // ongoing — never auto-completes
+		suggestSkill(snap) {
+			const inv = snap?.inventory ?? {};
+			if ((inv.chest ?? 0) > 0 && countAny(inv, FOOD_ITEMS) > 0) {
+				return { skillId: "village.deposit-surplus" };
+			}
+			return { skillId: "village.build-shelter" };
+		},
+		emergencyPause,
+	},
+]);
+
+export function getStep(id) {
+	return STORYLINE.find((s) => s.id === id) ?? null;
+}
+
+// Test exports
+export const __testing = {
+	countLogs, countPlanks, countAny, hasAny, hasSetItem,
+	FOOD_ITEMS, BED_ITEMS, emergencyPause, blockCount, woodBudget, hasLocalFoodMob,
+};