embark-ai 1.0.0

package/mc-server/bot/entityLiveness.js

@@ -0,0 +1,121 @@
+// entityLiveness.js — Entity desync detection and degraded-position provider.
+//
+// Diagnosis §5 confirmed bot.entity.position x/z becomes NaN during Mineflayer
+// entity desync (velocity update with bad delta-time), and that this NaN window
+// can persist for 50+ seconds. A binary valid/invalid model is too coarse:
+// a briefly-invalid position shouldn't drop damage events, but a 30s NaN window
+// means the client is corrupted and the bot should quit and reconnect.
+//
+// Five liveness states (diagnosis §13B):
+//   LIVE_VALID              — position is live and finite
+//   LIVE_TRANSIENT_INVALID  — invalid for < 500ms (post-teleport glitch, safe to ignore)
+//   LIVE_STALE_USING_CACHE  — invalid but cached pos is < CACHE_MAX_MS old (degraded ok)
+//   LIVE_RECOVERING         — invalid > 500ms, cache too stale (degrade + emit events)
+//   LIVE_FATAL              — invalid > FATAL_THRESHOLD_MS (quit + reconnect)
+//
+// getBestPosition() implements degraded runtime mode (diagnosis §13E):
+//   instead of silently dropping operations, return the best available position
+//   with a source tag so callers can degrade gracefully instead of aborting.
+
+const TRANSIENT_MS       = 500
+const CACHE_MAX_MS       = 5000
+const FATAL_THRESHOLD_MS = 8000   // was 30000 — the desync owner reconnects at DESYNC_HARD_MS,
+                                  // so LIVE_FATAL should never be reached in a pure desync now.
+const DESYNC_HARD_MS     = 5000   // structurally-invalid position for this long ⇒ reconnect now
+
+const STATES = Object.freeze({
+  LIVE_VALID:             'LIVE_VALID',
+  LIVE_TRANSIENT_INVALID: 'LIVE_TRANSIENT_INVALID',
+  LIVE_STALE_USING_CACHE: 'LIVE_STALE_USING_CACHE',
+  LIVE_RECOVERING:        'LIVE_RECOVERING',
+  LIVE_FATAL:             'LIVE_FATAL',
+})
+
+function isValidVec(v) {
+  return v != null &&
+    typeof v.x === 'number' && Number.isFinite(v.x) &&
+    typeof v.y === 'number' && Number.isFinite(v.y) &&
+    typeof v.z === 'number' && Number.isFinite(v.z)
+}
+
+module.exports = function createEntityLivenessMonitor(bot, log) {
+  let currentState  = STATES.LIVE_VALID
+  let lastValidPos  = null   // { x, y, z } snapshot when last valid
+  let lastValidAt   = 0      // ms timestamp
+  let invalidSince  = null   // ms timestamp when invalidity began
+
+  function tick() {
+    const livePos = bot.entity?.position
+    const now = Date.now()
+
+    if (isValidVec(livePos)) {
+      const wasInvalid = currentState !== STATES.LIVE_VALID
+      lastValidPos  = { x: livePos.x, y: livePos.y, z: livePos.z }
+      lastValidAt   = now
+      invalidSince  = null
+      if (wasInvalid) {
+        log.info('liveness_state_change', {
+          from: currentState, to: STATES.LIVE_VALID,
+          recoveredAfterMs: invalidSince ? now - invalidSince : null,
+        })
+      }
+      currentState = STATES.LIVE_VALID
+      return
+    }
+
+    // Position is invalid — classify severity
+    if (!invalidSince) invalidSince = now
+    const invalidMs  = now - invalidSince
+    const cacheAgeMs = lastValidAt ? now - lastValidAt : Infinity
+
+    let next
+    if (invalidMs < TRANSIENT_MS) {
+      next = STATES.LIVE_TRANSIENT_INVALID
+    } else if (cacheAgeMs < CACHE_MAX_MS) {
+      next = STATES.LIVE_STALE_USING_CACHE
+    } else if (invalidMs < FATAL_THRESHOLD_MS) {
+      next = STATES.LIVE_RECOVERING
+    } else {
+      next = STATES.LIVE_FATAL
+    }
+
+    if (next !== currentState) {
+      log.warn('liveness_state_change', { from: currentState, to: next, invalidMs, cacheAgeMs })
+      currentState = next
+    }
+  }
+
+  // Returns the best available position with a quality tag, or null if nothing usable.
+  // source === 'live'    — fresh, fully trust it
+  // source === 'cached'  — recent cache, safe for most operations
+  // source === 'unknown' — stale/absent; caller should degrade or use blind behaviour
+  function getBestPosition() {
+    const livePos = bot.entity?.position
+    if (isValidVec(livePos)) {
+      return { pos: { x: livePos.x, y: livePos.y, z: livePos.z }, source: 'live' }
+    }
+    if (lastValidPos) {
+      const cacheAgeMs = lastValidAt ? Date.now() - lastValidAt : Infinity
+      if (cacheAgeMs < CACHE_MAX_MS) {
+        return { pos: lastValidPos, source: 'cached' }
+      }
+      // Cache is stale but it's all we have — return it as 'unknown' so callers
+      // can still attempt degraded reactions rather than doing nothing at all.
+      return { pos: lastValidPos, source: 'unknown' }
+    }
+    return null
+  }
+
+  function getState()      { return currentState }
+  function getCachedPos()  { return lastValidPos }
+  function getCachedAge()  { return lastValidAt ? Date.now() - lastValidAt : Infinity }
+  function getInvalidMs()  { return invalidSince ? Date.now() - invalidSince : 0 }
+
+  // True when the live position has been structurally invalid (NaN/null component,
+  // or entity absent) continuously for longer than DESYNC_HARD_MS. This is the single
+  // trigger for the fast reconnect path — a desync is binary, not graded: no local
+  // maneuver can fix it, so the only correct response is to quit and reconnect.
+  function isDesynced()    { return invalidSince != null && (Date.now() - invalidSince) > DESYNC_HARD_MS }
+
+  return { tick, getState, getBestPosition, getCachedPos, getCachedAge, getInvalidMs, isDesynced, STATES }
+}

