feat(v0.4.0): finish vNext plan — anti-loop, skill-graph, worldDelta diff, flee→motion

Completes the remaining v0.4.0 plan items and one fix motivated by a live
in-game observation (flee hanging 30s against a persistent zombie).

- flee → MotionService.gotoSafe: structured {stuck|timeout|nopath} in ~4s with
  a blind-retreat fallback, instead of the observed 30s pathfinder hang + 3
  watchdog replans. Movements setup guarded so it is unit-testable.
- QW5 anti-loop (runtime/anti-loop.js): same skill failing >=3x in 5min →
  30min blacklist (reflex shouldSkip) + one-shot improvement_request
  (bot.js drainFired -> writeProposal).
- 4.1 closed-loop worldDelta: runSkill snapshots inventory before execute and
  attaches the real delta (_invObserved) to every successful result; opt-in
  skill.expectGain asserts the claimed gain or returns world_unchanged.
- 3.6 skill-graph (Plan4MC): declarative requires/produces for ~20 skills;
  prerequisitesMet/canRun/runnableFrontier; GoalManager annotates suggestions
  with blockedBy when prereqs are unmet.

+22 tests (472 total green). Live smoke confirmed dig-in works and no new
errors; flee loop is what this commit's flee migration addresses.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

runtime/skills/flee.js

