feat(v0.4.1): make the Settlement Contract honest end-to-end

Patches each link of the closed-loop chain (world-truth -> invariant ->
dispatch -> worldDelta -> milestone) so the contract can no longer advance
on a lie or stall on an unreachable milestone, and surfaces the result on
the monitor.

- Unblock M6_lighting: add gather.coal producer (mirrors gather.stone,
  strict expectGain), register it, add the skill-graph node, and make
  curriculum.shelter.torch two-step (gather coal -> craft torch). craft.torch
  needed coal but no skill produced it, so the contract pinned on M6 forever
  and starved M7/M8/M9. One curriculum edit fixes both rails.
- M8 no longer falsely satisfied: build-shelter records locations.shelter
  only on real progress (setLocation moved below the no_progress guard).
- M2_bed made monotonic: sleepInBed writes locations.bed when the bot places
  its own bed, so M2 stays met after the carried bed item is consumed.
- Observability: new ink-free tui/format.js helper renders per-tick
  state / firing rail / active skill / blocked prerequisite / stall reason
  in the monitor header (fields bot.js already computes but never showed).
- Harden the valid-skill-id guardrail: skillRegistryPrompt preserves the
  "NEVER invent" footer when truncating (a growing registry was dropping it),
  and fix the stale "tech-tree > autonomous" reflex chain in the escalation
  prompt.

Tests: 494/494 passing; new build-shelter / invariants / format suites plus
skill-graph, curriculum, skill-registry cases. lint-patch clean. Deferred
audit findings recorded in plans/v0.4.0-vnext.md (local).

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

runtime/skills/build-shelter.js

@@ -172,13 +172,22 @@ export const skill = Object.freeze({
 			}
 		}
 
+		// Closed-loop integrity: a build that placed nothing AND skipped
+		// nothing never established a shelter. Do NOT record a shelter
+		// location in that case — M8_shelter's invariant locationExists(
+		// "shelter") is mere key-presence with no compensating clear, so a
+		// single all-throw build would falsely satisfy the milestone forever.
+		// We record the location only on real progress: placed>0, or skipped>0
+		// (idempotent resume — the blueprint was already satisfied by existing
+		// blocks).
+		if (placed === 0 && skipped === 0) {
+			return { ok: false, code: "no_progress", detail: "could not place any blocks", worldDelta: null };
+		}
+
 		// Record the shelter location so future skills can find it even if
 		// base gets re-scored.
 		setLocation(SHELTER_NAME, { x: center.x, y: center.y, z: center.z, radius: 2, note: `auto-built; ${placed} blocks placed` });
 