package/mc-server/bot/env.js

@@ -0,0 +1,38 @@
+// env.js — Minimal .env loader (zero deps)
+// Looks up the project root by walking parent directories, loads .env if found.
+// Existing process.env values take precedence (so CLI/TUI can override).
+
+const fs   = require('fs')
+const path = require('path')
+
+function loadEnv() {
+  let dir = __dirname
+  for (let i = 0; i < 5; i++) {
+    const candidate = path.join(dir, '.env')
+    if (fs.existsSync(candidate)) {
+      try {
+        const content = fs.readFileSync(candidate, 'utf8')
+        for (const rawLine of content.split('\n')) {
+          const line = rawLine.trim()
+          if (!line || line.startsWith('#')) continue
+          const eq = line.indexOf('=')
+          if (eq === -1) continue
+          const key = line.slice(0, eq).trim()
+          let value = line.slice(eq + 1).trim()
+          if ((value.startsWith('"') && value.endsWith('"')) ||
+              (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1)
+          }
+          if (process.env[key] === undefined) process.env[key] = value
+        }
+      } catch {}
+      return candidate
+    }
+    const parent = path.dirname(dir)
+    if (parent === dir) break  // reached filesystem root
+    dir = parent
+  }
+  return null
+}
+
+module.exports = { loadEnv }

package/mc-server/bot/environmentPerception.js