@@ -39,7 +39,7 @@ export const skill = Object.freeze({
 	async execute(ctx, args = {}) {
 		const hit = nearestHostile(ctx.bot, args);
 		if (!hit) return { ok: false, code: "no_hostile", detail: "no matching hostile after precondition", worldDelta: null };
-		const res = await fleeFrom(ctx.bot, hit.entity, args.distance ?? 16);
+		const res = await fleeFrom(ctx.bot, hit.entity, args.distance ?? 16, { motion: ctx.motion, blindMs: args.blindMs });
 		if (res.ok) {
 			return {
 				ok: true,
@@ -48,8 +48,10 @@ export const skill = Object.freeze({
 				worldDelta: { fledTo: res.detail?.to ?? null },
 			};
 		}
+		// Prefer the structured code from MotionService (stuck/timeout/nopath);
+		// fall back to string-sniffing the legacy path's message.
 		const msg = String(res.detail ?? "");
-		const code = msg.includes("timed out") ? "timeout" : "failed";
+		const code = res.code ?? (msg.includes("timed out") ? "timeout" : "failed");
 		return { ok: false, code, detail: res.detail, worldDelta: null };
 	},
 	recover(ctx, result) {

runtime/skills/flee.test.js

@@ -0,0 +1,62 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { skill } from "./flee.js";
+
+function vec(x, y, z) {
+	return {
+		x, y, z,
+		clone() { return vec(x, y, z); },
+		distanceTo(o) { return Math.hypot(x - o.x, y - o.y, z - o.z); },
+		offset(dx, dy, dz) { return vec(x + dx, y + dy, z + dz); },
+	};
+}
+
+function fakeBot({ moveOnForward = 0 } = {}) {
+	const bot = {
+		entity: { position: vec(0, 64, 0), yaw: 0 },
+		entities: { z1: { name: "zombie", position: vec(2, 64, 0) } },
+		loadPlugin() {},
+		pathfinder: { goto: () => new Promise(() => {}), stop() {}, setMovements() {} },
+		setControlState(name, on) {
+			if (name === "forward" && on && moveOnForward) {
+				bot.entity.position = vec(moveOnForward, 64, 0);
+			}
+		},
+		async look() {},
+	};
+	return bot;
+}
+
+test("flee returns done when motion reaches the retreat point", async () => {
+	const bot = fakeBot();
+	const ctx = { bot, motion: { gotoSafe: async () => ({ ok: true, code: "reached", movedBlocks: 16 }) } };
+	const res = await skill.execute(ctx, {});
+	assert.equal(res.ok, true);
+	assert.equal(res.code, "done");
+	assert.ok(res.worldDelta.fledTo);
+});
+
+test("flee falls back to blind retreat and succeeds when it moves far enough", async () => {
+	const bot = fakeBot({ moveOnForward: 8 });
+	const ctx = { bot, motion: { gotoSafe: async () => ({ ok: false, code: "stuck", movedBlocks: 0 }) } };
+	const res = await skill.execute(ctx, { blindMs: 20 });
+	assert.equal(res.ok, true);
+	assert.equal(res.detail.mode, "blind-retreat");
+});
+
+test("flee surfaces the structured motion code when stuck and blind retreat fails", async () => {
+	const bot = fakeBot({ moveOnForward: 0 }); // never moves
+	const ctx = { bot, motion: { gotoSafe: async () => ({ ok: false, code: "stuck", movedBlocks: 0 }) } };
+	const res = await skill.execute(ctx, { blindMs: 20 });
+	assert.equal(res.ok, false);
+	assert.equal(res.code, "stuck");
+});
+
+test("flee precondition fails with no hostile", () => {
+	const bot = fakeBot();
+	bot.entities = {};
+	const pre = skill.preconditions({ bot }, {});
+	assert.equal(pre.ok, false);
+	assert.equal(pre.code, "no_hostile");
+});

runtime/skills/index.js

@@ -130,6 +130,18 @@ export const RUNNER_CODES = Object.freeze({
 	DONE: "done",
 });
 
+// Signed inventory diff between two count Maps (from InventoryLedger.mark/
+// snapshot). Used to attach the real world change to a skill result.
+function invDiff(before, after) {
+	const out = {};
+	const names = new Set([...(before?.keys?.() ?? []), ...(after?.keys?.() ?? [])]);
+	for (const n of names) {
+		const d = (after?.get?.(n) ?? 0) - (before?.get?.(n) ?? 0);
+		if (d !== 0) out[n] = d;
+	}
+	return out;
+}
+
 function normaliseResult(res, fallbackCode) {
 	const ok = !!res?.ok;
 	return {
@@ -222,6 +234,12 @@ export async function runSkill(id, ctx, args = {}) {
 		return result;
 	}
 
+	// WorldDelta diff layer (research §TL;DR): snapshot the inventory before
+	// execute so we can attach the REAL inventory change to the result and,
+	// for skills that opt in via `expectGain`, assert the claimed gain actually
+	// happened instead of trusting the skill's own bookkeeping.
+	const ledgerBefore = ctx?.ledger?.mark?.() ?? null;
+
 	const timeoutMs = skill.timeoutMs ?? 30_000;
 	let raw;
 	try {
@@ -277,6 +295,31 @@ export async function runSkill(id, ctx, args = {}) {
 			return failed;
 		}
 	}
+	// Closed loop: compare the inventory now vs the pre-execute baseline.
+	if (result.ok && ledgerBefore && ctx?.ledger) {
+		try { if (ctx.bot) ctx.ledger.update(ctx.bot); } catch {}
+		const observed = invDiff(ledgerBefore, ctx.ledger.snapshot());
+		if (Object.keys(observed).length > 0) {
+			result.worldDelta = { ...(result.worldDelta ?? {}), _invObserved: observed };
+		}
+		// Opt-in strict check: the world must show the claimed gain.
+		if (skill.expectGain) {
+			const gain = ctx.ledger.gainedSince(ledgerBefore, skill.expectGain.matcher);
+			if (gain < (skill.expectGain.min ?? 1)) {
+				const failed = {
+					ok: false,
+					code: "world_unchanged",
+					detail: `${id} reported ok but ${skill.expectGain.label ?? "expected items"} did not increase (gain ${gain})`,
+					worldDelta: result.worldDelta,
+				};
+				if (typeof skill.recover === "function") {
+					try { failed.recovery = skill.recover(ctx, failed) ?? null; } catch {}
+				}
+				return failed;
+			}
+		}
+	}
+
 	if (!result.ok && typeof skill.recover === "function") {
 		try {
 			result.recovery = skill.recover(ctx, result) ?? null;

runtime/skills/worlddelta.test.js

@@ -0,0 +1,77 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { runSkill, _registerForTest } from "./index.js";
+import { createInventoryLedger } from "../services/inventory-ledger.js";
+
+function botWithMutableInv(initial) {
+	let inv = initial;
+	return {
+		bot: { inventory: { items: () => inv } },
+		set(next) { inv = next; },
+	};
+}
+
+test("expectGain passes and attaches the observed inventory delta", async () => {
+	const m = botWithMutableInv([{ name: "cobblestone", count: 0 }]);
+	const ledger = createInventoryLedger();
+	ledger.update(m.bot);
+	const teardown = _registerForTest({
+		id: "test.mine-ok",
+		title: "t", timeoutMs: 1000,
+		preconditions: () => ({ ok: true }),
+		execute: async () => { m.set([{ name: "cobblestone", count: 5 }]); return { ok: true, code: "done", worldDelta: {} }; },
+		expectGain: { matcher: "cobblestone", min: 1, label: "cobblestone" },
+	});
+	const res = await runSkill("test.mine-ok", { bot: m.bot, ledger });
+	teardown();
+	assert.equal(res.ok, true);
+	assert.equal(res.worldDelta._invObserved.cobblestone, 5);
+});
+
+test("expectGain fails with world_unchanged when the world did not move", async () => {
+	const m = botWithMutableInv([{ name: "cobblestone", count: 0 }]);
+	const ledger = createInventoryLedger();
+	ledger.update(m.bot);
+	const teardown = _registerForTest({
+		id: "test.mine-liar",
+		title: "t", timeoutMs: 1000,
+		preconditions: () => ({ ok: true }),
+		execute: async () => ({ ok: true, code: "done", worldDelta: {} }), // claims ok, gains nothing
+		expectGain: { matcher: "cobblestone", min: 1, label: "cobblestone" },
+	});
+	const res = await runSkill("test.mine-liar", { bot: m.bot, ledger });
+	teardown();
+	assert.equal(res.ok, false);
+	assert.equal(res.code, "world_unchanged");
+});
+
+test("no ledger in ctx → no validation, skill passes untouched", async () => {
+	const teardown = _registerForTest({
+		id: "test.no-ledger",
+		title: "t", timeoutMs: 1000,
+		preconditions: () => ({ ok: true }),
+		execute: async () => ({ ok: true, code: "done", worldDelta: { foo: 1 } }),
+		expectGain: { matcher: "diamond", min: 1 },
+	});
+	const res = await runSkill("test.no-ledger", { bot: { inventory: { items: () => [] } } });
+	teardown();
+	assert.equal(res.ok, true);
+	assert.equal(res.worldDelta.foo, 1);
+});
+
+test("observed delta is attached even without expectGain", async () => {
+	const m = botWithMutableInv([{ name: "oak_log", count: 2 }]);
+	const ledger = createInventoryLedger();
+	ledger.update(m.bot);
+	const teardown = _registerForTest({
+		id: "test.observe-only",
+		title: "t", timeoutMs: 1000,
+		preconditions: () => ({ ok: true }),
+		execute: async () => { m.set([{ name: "oak_log", count: 6 }]); return { ok: true, code: "done", worldDelta: null }; },
+	});
+	const res = await runSkill("test.observe-only", { bot: m.bot, ledger });
+	teardown();
+	assert.equal(res.ok, true);
+	assert.equal(res.worldDelta._invObserved.oak_log, 4);
+});