v0.4.0 vNext — closed-loop world model + settlement contract (#29)

* feat(v0.4.0): vNext — closed-loop world model + settlement contract

Implements the vNext architecture from the research doc: demote the noisy
multi-rail planner in favour of a closed loop (world truth → invariant check)
plus a single utility-driven goal authority.

L1 services (fix no_drop / silent pathfinder hang first):
- InventoryLedger: diff-based "did I actually get it" verifier; acquire-food
  now confirms via ledger.gainedSince instead of the unreliable count/event.
- MotionService.gotoSafe: wall-clock timeout + progress watchdog +
  path_update(noPath/timeout) → structured {reached|stuck|timeout|nopath}.

L3 plan — unify the three competing rails (curriculum/manifesto/storyline):
- Settlement Contract: ordered M0–M9 milestones, each invariant-checked
  against an authoritative world view (early steps delegate to the proven
  curriculum; late game adds farming).
- InvariantChecker + predicate library; GoalManager selects the lowest unmet
  milestone via utility argmax (food-urgency preempts, DEPS-style).
- Wired into the scheduler: bot.js precomputes snapshot.contract; reflex.js
  consumes it in place of the storyline rail. Manifesto L0 still preempts.

Eval + robustness:
- Village Score (single 0..1 metric) on the snapshot + TUI "build" line.
- survive.dig-in skill + dusk_dig_in mode (exposed at night, no bed → cover).
- approach_block helper (GoalNear + lookAt, avoids GoalLookAtBlock #341).

+28 new tests (450 total green). LLM remains entirely off the tick path.

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

* 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>

---------

Co-authored-by: Yuriy Mayatnikov <mayatnikov@me.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

runtime/reflex.test.js

@@ -53,6 +53,7 @@ function makeCtx({
 	                          // tested directly in advisor-trigger.test.js.
 	disableStoryline = true, // storyline tested in goal/storyline.test.js
 	disableWedge = true,     // wedge tested in awareness/wedge-detector.test.js
+	disableContract = true,  // contract path tested below + goal-manager.test.js
 } = {}) {
 	const dispatches = [];
 	const ctx = {
@@ -69,6 +70,7 @@ function makeCtx({
 		disableAdvisor,
 		disableStoryline,
 		disableWedge,
+		disableContract,
 		dispatch(fn, label, opts = {}) {
 			dispatches.push({ fn, label, opts });
 		},
@@ -547,3 +549,65 @@ test("onComplete sets per-skill backoff on cooldown-class failures", () => {
 	cb({ ok: false, code: "missing_tool", detail: "no pickaxe" });
 	assert.ok((ctx.skillBackoff?.["gather.stone"] ?? 0) > Date.now());
 });
+
+// ---- v0.4.0 Settlement Contract integration --------------------------------
+
+test("contract suggestion drives dispatch (beats curriculum plan)", () => {
+	const { ctx, dispatches } = makeCtx({
+		disableContract: false,
+		snapshot: {
+			connected: true,
+			health: 20,
+			food: 20,
+			isDay: true,
+			// curriculum (legacy) would say gather.logs; the contract says farm.
+			curriculum: { plan: { skillId: "gather.logs" } },
+			contract: {
+				done: false,
+				milestone: { id: "M9_farm", title: "Start a wheat farm" },
+				suggestedSkill: { skillId: "farm.wheat" },
+			},
+		},
+	});
+	const out = runTick(ctx);
+	assert.equal(out.reflex, "curriculum");
+	assert.equal(dispatches[0].label, "farm.wheat");
+	assert.equal(out.source, "contract:M9_farm");
+});
+
+test("contract dispatches even when curriculum plan is exhausted (no wander)", () => {
+	const { ctx, dispatches } = makeCtx({
+		disableContract: false,
+		snapshot: {
+			connected: true,
+			health: 20,
+			food: 20,
+			isDay: true,
+			curriculum: null, // curriculum exhausted
+			contract: {
+				done: false,
+				milestone: { id: "M9_farm", title: "Start a wheat farm" },
+				suggestedSkill: { skillId: "farm.wheat" },
+			},
+		},
+	});
+	const out = runTick(ctx);
+	assert.equal(dispatches[0].label, "farm.wheat");
+});
+
+test("contract done → falls through to wander when nothing else suggests", () => {
+	const { ctx, dispatches } = makeCtx({
+		disableContract: false,
+		snapshot: {
+			connected: true,
+			health: 20,
+			food: 20,
+			isDay: true,
+			curriculum: null,
+			contract: { done: true, milestone: null, suggestedSkill: null },
+		},
+	});
+	const out = runTick(ctx);
+	assert.equal(out.reflex, "curriculum");
+	assert.equal(dispatches[0].label, "wander");
+});