@@ -0,0 +1,384 @@
+// environmentPerception.js — Real-time environmental perception layer.
+//
+// Continuously scans nearby world state and builds:
+//   - local hazard map  (fatal/damage/slow/liquid blocks in configurable radius)
+//   - traversability analysis (N/S/E/W classified as walkable/blocked/fall_risk/unsafe_*)
+//   - escape vector     (direction with lowest danger score)
+//   - hazard memory     (dangerous coordinates, TTL-evicted, max 100)
+//   - stuck classifier  (lava_immobilization/collision_deadlock/terrain_deadlock/…)
+//   - locomotion risk   (0–10 score)
+//
+// scan()         → full perception report
+// getLLMContext  → compact string for LLM prompt (no raw chunk data)
+// getHazardMemory→ read hazard memory entries
+
+'use strict'
+
+// ── Hazard taxonomy ────────────────────────────────────────────────────────────
+
+const SEVERITY = Object.freeze({ FATAL: 3, DAMAGE: 2, SLOW: 1, LIQUID: 1 })
+
+const HAZARD_FATAL  = new Set(['lava', 'fire', 'soul_fire'])
+const HAZARD_DAMAGE = new Set(['cactus', 'sweet_berry_bush', 'wither_rose', 'magma_block',
+                                'campfire', 'soul_campfire'])
+const HAZARD_SLOW   = new Set(['cobweb', 'soul_sand', 'mud', 'honey_block', 'powder_snow'])
+const HAZARD_LIQUID = new Set(['water'])
+const AIR_BLOCKS    = new Set(['air', 'cave_air', 'void_air'])
+
+const SCAN_RADIUS_DEFAULT = 12
+const HAZARD_TTL_MS       = 5 * 60 * 1000  // 5 minutes
+const HAZARD_MEMORY_MAX   = 100
+
+const DIRECTIONS = Object.freeze({
+  N: { dx: 0,  dz: -1, label: 'north' },
+  S: { dx: 0,  dz:  1, label: 'south' },
+  E: { dx: 1,  dz:  0, label: 'east'  },
+  W: { dx: -1, dz:  0, label: 'west'  },
+})
+
+// ── Module factory ─────────────────────────────────────────────────────────────
+
+module.exports = function createEnvironmentPerception(bot, log) {
+  // hazardMemory: array of { key, type, ts, pos } — oldest-first, evicted by age or length
+  const hazardMemory = []
+
+  // ── Block helpers ────────────────────────────────────────────────────────────
+
+  function _blockAt(x, y, z) {
+    try { return bot.blockAt(bot.vec3(x, y, z)) } catch { return null }
+  }
+
+  function _isAir(block) {
+    return !block || AIR_BLOCKS.has(block.name)
+  }
+
+  function _isSolid(block) {
+    return block != null && !AIR_BLOCKS.has(block.name) && block.boundingBox === 'block'
+  }
+
+  function _hazardSeverity(block) {
+    if (!block) return 0
+    if (HAZARD_FATAL.has(block.name))  return SEVERITY.FATAL
+    if (HAZARD_DAMAGE.has(block.name)) return SEVERITY.DAMAGE
+    if (HAZARD_SLOW.has(block.name))   return SEVERITY.SLOW
+    if (HAZARD_LIQUID.has(block.name)) return SEVERITY.LIQUID
+    return 0
+  }
+
+  function _hazardClass(block) {
+    if (!block) return null
+    if (HAZARD_FATAL.has(block.name))  return 'fatal'
+    if (HAZARD_DAMAGE.has(block.name)) return 'damage'
+    if (HAZARD_SLOW.has(block.name))   return 'slow'
+    if (HAZARD_LIQUID.has(block.name)) return 'liquid'
+    return null
+  }
+
+  function _coordKey(x, y, z) {
+    return `${Math.floor(x)},${Math.floor(y)},${Math.floor(z)}`
+  }
+
+  // ── Hazard memory ────────────────────────────────────────────────────────────
+
+  function _pruneMemory() {
+    const cutoff = Date.now() - HAZARD_TTL_MS
+    while (hazardMemory.length > 0 && hazardMemory[0].ts < cutoff) hazardMemory.shift()
+  }
+
+  function recordHazardPosition(x, y, z, type) {
+    const key = _coordKey(x, y, z)
+    if (!hazardMemory.find(e => e.key === key)) {
+      hazardMemory.push({ key, type, ts: Date.now(), pos: { x: Math.floor(x), y: Math.floor(y), z: Math.floor(z) } })
+      while (hazardMemory.length > HAZARD_MEMORY_MAX) hazardMemory.shift()
+    }
+  }
+
+  function isKnownHazard(x, y, z) {
+    const key = _coordKey(x, y, z)
+    return hazardMemory.some(e => e.key === key)
+  }
+
+  // ── Traversability classifier ────────────────────────────────────────────────
+  // Returns { label, score } for one horizontal direction.
+  // Score: 0=safe, 10=lethal — used to rank escape vectors.
+
+  function _classifyDirection(bx, by, bz, dx, dz) {
+    let worstLabel = 'walkable', worstScore = 0
+
+    for (const step of [1, 2]) {
+      const tx = bx + dx * step
+      const tz = bz + dz * step
+
+      const foot  = _blockAt(tx, by,     tz)
+      const head  = _blockAt(tx, by + 1, tz)
+      const floor = _blockAt(tx, by - 1, tz)
+      const sub1  = _blockAt(tx, by - 2, tz)
+      const sub2  = _blockAt(tx, by - 3, tz)
+
+      let label = 'walkable', score = 0
+
+      if (HAZARD_FATAL.has(foot?.name) || HAZARD_FATAL.has(head?.name)) {
+        label = (foot?.name === 'lava' || head?.name === 'lava') ? 'unsafe_lava' : 'unsafe_fire'
+        score = 10
+      } else if (HAZARD_DAMAGE.has(foot?.name) || HAZARD_DAMAGE.has(head?.name)) {
+        label = 'hazardous'; score = 6
+      } else if (HAZARD_LIQUID.has(foot?.name)) {
+        label = 'swim_risk'; score = 3
+      } else if (_isSolid(foot) && _isSolid(head)) {
+        label = 'blocked'; score = 7
+      } else if (!_isSolid(foot) && _isSolid(head)) {
+        label = 'low_ceiling'; score = 2
+      } else if (_isAir(foot) && _isAir(floor)) {
+        const depth = _isAir(sub1) ? (_isAir(sub2) ? 3 : 2) : 1
+        label = depth >= 3 ? 'fall_risk' : 'step_down'
+        score = depth >= 3 ? 7 : 1
+      } else if (isKnownHazard(tx, by, tz)) {
+        label = 'hazard_memory'; score = Math.max(score, 5)
+      }
+
+      if (HAZARD_SLOW.has(floor?.name)) score += 1
+
+      if (score > worstScore) { worstScore = score; worstLabel = label }
+      if (worstScore >= 10) break  // already worst possible
+    }
+
+    return { label: worstLabel, score: worstScore }
+  }
+
+  // ── Cliff detector ───────────────────────────────────────────────────────────
+
+  function _detectCliff(bx, by, bz) {
+    for (const [key, dir] of Object.entries(DIRECTIONS)) {
+      const tx = bx + dir.dx, tz = bz + dir.dz
+      if (_isAir(_blockAt(tx, by, tz)) &&
+          _isAir(_blockAt(tx, by - 1, tz)) &&
+          _isAir(_blockAt(tx, by - 2, tz))) {
+        return { hasCliff: true, direction: key, label: dir.label }
+      }
+    }
+    return { hasCliff: false, direction: null, label: null }
+  }
+
+  // ── Risk scorer ──────────────────────────────────────────────────────────────
+
+  function _computeRisk(s) {
+    let r = 0
+    if (s.maxSeverity >= SEVERITY.FATAL)  r += 5
+    if (s.maxSeverity >= SEVERITY.DAMAGE) r += 2
+    if (s.isEnclosed)  r += 2
+    if (s.cliff.hasCliff) r += 1
+    for (const v of Object.values(s.traversability)) {
+      if (['unsafe_lava','unsafe_fire','fall_risk'].includes(v)) r++
+    }
+    if (HAZARD_FATAL.has(s.feetBlock?.name)  || HAZARD_FATAL.has(s.headBlock?.name))  r += 4
+    if (HAZARD_DAMAGE.has(s.standingOn?.name)) r += 2
+    return Math.min(10, r)
+  }
+
+  // ── Stuck classifier ─────────────────────────────────────────────────────────
+
+  function _classifyStuck({ feetBlock, headBlock, hazards, traversability, locomotionRisk }) {
+    if (HAZARD_FATAL.has(feetBlock?.name))  return 'lava_immobilization'
+    if (HAZARD_FATAL.has(headBlock?.name))  return 'suffocation_hazard'
+    const blocked = Object.values(traversability).filter(v =>
+      ['blocked','unsafe_lava','unsafe_fire'].includes(v)
+    ).length
+    if (blocked >= 4) return 'collision_deadlock'
+    if (locomotionRisk >= 8) return 'terrain_deadlock'
+    if (HAZARD_LIQUID.has(feetBlock?.name)) return 'liquid_drag'
+    if (hazards.some(h => h.severity === SEVERITY.FATAL && h.dist < 3)) return 'lava_proximity'
+    return 'movement_blocked'
+  }
+
+  // ── Hazard summary text ──────────────────────────────────────────────────────
+
+  function _hazardSummary(hazards) {
+    if (!hazards.length) return 'clear'
+    const seen = new Set()
+    const parts = []
+    for (const h of hazards.slice(0, 5)) {
+      if (seen.has(h.type)) continue
+      seen.add(h.type)
+      const dir = Math.abs(h.dx) >= Math.abs(h.dz)
+        ? (h.dx > 0 ? 'E' : 'W')
+        : (h.dz > 0 ? 'S' : 'N')
+      parts.push(`${h.type.replace(/_/g,' ')} ${Math.round(h.dist)}m ${dir}`)
+    }
+    return parts.join('; ')
+  }
+
+  // ── Main scan ────────────────────────────────────────────────────────────────
+
+  function scan(radius = SCAN_RADIUS_DEFAULT) {
+    _pruneMemory()
+
+    if (!bot.entity?.position) return _invalid('no_entity')
+
+    const pos = bot.entity.position
+    // NaN/null component = entity desync (LIVE_FATAL window). Math.floor(NaN) = NaN,
+    // making every blockAt probe return null — scan would report "all clear" and
+    // escapeVector would default North. Reject early so callers see valid:false,
+    // not a plausible-looking zero-risk result.
+    if (!Number.isFinite(pos.x) || !Number.isFinite(pos.y) || !Number.isFinite(pos.z)) {
+      log.warn('perception_position_invalid', { x: pos.x, y: pos.y, z: pos.z })
+      return _invalid('position_nan')
+    }
+
+    const bx  = Math.floor(pos.x)
+    const by  = Math.floor(pos.y)
+    const bz  = Math.floor(pos.z)
+
+    // Collect hazards in sphere of radius
+    const hazards = []
+    const nearbyBlocksCompact = []
+    let maxSeverity = 0
+
+    for (let dx = -radius; dx <= radius; dx++) {
+      for (let dy = -2; dy <= 3; dy++) {
+        for (let dz = -radius; dz <= radius; dz++) {
+          if (dx*dx + dz*dz > radius*radius) continue
+          const block = _blockAt(bx+dx, by+dy, bz+dz)
+          if (!block) continue
+          const sev = _hazardSeverity(block)
+          if (sev <= 0) continue
+
+          const dist = Math.sqrt(dx*dx + dy*dy + dz*dz)
+          hazards.push({
+            type: block.name,
+            hazardClass: _hazardClass(block),
+            severity: sev,
+            dx, dy, dz, dist,
+          })
+          if (sev > maxSeverity) maxSeverity = sev
+          recordHazardPosition(bx+dx, by+dy, bz+dz, _hazardClass(block))
+
+          // Compact list (close range only)
+          if (Math.abs(dx) <= 4 && Math.abs(dy) <= 2 && Math.abs(dz) <= 4) {
+            nearbyBlocksCompact.push({ type: block.name, dx, dy, dz })
+          }
+        }
+      }
+    }
+
+    hazards.sort((a, b) => a.dist - b.dist)
+
+    const standingOn = _blockAt(bx, by-1, bz)
+    const feetBlock  = _blockAt(bx, by,   bz)
+    const headBlock  = _blockAt(bx, by+1, bz)
+
+    // Traversability per direction
+    const traversability = {}
+    const dirScores      = {}
+    for (const [key, dir] of Object.entries(DIRECTIONS)) {
+      const result = _classifyDirection(bx, by, bz, dir.dx, dir.dz)
+      traversability[key] = result.label
+      dirScores[key]      = result.score
+    }
+
+    // Escape vector: direction with lowest danger
+    const [bestDir] = Object.entries(dirScores).sort((a, b) => a[1] - b[1])
+    const escapeDir  = DIRECTIONS[bestDir[0]]
+    const escapeVector = {
+      direction: bestDir[0],
+      label:     escapeDir.label,
+      dx:        escapeDir.dx,
+      dz:        escapeDir.dz,
+      score:     bestDir[1],
+    }
+
+    // Enclosed: 3+ directions lethal/blocked
+    const blockedDirs = Object.values(traversability).filter(v =>
+      ['blocked','unsafe_lava','unsafe_fire','hazardous'].includes(v)
+    ).length
+    const isEnclosed = blockedDirs >= 3
+
+    const cliff = _detectCliff(bx, by, bz)
+
+    const locomotionRisk = _computeRisk({ maxSeverity, isEnclosed, cliff, traversability,
+                                           feetBlock, headBlock, standingOn })
+    const stuckClass     = _classifyStuck({ feetBlock, headBlock, hazards, traversability, locomotionRisk })
+    const hazardSummary  = _hazardSummary(hazards)
+
+    const result = {
+      valid:               true,
+      hazards:             hazards.slice(0, 8),
+      hazardSummary,
+      traversability,
+      escapeVector,
+      standingOn:          standingOn?.name || 'unknown',
+      feetBlock:           feetBlock?.name  || 'air',
+      headBlock:           headBlock?.name  || 'air',
+      locomotionRisk,
+      isEnclosed,
+      cliffNearby:         cliff.hasCliff,
+      cliffDirection:      cliff.label,
+      stuckClass,
+      nearbyBlocksCompact: nearbyBlocksCompact.slice(0, 12),
+      hazardMemorySize:    hazardMemory.length,
+    }
+
+    if (hazards.length > 0 || isEnclosed || cliff.hasCliff) {
+      log.info('environment_scan', {
+        hazardCount:   hazards.length,
+        closest:       hazards[0] ? `${hazards[0].type}@(${hazards[0].dx},${hazards[0].dy},${hazards[0].dz})` : null,
+        locomotionRisk,
+        isEnclosed,
+        cliffNearby:   cliff.hasCliff,
+        escapeDir:     escapeVector.direction,
+        stuckClass,
+      })
+    }
+
+    return result
+  }
+
+  // ── LLM context string ───────────────────────────────────────────────────────
+  // Compact symbolic text; fits within the existing prompt without bloat.
+
+  function getLLMContext(s) {
+    if (!s?.traversability) return 'perception: unavailable'
+    const travLines = Object.entries(s.traversability)
+      .map(([d, v]) => `  ${d}:${v}`)
+      .join('  ')
+    const flags = [
+      s.isEnclosed   && 'ENCLOSED',
+      s.cliffNearby  && `cliff-${s.cliffDirection}`,
+      s.locomotionRisk >= 7 && `HIGH-RISK(${s.locomotionRisk})`,
+    ].filter(Boolean).join(' ')
+
+    return [
+      `standing_on: ${s.standingOn}`,
+      `hazards: ${s.hazardSummary}`,
+      `risk: ${s.locomotionRisk}/10${flags ? ' ' + flags : ''}`,
+      `movement: ${travLines}`,
+      `escape: ${s.escapeVector.label}`,
+    ].join(' | ')
+  }
+
+  // Returns an explicitly-invalid scan result. Callers must check valid===false before
+  // trusting any fields — in particular locomotionRisk and escapeVector are meaningless.
+  function _invalid(reason) {
+    return {
+      valid:               false,
+      reason,
+      hazards:             [],
+      hazardSummary:       'position_invalid',
+      traversability:      { N:'unknown', S:'unknown', E:'unknown', W:'unknown' },
+      escapeVector:        { direction:'N', label:'north', dx:0, dz:-1, score:0 },
+      standingOn:          'unknown',
+      feetBlock:           'unknown',
+      headBlock:           'unknown',
+      locomotionRisk:      null,
+      isEnclosed:          false,
+      cliffNearby:         false,
+      cliffDirection:      null,
+      stuckClass:          'unknown',
+      nearbyBlocksCompact: [],
+      hazardMemorySize:    hazardMemory.length,
+    }
+  }
+
+  function getHazardMemory() { return [...hazardMemory] }
+
+  return { scan, getLLMContext, recordHazardPosition, isKnownHazard, getHazardMemory }
+}

