fix(perception): use numeric block ids — callback matchers silently fail under ViaBackwards

Root cause of "bot just stands still": every gather.* skill was using
bot.findBlock({ matching: (b) => names.includes(b.name) }), and under
mineflayer 1.21.4 + ViaBackwards the Block objects fed into the
callback have a wrong .name field (Block.type / numeric id is still
correct — this is mineflayer issue #2347). Every search returned null,
every skill reported "no_target", reflex looped wander → tunnel-out
forever. The bot's logs said "dispatch ok" while the operator watched
it pace in circles.

Proven live with a new diag.match skill on play.xmatic.team:
  findBlocks({matching: numericIds})              → 50 hits
  findBlocks({matching: (b) => b.name === ...})   →  0 hits  ← the bug
  findBlock({matching: (b) => b.name === ...})    → null     ← the bug
  findBlock({matching: numericIds})               → dark_oak_log @ (606,62,110)

After this fix the same bot from the same spawn dispatches gather.logs
and reaches the chop loop ("chop: dark_oak_log at 606,62,110 (tool=fists)")
instead of returning "no reachable log within 64 blocks".

Changes:
- runtime/perception.js (new): findBlocksByName / findNearestBlockByName
  centralise the numeric-id workaround for any future skill.
- runtime/actions.js: chopNearestTree, sleepInBed, placeCraftingTable now
  use perception. Also load mineflayer-tool plugin alongside collectblock
  (collectblock 1.6 hard-requires bot.tool to dispatch a dig).
- gather-stone, gather-wool, deposit-surplus rewritten to numeric-id
  search. gather-wool also loads mineflayer-tool.
- diagnose-scan.js (new): two diagnostic skills — diag.scan reports
  findBlocks counts per radius for common blocks; diag.match cross-tests
  the four matcher styles so this regression can be re-proven on demand.
- runtime/skills/index.js: registers diag.scan + diag.match.

Memory: project_findblock_callback_broken_under_viabackwards.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

runtime/skills/deposit-surplus.js

@@ -13,6 +13,9 @@ const { pathfinder, goals, Movements } = pathfinderPkg;
 
 import { applyProfile, PROFILES } from "../movement-profiles.js";
 import { info, warn } from "../log.js";
+import { findNearestBlockByName } from "../perception.js";
+
+const CHEST_NAMES = ["chest", "trapped_chest"];
 
 const KEEP_ALWAYS_NAME_RE = /(_axe|_pickaxe|_sword|_shovel|_hoe|_bed|bread|cooked_|apple|carrot|potato|wheat_seeds)$/;
 const STORABLE_NAME_RE = /(_log$|_stem$|cobblestone|cobbled_deepslate|deepslate|stone$|dirt|sand|gravel|wheat$|_planks$|stick$)/;
@@ -61,19 +64,13 @@ export const skill = Object.freeze({
 		if (!ctx?.bot) return { ok: false, code: "no_bot", detail: "bot missing" };
 		const surplus = pickSurplus(ctx.bot);
 		if (surplus.length === 0) return { ok: false, code: "nothing_to_deposit", detail: "no surplus stacks" };
-		const chest = ctx.bot.findBlock({
-			matching: (b) => b?.name === "chest" || b?.name === "trapped_chest",
-			maxDistance: 24,
-		});
+		const chest = findNearestBlockByName(ctx.bot, CHEST_NAMES, { maxDistance: 24 });
 		if (!chest) return { ok: false, code: "no_chest", detail: "no chest within 24 blocks" };
 		return { ok: true };
 	},
 	async execute(ctx) {
 		const bot = ctx.bot;
-		const chest = bot.findBlock({
-			matching: (b) => b?.name === "chest" || b?.name === "trapped_chest",
-			maxDistance: 24,
-		});
+		const chest = findNearestBlockByName(bot, CHEST_NAMES, { maxDistance: 24 });
 		if (!chest) return { ok: false, code: "no_chest", detail: "no chest after move", worldDelta: null };
 
 		ensurePathfinder(bot);

runtime/skills/diagnose-scan.js

@@ -0,0 +1,118 @@
+// diag.scan / diag.match — ground-truth probes of bot.findBlock(s).
+// Counts how many instances of common blocks are visible at increasing
+// radii. Lets the operator (or a stuck detector) tell two failure modes
+// apart:
+//
+//   case A: grass_block.32 > 0 but oak_log.96 = 0 → world has no trees
+//   case B: grass_block.32 = 0 → findBlocks itself is broken (mineflayer
+//                                issue #2347 under ViaBackwards), and
+//                                gather.* skills will silently no-op
+//                                forever no matter how far we walk.
+//
+// Writes nothing to journal. Always returns ok so it never wedges.
+
+const TYPES = ["grass_block", "dirt", "stone", "oak_log", "birch_log", "spruce_log", "jungle_log", "coal_ore", "iron_ore"];
+const RADII = [16, 32, 64, 96];
+const LOG_NAMES = ["oak_log", "dark_oak_log", "spruce_log", "birch_log", "jungle_log", "acacia_log", "mangrove_log", "cherry_log", "pale_oak_log"];
+
+export const matchSkill = Object.freeze({
+	id: "diag.match",
+	title: "Compare findBlock matcher styles for logs",
+	timeoutMs: 15_000,
+	preconditions(ctx) {
+		if (!ctx?.bot) return { ok: false, code: "no_bot", detail: "bot missing" };
+		return { ok: true };
+	},
+	async execute(ctx) {
+		const bot = ctx.bot;
+		const mcData = bot.registry;
+		const ids = LOG_NAMES.map((n) => mcData?.blocksByName?.[n]?.id).filter((x) => typeof x === "number");
+		const r = 32;
+		// Style A: numeric matching (what diag.scan uses, and what works)
+		const a = (bot.findBlocks({ matching: ids, maxDistance: r, count: 50 }) || []).length;
+		// Style B: callback matching by .name (what chopNearestTree uses, and what fails)
+		const b = (bot.findBlocks({
+			matching: (blk) => !!blk && !!blk.position && LOG_NAMES.includes(blk.name),
+			maxDistance: r,
+			count: 50,
+		}) || []).length;
+		// Style C: callback matching by .type (numeric id) — control
+		const c = (bot.findBlocks({
+			matching: (blk) => !!blk && ids.includes(blk.type),
+			maxDistance: r,
+			count: 50,
+		}) || []).length;
+		// Style D: singular findBlock with callback matcher (what chopNearestTree literally calls)
+		const d = bot.findBlock({
+			matching: (blk) => !!blk && !!blk.position && LOG_NAMES.includes(blk.name),
+			maxDistance: r,
+		});
+		// Style E: singular findBlock with numeric id array
+		const e = bot.findBlock({ matching: ids, maxDistance: r });
+		return {
+			ok: true,
+			code: "match_done",
+			detail: {
+				ids,
+				radius: r,
+				A_findBlocks_numeric: a,
+				B_findBlocks_callback_name: b,
+				C_findBlocks_callback_type: c,
+				D_findBlock_callback_name: d ? { name: d.name, type: d.type, pos: { x: d.position.x, y: d.position.y, z: d.position.z } } : null,
+				E_findBlock_numeric: e ? { name: e.name, type: e.type, pos: { x: e.position.x, y: e.position.y, z: e.position.z } } : null,
+			},
+			worldDelta: null,
+		};
+	},
+});
+
+export const skill = Object.freeze({
+	id: "diag.scan",
+	title: "Scan for findBlocks visibility",
+	timeoutMs: 20_000,
+	preconditions(ctx) {
+		if (!ctx?.bot) return { ok: false, code: "no_bot", detail: "bot missing" };
+		return { ok: true };
+	},
+	async execute(ctx) {
+		const bot = ctx.bot;
+		const mcData = bot.registry;
+		const here = bot.entity.position.clone();
+		const report = {};
+		for (const name of TYPES) {
+			const blk = mcData?.blocksByName?.[name];
+			if (!blk) {
+				report[name] = { absent_in_registry: true };
+				continue;
+			}
+			const perRadius = {};
+			for (const r of RADII) {
+				const hits = bot.findBlocks({ matching: blk.id, maxDistance: r, count: 50 }) || [];
+				perRadius[r] = hits.length;
+			}
+			report[name] = perRadius;
+		}
+		// Also blockAt directly underfoot and 5-block ring scan: this bypasses
+		// findBlocks entirely and proves whether the protocol decode is sane.
+		const under = bot.blockAt(here.offset(0, -1, 0));
+		const ring = {};
+		for (let dx = -5; dx <= 5; dx++) {
+			for (let dz = -5; dz <= 5; dz++) {
+				const b = bot.blockAt(here.offset(dx, -1, dz));
+				if (!b) continue;
+				ring[b.name] = (ring[b.name] || 0) + 1;
+			}
+		}
+		return {
+			ok: true,
+			code: "scan_done",
+			detail: {
+				pos: { x: +here.x.toFixed(1), y: +here.y.toFixed(1), z: +here.z.toFixed(1) },
+				under: under?.name ?? null,
+				ring_11x11_underfoot: ring,
+				findBlocks: report,
+			},
+			worldDelta: null,
+		};
+	},
+});

runtime/skills/gather-stone.js

@@ -10,9 +10,12 @@ const collectBlockPlugin =
 	collectBlockPkg.default?.plugin ??
 	collectBlockPkg.default ??
 	collectBlockPkg;
+import toolPkg from "mineflayer-tool";
+const toolPlugin = toolPkg.plugin ?? toolPkg.default?.plugin ?? toolPkg.default ?? toolPkg;
 
 import { pickaxes } from "./groups.js";
 import { info, warn } from "../log.js";
+import { findNearestBlockByName } from "../perception.js";
 
 const STONE_NAMES = ["stone", "cobblestone", "deepslate", "cobbled_deepslate", "andesite", "diorite", "granite"];
 
@@ -23,9 +26,16 @@ function ensurePathfinder(bot) {
 	pluginLoaded.add(bot);
 }
 
+let toolLoaded = new WeakSet();
+function ensureTool(bot) {
+	if (toolLoaded.has(bot)) return;
+	bot.loadPlugin(toolPlugin);
+	toolLoaded.add(bot);
+}
 let collectBlockLoaded = new WeakSet();
 function ensureCollectBlock(bot) {
 	ensurePathfinder(bot);
+	ensureTool(bot);
 	if (collectBlockLoaded.has(bot)) return;
 	bot.loadPlugin(collectBlockPlugin);
 	collectBlockLoaded.add(bot);
@@ -93,13 +103,10 @@ export const skill = Object.freeze({
 	async execute(ctx) {
 		const bot = ctx.bot;
 		const blacklist = getBlacklist(bot);
-		const target = bot.findBlock({
-			matching: (b) => {
-				if (!b || !b.position || !STONE_NAMES.includes(b.name)) return false;
-				const key = `${b.position.x},${b.position.y},${b.position.z}`;
-				return !blacklist.has(key);
-			},
+		// Numeric-id search — callback matcher returns 0 under ViaBackwards. See runtime/perception.js.
+		const target = findNearestBlockByName(bot, STONE_NAMES, {
 			maxDistance: 32,
+			predicate: (b) => !blacklist.has(`${b.position.x},${b.position.y},${b.position.z}`),
 		});
 		if (!target) {
 			return { ok: false, code: "no_target", detail: "no reachable stone within 32 blocks", worldDelta: null };

runtime/skills/gather-wool.js

@@ -9,10 +9,18 @@
 
 import collectBlockPkg from "mineflayer-collectblock";
 import pathfinderPkg from "mineflayer-pathfinder";
+import toolPkg from "mineflayer-tool";
+const toolPlugin = toolPkg.plugin ?? toolPkg.default?.plugin ?? toolPkg.default ?? toolPkg;
 
 import { info, warn } from "../log.js";
+import { findNearestBlockByName } from "../perception.js";
 
 const { pathfinder, goals, Movements } = pathfinderPkg;
+const WOOL_NAMES = [
+	"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",
+];
 const collectBlockPlugin =
 	collectBlockPkg.plugin ??
 	collectBlockPkg.default?.plugin ??
@@ -25,6 +33,7 @@ let pluginLoaded = new WeakSet();
 function ensurePlugins(bot) {
 	if (pluginLoaded.has(bot)) return;
 	bot.loadPlugin(pathfinder);
+	bot.loadPlugin(toolPlugin); // collectblock needs bot.tool
 	bot.loadPlugin(collectBlockPlugin);
 	pluginLoaded.add(bot);
 }
@@ -77,11 +86,8 @@ export const skill = Object.freeze({
 		ensurePlugins(bot);
 		setMovementsForGather(bot);
 
-		// 1. Placed wool block?
-		const woolBlock = bot.findBlock({
-			matching: (b) => b?.name && (b.name.endsWith("_wool") || b.name === "wool"),
-			maxDistance: 32,
-		});
+		// 1. Placed wool block? Numeric-id search — see runtime/perception.js.
+		const woolBlock = findNearestBlockByName(bot, WOOL_NAMES, { maxDistance: 32 });
 		if (woolBlock) {
 			info("action", `gather.wool: mining ${woolBlock.name} at ${woolBlock.position}`);
 			try {

runtime/skills/index.js

@@ -28,6 +28,7 @@ import { skill as wander } from "./wander.js";
 import { skill as exploreFar } from "./explore-far.js";
 import { skill as tunnelOut } from "./recovery-tunnel-out.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 chooseBase } from "./choose-base.js";
@@ -66,6 +67,8 @@ register(wander);
 register(exploreFar);
 register(tunnelOut);
 register(diagPhysics);
+register(diagScan);
+register(diagMatch);
 register(gatherStone);
 register(gatherWool);
 register(chooseBase);