-		if (placed === 0 && skipped === 0) {
-			return { ok: false, code: "no_progress", detail: "could not place any blocks", worldDelta: null };
-		}
 		return {
 			ok: true,
 			code: "done",

runtime/skills/build-shelter.test.js

@@ -0,0 +1,69 @@
+// build-shelter closed-loop integrity: the shelter LOCATION (which satisfies
+// M8_shelter's locationExists("shelter") invariant) must be recorded ONLY when
+// the build actually made progress. A build that places nothing and skips
+// nothing must NOT mark M8 done. Runs against the isolated test state dir
+// (config.js detects --test), with a fake bot carrying a real minecraft-data
+// registry so applyProfile/Movements construct without a live server.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import mcDataLoader from "minecraft-data";
+
+import { skill } from "./build-shelter.js";
+import { setLocation, getLocation, removeLocation } from "../locations.js";
+
+const registry = mcDataLoader("1.21.4");
+
+function makePos(x, y, z) {
+	return { x, y, z, clone: () => makePos(x, y, z), offset: (dx, dy, dz) => makePos(x + dx, y + dy, z + dz) };
+}
+
+// blockKind: (target) => block-or-null describing what bot.blockAt returns at
+// every coordinate. We use it to make the whole world either air (no
+// placement possible) or solid (every placement succeeds).
+function makeBot(blockKind, planks = 30) {
+	return {
+		registry,
+		world: {},
+		entity: { position: makePos(0, 64, 0) },
+		pathfinder: { setMovements() {} },
+		inventory: { items: () => (planks > 0 ? [{ name: "oak_planks", count: planks }] : []) },
+		blockAt(p) { return blockKind(p); },
+		async equip() { return true; },
+		async placeBlock() { return true; },
+	};
+}
+
+test("failed build (placed 0, skipped 0) does NOT record a shelter location", async () => {
+	removeLocation("shelter");
+	setLocation("base", { x: 0, y: 64, z: 0, note: "test base" });
+
+	// Air everywhere → every findReferenceForPlacement returns null → nothing
+	// placed, nothing skipped.
+	const bot = makeBot(() => ({ name: "air", boundingBox: "empty" }));
+	const res = await skill.execute({ bot, owned: null });
+
+	assert.equal(res.ok, false);
+	assert.equal(res.code, "no_progress");
+	assert.equal(getLocation("shelter"), null, "shelter location must NOT be recorded on a no-progress build");
+
+	removeLocation("base");
+});
+
+test("successful build records the shelter location", async () => {
+	removeLocation("shelter");
+	setLocation("base", { x: 0, y: 64, z: 0, note: "test base" });
+
+	// Solid everywhere → every target has a reference block to place against.
+	const bot = makeBot((p) => ({ name: "stone", boundingBox: "block", position: makePos(p.x, p.y, p.z) }));
+	const res = await skill.execute({ bot, owned: null });
+
+	assert.equal(res.ok, true);
+	assert.equal(res.code, "done");
+	assert.ok(res.detail.placed > 0, "expected at least one block placed");
+	const shelter = getLocation("shelter");
+	assert.ok(shelter && shelter.x === 0 && shelter.z === 0, "shelter location recorded on success");
+
+	removeLocation("shelter");
+	removeLocation("base");
+});

runtime/skills/gather-coal.js

@@ -0,0 +1,169 @@
+// gather.coal — find a nearby coal ore block, equip a pickaxe (best
+// available), path to it and mine it. Modelled on gather.stone: stone-tier
+// mining needs at least a wooden pickaxe, the preconditions enforce that.
+//
+// Why this exists: craft.torch hard-requires coal (or charcoal), but no other
+// skill produces either, so M6_lighting was a permanent dead-end that pinned
+// the Settlement Contract forever and starved M7/M8/M9. gather.coal is the
+// missing producer. coal_ore drops coal directly and collectBlock awaits the
+// pickup, so the strict ledger check (expectGain) is safe here.
+
+import pathfinderPkg from "mineflayer-pathfinder";
+const { pathfinder, Movements } = pathfinderPkg;
+import collectBlockPkg from "mineflayer-collectblock";
+const collectBlockPlugin =
+	collectBlockPkg.plugin ??
+	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 COAL_ORE_NAMES = ["coal_ore", "deepslate_coal_ore"];
+
+let pluginLoaded = new WeakSet();
+function ensurePathfinder(bot) {
+	if (pluginLoaded.has(bot)) return;
+	bot.loadPlugin(pathfinder);
+	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);
+}
+
+function setMovementsForGather(bot) {
+	const m = new Movements(bot);
+	m.canDig = true;
+	m.allow1by1towers = false;
+	bot.pathfinder.setMovements(m);
+}
+
+const PICKAXE_PRIORITY = ["netherite_pickaxe", "diamond_pickaxe", "iron_pickaxe", "stone_pickaxe", "wooden_pickaxe"];
+async function equipBestPickaxe(bot) {
+	for (const name of PICKAXE_PRIORITY) {
+		const item = bot.inventory.items().find((i) => i.name === name);
+		if (item) {
+			try {
+				await bot.equip(item, "hand");
+				return name;
+			} catch {}
+		}
+	}
+	return null;
+}
+
+function withTimeout(promise, ms, label) {
+	let timer;
+	const timeout = new Promise((_, reject) => {
+		timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms / 1000}s`)), ms);
+	});
+	return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
+const coalBlacklist = new WeakMap();
+const BLACKLIST_TTL_MS = 5 * 60_000;
+
+function getBlacklist(bot) {
+	let m = coalBlacklist.get(bot);
+	if (!m) {
+		m = new Map();
+		coalBlacklist.set(bot, m);
+	}
+	const now = Date.now();
+	for (const [k, exp] of m) if (exp < now) m.delete(k);
+	return m;
+}
+
+export const skill = Object.freeze({
+	id: "gather.coal",
+	title: "Gather coal",
+	timeoutMs: 90_000,
+	// Closed-loop strict check: the milestone needs coal in hand, so we assert
+	// the world actually moved (coal/charcoal increased) and refuse to report
+	// "ok" if the dig left the inventory unchanged (runSkill → world_unchanged).
+	expectGain: { matcher: (k) => k === "coal" || k === "charcoal", min: 1, label: "coal" },
+	preconditions(ctx) {
+		if (!ctx?.bot) return { ok: false, code: "no_bot", detail: "bot missing" };
+		const available = pickaxes(ctx.bot);
+		if (available.size === 0) {
+			return { ok: false, code: "unsupported_version", detail: "no pickaxes in registry" };
+		}
+		const owned = ctx.bot.inventory.items().some((i) => available.has(i.name));
+		if (!owned) {
+			return { ok: false, code: "missing_tool", detail: "no pickaxe in inventory" };
+		}
+		return { ok: true };
+	},
+	async execute(ctx) {
+		const bot = ctx.bot;
+		const blacklist = getBlacklist(bot);
+		// Numeric-id search — callback matcher returns 0 under ViaBackwards. See runtime/perception.js.
+		const target = findNearestBlockByName(bot, COAL_ORE_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 coal ore within 32 blocks", worldDelta: null };
+		}
+
+		ensureCollectBlock(bot);
+		setMovementsForGather(bot);
+		const pickaxe = await equipBestPickaxe(bot);
+		info("action", `gather.coal: ${target.name} at ${target.position.x},${target.position.y},${target.position.z} (tool=${pickaxe ?? "fists"})`);
+		const targetPos = target.position.clone();
+		try {
+			try {
+				await withTimeout(bot.lookAt(targetPos.offset(0.5, 0.5, 0.5), true), 2_000, "lookAt(coal)");
+			} catch {}
+			await withTimeout(bot.collectBlock.collect(target), 60_000, "collectCoal");
+			const after = bot.blockAt(targetPos);
+			if (after && COAL_ORE_NAMES.includes(after.name)) {
+				warn("action", `gather.coal reported ok but block still at ${targetPos.x},${targetPos.y},${targetPos.z} — silent dig failure`);
+				const key = `${targetPos.x},${targetPos.y},${targetPos.z}`;
+				blacklist.set(key, Date.now() + BLACKLIST_TTL_MS);
+				return {
+					ok: false,
+					code: "silent_dig_failure",
+					detail: "block still exists after collect — protocol/anti-cheat issue",
+					worldDelta: null,
+				};
+			}
+			return {
+				ok: true,
+				code: "done",
+				detail: { blockType: target.name, at: targetPos },
+				worldDelta: { minedAt: targetPos, blockType: target.name },
+			};
+		} catch (e) {
+			warn("action", `gather.coal failed: ${e.message}`);
+			const key = `${target.position.x},${target.position.y},${target.position.z}`;
+			blacklist.set(key, Date.now() + BLACKLIST_TTL_MS);
+			const msg = String(e?.message ?? "");
+			const code = msg.includes("timed out") ? "timeout" : "failed";
+			return { ok: false, code, detail: e.message, worldDelta: null };
+		}
+	},
+	validate(ctx, result) {
+		return result.ok && !!result.worldDelta?.blockType;
+	},
+	recover(ctx, result) {
+		if (result.code === "no_target") return { hint: "wander", reason: "no coal ore within 32 blocks" };
+		return null;
+	},
+});

runtime/skills/index.js

@@ -35,6 +35,7 @@ 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 gatherCoal } from "./gather-coal.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";
@@ -84,6 +85,7 @@ register(diagPhysics);
 register(diagScan);
 register(diagMatch);
 register(gatherStone);
+register(gatherCoal);
 register(gatherWool);
 register(acquireFood);
 register(scoutFood);