package/mc-server/bot/fatalDesyncRecovery.js

@@ -0,0 +1,42 @@
+// fatalDesyncRecovery.js — Detect entity position desync; report it to the arbiter.
+//
+// When bot.entity.position has a NaN/null component (Mineflayer entity desync — a
+// velocity packet with a bad delta-time corrupts the position) for longer than
+// DESYNC_HARD_MS (~5s), the client is in an unrecoverable state: no local maneuver
+// (cancelTask, blind survival, escape) can fix it, because the bot genuinely isn't
+// where it thinks it is (diagnosis#2 §1.3). The only correct response is to reconnect.
+//
+// This module DETECTS and REPORTS only. recoveryEngine is the single arbiter that
+// owns the reconnect — see diagnosis#2 §2.1: recovery used to be multi-headed and the
+// heads raced (this module's own bot.quit() fired ~4s before / after others' would
+// have). Now the flow is: detect desync → recovery.report('DESYNC') → arbiter quits.
+// botSupervisor.js still gets its short reconnect backoff because the arbiter writes
+// exit_reason.json {reason:"entity_desync"} before quitting.
+
+const CHECK_INTERVAL_MS = 1000
+
+module.exports = function createFatalDesyncRecovery(bot, liveness, log, onDesync) {
+  let reported = false
+
+  const interval = setInterval(() => {
+    if (reported) return
+    if (!liveness.isDesynced()) return
+
+    reported = true
+    clearInterval(interval)
+    log.fatal('fatal_desync_quit', {
+      invalidMs:     liveness.getInvalidMs(),
+      cachedPos:     liveness.getCachedPos(),
+      livenessState: liveness.getState(),
+    })
+    try {
+      onDesync({ source: 'fatal_desync', invalidMs: liveness.getInvalidMs() })
+    } catch (e) {
+      log.error('fatal_desync_report_error', { message: e.message })
+      // Last-resort fallback: if the arbiter is unreachable, quit anyway.
+      try { bot.quit() } catch { process.exit(0) }
+    }
+  }, CHECK_INTERVAL_MS)
+
+  return { interval }
+}

package/mc-server/bot/goalRegistry.js

@@ -0,0 +1,49 @@
+// goalRegistry.js — Encapsulates state.goal mutations.
+// Every transition is logged with source, previous goal, and reason.
+// Invariant violations are logged loudly but still proceed — the mutation
+// is not blocked, which avoids introducing new failure modes during the refactor.
+
+const COMBAT_GOALS = new Set(['attacking'])
+
+module.exports = function createGoalRegistry(state, getOwnership, log) {
+  // getOwnership() → { taskBusy, currentTaskToken }
+
+  function setGoal(name, meta = {}) {
+    const prev = state.goal
+    const { source = 'unknown', token = null, reason = null } = meta
+    const { taskBusy, currentTaskToken } = getOwnership()
+
+    // Invariant: 'following' must not overwrite active combat
+    if (name === 'following' && COMBAT_GOALS.has(prev)) {
+      log.warn('invariant_violation', {
+        violation: 'follow_overwrites_combat',
+        prev, next: name, source,
+        ...(reason && { reason }),
+      })
+    }
+
+    // Invariant: goal should not be set to a task name when no task is active
+    // (source 'task_start' is exempt — taskBusy is set the line before setGoal is called)
+    if (name !== 'idle' && name !== 'following' && name !== 'resting' &&
+        source !== 'task_start' && !taskBusy) {
+      log.warn('invariant_violation', {
+        violation: 'task_goal_without_active_task',
+        next: name, source, taskBusy,
+        ...(reason && { reason }),
+      })
+    }
+
+    log.debug('goal_transition', {
+      prev,
+      next: name,
+      source,
+      taskBusy,
+      ...(reason && { reason }),
+      ...(token && { token: token.toString() }),
+    })
+
+    state.goal = name
+  }
+
+  return { setGoal }
+}