embark-ai 1.0.0

package/mc-server/bot/movementController.js

@@ -0,0 +1,110 @@
+// movementController.js — Single owner of bot.pathfinder.
+// All pathfinder writes route through this module; every transition is logged.
+// Priority model: CRITICAL(4) > HIGH(3) > NORMAL(2) > LOW(1) > PASSIVE(0)
+
+const NAVIGATE_TIMEOUT_MS = 15000
+
+const PRIORITY = Object.freeze({ CRITICAL: 4, HIGH: 3, NORMAL: 2, LOW: 1, PASSIVE: 0 })
+
+module.exports = function createMovementController(bot, goals, makeMovements, log) {
+  let owner = null              // { source, priority, type, startedAt }
+  let savedThinkingTimeout = null
+
+  function _acquire(source, priority, type) {
+    if (owner && priority < owner.priority) {
+      log.warn('movement_blocked', { source, priority, blockedBy: owner.source, blockedPriority: owner.priority })
+      return false
+    }
+    if (owner) {
+      log.debug('movement_preempted', { by: source, was: owner.source, heldMs: Date.now() - owner.startedAt })
+    }
+    owner = { source, priority, type, startedAt: Date.now() }
+    log.debug('movement_acquired', { source, priority, type })
+    return true
+  }
+
+  function release(source) {
+    if (!owner || owner.source !== source) return
+    log.debug('movement_released', { source, heldMs: Date.now() - owner.startedAt })
+    owner = null
+  }
+
+  // stop: stop pathfinder and release ownership if caller is current owner.
+  function stop(source) {
+    try { bot.pathfinder.stop() } catch {}
+    release(source)
+  }
+
+  // forceStop: stop pathfinder and clear ownership regardless of who holds it.
+  // Use when a higher-level interrupt (cancel, error, evade) supersedes movement.
+  function forceStop(source) {
+    try { bot.pathfinder.stop() } catch {}
+    if (owner) log.debug('movement_force_stopped', { by: source, was: owner.source, heldMs: Date.now() - owner.startedAt })
+    owner = null
+  }
+
+  // navigate: async goto — acquires ownership, drives pathfinder.goto, releases on settle.
+  // Rejects if blocked by a higher-priority owner or if pathfinding times out.
+  async function navigate(x, y, z, range = 3, priority = PRIORITY.NORMAL, source = 'task') {
+    if (!_acquire(source, priority, 'navigate')) {
+      throw new Error(`movement_blocked: ${source} (p${priority}) blocked by ${owner?.source} (p${owner?.priority})`)
+    }
+
+    bot.pathfinder.setMovements(makeMovements())
+    let timer
+    const pathPromise = bot.pathfinder.goto(new goals.GoalNear(x, y, z, range))
+    const timeoutPromise = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        try { bot.pathfinder.stop() } catch {}
+        reject(new Error(`pathfinding timeout to (${x},${y},${z})`))
+      }, NAVIGATE_TIMEOUT_MS)
+    })
+
+    try {
+      await Promise.race([pathPromise, timeoutPromise])
+    } finally {
+      clearTimeout(timer)
+      release(source)
+    }
+  }
+
+  // follow: fire-and-forget dynamic goal — acquires ownership and sets GoalFollow.
+  // Ownership persists until stop/forceStop/another follow call (no async release).
+  function follow(entity, range = 2, priority = PRIORITY.LOW, source = 'follow') {
+    if (!_acquire(source, priority, 'follow')) return false
+    try {
+      bot.pathfinder.setMovements(makeMovements())
+      bot.pathfinder.setGoal(new goals.GoalFollow(entity, range), true)
+    } catch (e) {
+      log.error('movement_follow_error', { source, message: e.message })
+      release(source)
+      return false
+    }
+    return true
+  }
+
+  // setThinkingTimeout / restoreThinkingTimeout: let callers temporarily tighten
+  // pathfinder planning budget (explore = 2s, escape = 5s). Saves original on first call.
+  function setThinkingTimeout(ms) {
+    if (savedThinkingTimeout === null) {
+      savedThinkingTimeout = bot.pathfinder.thinkingTimeout ?? 1500
+    }
+    try { bot.pathfinder.thinkingTimeout = ms } catch {}
+    log.debug('movement_thinking_timeout_set', { ms })
+  }
+
+  function restoreThinkingTimeout() {
+    if (savedThinkingTimeout === null) return
+    try { bot.pathfinder.thinkingTimeout = savedThinkingTimeout } catch {}
+    log.debug('movement_thinking_timeout_restored', { ms: savedThinkingTimeout })
+    savedThinkingTimeout = null
+  }
+
+  function isActive() {
+    return !!(bot.pathfinder?.isMoving() || bot.pathfinder?.goal != null)
+  }
+
+  function getOwner() { return owner ? { ...owner } : null }
+
+  return { PRIORITY, navigate, follow, stop, forceStop, release, setThinkingTimeout, restoreThinkingTimeout, isActive, getOwner }
+}

package/mc-server/bot/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "mc-agent-bot",
+  "version": "1.0.0",
+  "description": "Minecraft autonomous agent bot",
+  "main": "bot.js",
+  "scripts": {
+    "start": "node bot.js"
+  },
+  "dependencies": {
+    "mineflayer": "^4.37.0",
+    "mineflayer-pathfinder": "^2.4.5",
+    "mineflayer-pvp": "^1.3.2"
+  }
+}

package/mc-server/bot/positionGuard.js

@@ -0,0 +1,75 @@
+// positionGuard.js — Repair bot.entity.position in place when a hit corrupts it to NaN.
+//
+// A single knockback can make prismarine-physics integrate a bad velocity into a
+// NaN/null position (a long-standing Mineflayer quirk). The server's view of the bot
+// is fine, but the *client* is then stuck with a corrupt position for several seconds:
+// the bot can't pathfind or react, so it stands still until either a server position
+// packet arrives or fatalDesyncRecovery reconnects (~6s of "freeze when you hit her").
+//
+// This guard runs every physics tick (~50ms): if the live position has any non-finite
+// component, it overwrites it with the last cached valid position (from entityLiveness)
+// and zeroes any non-finite velocity component. Physics then continues from there with
+// finite values; the next server position packet corrects any small drift. Net effect:
+// the ~6s freeze becomes a ~50ms invisible blip.
+//
+// Because the restore makes entityLiveness see a valid position again, isDesynced()
+// never fires and fatalDesyncRecovery never reconnects in the common case. As a backstop
+// for the rare scenario where the corruption keeps reappearing despite restores, after
+// RECONNECT_AFTER_TICKS of continuous restoring we ask the recovery arbiter to reconnect.
+
+const RECONNECT_AFTER_TICKS = 100  // ~5s of nonstop restoring ⇒ something deeper is wrong
+
+function finite(n) { return typeof n === 'number' && Number.isFinite(n) }
+
+module.exports = function createPositionGuard(bot, liveness, log, recoveryEngine) {
+  let restoreCount       = 0
+  let consecutiveBad     = 0
+  let reconnectRequested = false
+
+  bot.on('physicsTick', () => {
+    const e = bot.entity
+    if (!e) return
+    const p = e.position
+    const v = e.velocity
+
+    const pBad = !p || !finite(p.x) || !finite(p.y) || !finite(p.z)
+    const vBad = !!v && (!finite(v.x) || !finite(v.y) || !finite(v.z))
+
+    if (!pBad && !vBad) {
+      consecutiveBad     = 0
+      reconnectRequested = false
+      return
+    }
+
+    consecutiveBad++
+
+    if (pBad) {
+      const cached = liveness.getCachedPos()
+      if (!cached) return  // nothing valid recorded yet (pre-spawn) — leave it; desync path will handle
+      if (!finite(p.x)) p.x = cached.x
+      if (!finite(p.y)) p.y = cached.y
+      if (!finite(p.z)) p.z = cached.z
+    }
+    if (vBad && v) {
+      if (!finite(v.x)) v.x = 0
+      if (!finite(v.y)) v.y = 0
+      if (!finite(v.z)) v.z = 0
+    }
+
+    restoreCount++
+    if (restoreCount === 1 || restoreCount % 20 === 0) {
+      log.warn('position_guard_restored', {
+        restoreCount, consecutiveBad, pBad, vBad,
+        restoredTo: pBad ? liveness.getCachedPos() : null,
+      })
+    }
+
+    if (consecutiveBad > RECONNECT_AFTER_TICKS && !reconnectRequested) {
+      reconnectRequested = true
+      log.error('position_guard_giving_up', { consecutiveBad, restoreCount })
+      try { recoveryEngine?.report('DESYNC', { source: 'position_guard_unrecoverable', consecutiveBad }) } catch {}
+    }
+  })
+
+  return { getRestoreCount: () => restoreCount }
+}

package/mc-server/bot/recoveryEngine.js

@@ -0,0 +1,315 @@
+// recoveryEngine.js — The single recovery arbiter.
+//
+// Recovery used to be multi-headed (diagnosis#2 §2.1): freeze-forensics,
+// fatalDesyncRecovery, the health-integrity watchdog, the task watchdog, the
+// movement-timeout streak, and the activity watchdog all independently detected
+// overlapping symptoms AND independently acted — and they raced (the log shows two
+// of them firing on the same incident seconds apart). Now there is one arbiter:
+// watchdogs DETECT and call report(symptom, context); this module DECIDES and ACTS.
+// Nothing else in the codebase calls bot.quit() — reconnection is owned here.
+//
+// SYMPTOMS (what watchdogs observe) → CLASSES (escalation ladders):
+//   DESYNC                  → DESYNC       position structurally invalid; reconnect only
+//   STUCK                   → STUCK        physically wedged; jiggle / blind-survival / escape
+//   MOVEMENT_TIMEOUT_STREAK → MOVEMENT     pathfinder timeout streak
+//   TASK_HUNG               → TASK         task watchdog tripped
+//   ENTITY_ORPHAN           → ENTITY       orphaned task state
+//   COMBAT_STALL            → COMBAT       combat-specific recovery
+//   CRITICAL_HP             → CRITICAL_HP  HP draining, damage pipeline blind, position VALID
+//   IDLE                    → IDLE         activity watchdog
+//
+// PRIORITY (highest first): DESYNC > STUCK > MOVEMENT_TIMEOUT_STREAK > TASK_HUNG >
+//   ENTITY_ORPHAN > COMBAT_STALL > CRITICAL_HP > IDLE. If a higher-priority class is
+//   mid-recovery (acted within its own cooldown), lower-priority reports are
+//   suppressed so the watchdogs can't pile on during an in-flight recovery.
+//
+// STUCK vs DESYNC (diagnosis#2 §1.3): being physically wedged in terrain and being
+// server-state desynced are different failure modes with different remedies.
+// STUCK  — live position is valid but not progressing: jiggle / blind-survival / escape.
+// DESYNC — live position is structurally invalid (NaN/null component): NO local maneuver
+//          can help; the only action at any level is to reconnect.
+//
+// Per-class failure counts decay after DECAY_MS of silence so transient issues don't
+// permanently poison the escalation level.
+
+const CLASSES = Object.freeze({
+  TASK:        'TASK',
+  STUCK:       'STUCK',
+  DESYNC:      'DESYNC',
+  MOVEMENT:    'MOVEMENT',
+  CRITICAL_HP: 'CRITICAL_HP',
+  IDLE:        'IDLE',
+  ENTITY:      'ENTITY',
+  COMBAT:      'COMBAT',
+})
+
+const SYMPTOMS = Object.freeze({
+  DESYNC:                  'DESYNC',
+  STUCK:                   'STUCK',
+  MOVEMENT_TIMEOUT_STREAK: 'MOVEMENT_TIMEOUT_STREAK',
+  TASK_HUNG:               'TASK_HUNG',
+  ENTITY_ORPHAN:           'ENTITY_ORPHAN',
+  COMBAT_STALL:            'COMBAT_STALL',
+  CRITICAL_HP:             'CRITICAL_HP',
+  IDLE:                    'IDLE',
+})
+
+const SYMPTOM_TO_CLASS = {
+  DESYNC:                  CLASSES.DESYNC,
+  STUCK:                   CLASSES.STUCK,
+  MOVEMENT_TIMEOUT_STREAK: CLASSES.MOVEMENT,
+  TASK_HUNG:               CLASSES.TASK,
+  ENTITY_ORPHAN:           CLASSES.ENTITY,
+  COMBAT_STALL:            CLASSES.COMBAT,
+  CRITICAL_HP:             CLASSES.CRITICAL_HP,
+  IDLE:                    CLASSES.IDLE,
+}
+
+// Highest priority first.
+const PRIORITY = [
+  'DESYNC',
+  'STUCK',
+  'MOVEMENT_TIMEOUT_STREAK',
+  'TASK_HUNG',
+  'ENTITY_ORPHAN',
+  'COMBAT_STALL',
+  'CRITICAL_HP',
+  'IDLE',
+]
+
+const COOLDOWN_MS = {
+  TASK:        8_000,
+  STUCK:       5_000,
+  DESYNC:      3_000,
+  MOVEMENT:    10_000,
+  CRITICAL_HP: 8_000,   // matches healthIntegrityWatchdog's TRIGGER_COOLDOWN_MS
+  IDLE:        120_000,
+  ENTITY:      10_000,
+  COMBAT:      5_000,
+}
+
+const DECAY_MS = {
+  TASK:        120_000,
+  STUCK:        60_000,
+  DESYNC:       60_000,
+  MOVEMENT:    120_000,
+  CRITICAL_HP:  60_000,
+  IDLE:        600_000,
+  ENTITY:       60_000,
+  COMBAT:       30_000,
+}
+
+const MAX_LEVEL = {
+  TASK: 4, STUCK: 3, DESYNC: 1, MOVEMENT: 3, CRITICAL_HP: 2, IDLE: 2, ENTITY: 2, COMBAT: 2,
+}
+
+module.exports = function createRecoveryEngine(deps) {
+  const { bot, movement, state, log } = deps
+  const { getTaskContext, cancelTask, replaceTask, runTask } = deps
+  const { taskBlindSurvival, taskEscape, taskExplore } = deps
+  const { writeExitReason } = deps
+
+  // Per-class state: failures, current escalation level, last attempt timestamp
+  const cs = {}
+  for (const cls of Object.values(CLASSES)) {
+    cs[cls] = { failures: 0, level: 0, lastAttemptAt: 0 }
+  }
+
+  // Once we've committed to a reconnect the client is going away — ignore all
+  // further reports so nothing tries to act on a disconnecting bot.
+  let quitPending = false
+
+  // ── Public entrypoint ───────────────────────────────────────────────────────
+  // Watchdogs call this and nothing else.
+  function report(symptom, context = {}) {
+    if (quitPending) return
+
+    const cls = SYMPTOM_TO_CLASS[symptom]
+    if (!cls) {
+      log.warn('recovery_unknown_symptom', { symptom, ...context })
+      return
+    }
+
+    // Cross-class priority suppression: if a higher-priority class acted within its
+    // own cooldown, it owns the situation right now — drop this lower-priority report.
+    const now = Date.now()
+    const myIdx = PRIORITY.indexOf(symptom)
+    for (let i = 0; i < myIdx; i++) {
+      const higherCls = SYMPTOM_TO_CLASS[PRIORITY[i]]
+      const hs = cs[higherCls]
+      if (hs.failures > 0 && (now - hs.lastAttemptAt) < COOLDOWN_MS[higherCls]) {
+        log.debug('recovery_suppressed', { symptom, class: cls, suppressedBy: higherCls, ...context })
+        return
+      }
+    }
+
+    _recover(cls, { symptom, ...context })
+  }
+
+  // ── Internal escalation ladder ──────────────────────────────────────────────
+  // Same-symptom dedup falls out of the per-class cooldown below.
+  function _recover(cls, context = {}) {
+    const s = cs[cls]
+    const now = Date.now()
+    const elapsed = now - s.lastAttemptAt
+
+    if (elapsed < COOLDOWN_MS[cls]) {
+      log.debug('recovery_cooldown', { class: cls, remainingMs: COOLDOWN_MS[cls] - elapsed, ...context })
+      return
+    }
+
+    // Decay: long silence between failures resets escalation
+    if (s.failures > 0 && elapsed > DECAY_MS[cls]) {
+      log.debug('recovery_decay_reset', { class: cls, hadLevel: s.level, hadFailures: s.failures })
+      s.failures = 0
+      s.level = 0
+    }
+
+    s.failures++
+    s.lastAttemptAt = now
+
+    const prevLevel = s.level
+    s.level = Math.min(s.failures, MAX_LEVEL[cls])
+
+    log.warn('recovery_attempt', {
+      class: cls,
+      level: s.level,
+      failures: s.failures,
+      ...(context.symptom  && { symptom: context.symptom }),
+      ...(context.source   && { source: context.source }),
+      ...(context.goalName && { goalName: context.goalName }),
+      ...(context.reason   && { reason: context.reason }),
+    })
+
+    if (s.level > prevLevel && prevLevel > 0) {
+      log.warn('recovery_escalated', { class: cls, from: prevLevel, to: s.level, ...context })
+    }
+
+    _execute(cls, s.level, context)
+  }
+
+  function reset(cls) {
+    const s = cs[cls]
+    if (!s) return
+    if (s.failures > 0) {
+      log.debug('recovery_class_reset', { class: cls, failures: s.failures, level: s.level })
+    }
+    s.failures = 0
+    s.level = 0
+  }
+
+  function _execute(cls, level, context) {
+    switch (cls) {
+      case CLASSES.TASK:
+        if (level <= 2) {
+          cancelTask()
+        } else if (level === 3) {
+          cancelTask()
+          movement.forceStop('recovery')
+          setTimeout(() => {
+            if (!getTaskContext().taskBusy && state.goal === 'idle') {
+              runTask('escaping', taskEscape)
+            }
+          }, 300)
+        } else {
+          _quitSafely(cls, level, context)
+        }
+        break
+
+      case CLASSES.STUCK:
+        if (level === 1) {
+          cancelTask()
+        } else if (level === 2) {
+          cancelTask()
+          replaceTask('blind_survival', taskBlindSurvival, { silent: true })
+        } else {
+          _quitSafely(cls, level, context)
+        }
+        break
+
+      case CLASSES.DESYNC:
+        // Position is structurally invalid — no control-state maneuver can fix it.
+        // Reconnect immediately, at any level.
+        _quitSafely(cls, level, context)
+        break
+
+      case CLASSES.MOVEMENT:
+        if (level === 1) {
+          movement.forceStop('recovery_movement')
+          setTimeout(() => {
+            if (!getTaskContext().taskBusy && state.goal === 'idle') {
+              runTask('escaping', taskEscape)
+            }
+          }, 300)
+        } else if (level === 2) {
+          cancelTask()
+          movement.forceStop('recovery_movement')
+          setTimeout(() => {
+            if (!getTaskContext().taskBusy && state.goal === 'idle') {
+              runTask('escaping', taskEscape)
+            }
+          }, 300)
+        } else {
+          _quitSafely(cls, level, context)
+        }
+        break
+
+      case CLASSES.CRITICAL_HP:
+        // HP draining and the normal damage pipeline can't react (NaN window) BUT the
+        // position is valid — so raw-control-state survival can still help. Sprint away
+        // at L1; escalate to a full escape task at L2.
+        if (level === 1) {
+          replaceTask('blind_survival', taskBlindSurvival, { silent: true })
+        } else {
+          cancelTask()
+          movement.forceStop('recovery_critical_hp')
+          setTimeout(() => {
+            if (!getTaskContext().taskBusy && state.goal === 'idle') {
+              runTask('escaping', taskEscape)
+            }
+          }, 300)
+        }
+        break
+
+      case CLASSES.IDLE:
+        if (level === 1) {
+          state.idleTicks = 999  // trigger autonomous decision on next state tick
+        } else {
+          if (!getTaskContext().taskBusy) runTask('exploring', taskExplore)
+        }
+        break
+
+      case CLASSES.ENTITY:
+        cancelTask()
+        if (level > 1) movement.forceStop('recovery_entity')
+        break
+
+      case CLASSES.COMBAT:
+        cancelTask()
+        break
+    }
+  }
+
+  // The single owner of bot.quit(). Writes the exit reason up front (so botSupervisor
+  // applies the right backoff even if bot.on('end') doesn't run cleanly), announces
+  // in-game, then quits after a short defer.
+  function _quitSafely(cls, level, context) {
+    if (quitPending) return
+    quitPending = true
+    const isDesync = cls === CLASSES.DESYNC
+    log.error('recovery_reconnect', { class: cls, level, ...context })
+    try { if (writeExitReason) writeExitReason(isDesync ? 'entity_desync' : 'stuck_reconnect') } catch {}
+    try { bot.chat(isDesync ? 'Entity desync — reconnecting.' : 'Stuck — reconnecting.') } catch {}
+    setTimeout(() => {
+      try { bot.quit() } catch { process.exit(0) }
+    }, 500)
+  }
+
+  function getState() {
+    return Object.fromEntries(
+      Object.entries(cs).map(([cls, s]) => [cls, { ...s }])
+    )
+  }
+
+  return { CLASSES, SYMPTOMS, report, reset, getState }
+}

package/mc-server/bot/safeMineflayer.js

@@ -0,0 +1,129 @@
+// safeMineflayer.js — Bounded wrappers for Mineflayer async API calls.
+//
+// Every Mineflayer API call that returns a Promise can hang indefinitely
+// if the server stops responding mid-operation (confirmed: bot.dig took 38s
+// on a sand block — events.jsonl 06:48:34–06:49:14). These wrappers enforce
+// per-call timeouts via Promise.race, mirroring navNear (bot.js:914-955).
+//
+// On timeout: rejects with a clear Error and emits a structured log event
+// so events.jsonl shows exactly which call stalled and for how long.
+//
+// Cleanup (pathfinder.stop, clearControlStates) is NOT done here — the
+// calling task's existing catch/finally handlers already own that path.
+
+const log = require('./logger')
+
+function withTimeout(promise, timeoutMs, eventName, meta = {}) {
+  let timer
+  const timeoutPromise = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      log.warn(eventName, { timeoutMs, ...meta })
+      reject(new Error(`${eventName}: timed out after ${timeoutMs}ms`))
+    }, timeoutMs)
+  })
+  return Promise.race([promise, timeoutPromise]).finally(() => clearTimeout(timer))
+}
+
+function safeDig(bot, block, timeoutMs = 8000) {
+  return withTimeout(bot.dig(block), timeoutMs, 'safe_dig_timeout', {
+    block: block?.name,
+    pos: block?.position
+      ? { x: block.position.x, y: block.position.y, z: block.position.z }
+      : null,
+  })
+}
+
+function safeCraft(bot, recipe, count, table, timeoutMs = 5000) {
+  return withTimeout(bot.craft(recipe, count, table), timeoutMs, 'safe_craft_timeout', {
+    count,
+    hasTable: !!table,
+  })
+}
+
+function safeEquip(bot, item, destination, timeoutMs = 3000) {
+  return withTimeout(bot.equip(item, destination), timeoutMs, 'safe_equip_timeout', {
+    item: item?.name,
+    destination,
+  })
+}
+
+function safeConsume(bot, timeoutMs = 5000) {
+  return withTimeout(bot.consume(), timeoutMs, 'safe_consume_timeout', {})
+}
+
+function safePlaceBlock(bot, referenceBlock, faceVector, timeoutMs = 5000) {
+  return withTimeout(bot.placeBlock(referenceBlock, faceVector), timeoutMs, 'safe_place_timeout', {
+    ref: referenceBlock?.name,
+    pos: referenceBlock?.position
+      ? { x: referenceBlock.position.x, y: referenceBlock.position.y, z: referenceBlock.position.z }
+      : null,
+  })
+}
+
+// safeAttack — bounded bot.pvp.attack() wrapper.
+//
+// bot.pvp.attack() is fire-and-forget: the only escape is waiting for
+// 'stoppedAttacking', which never fires if the target dies/desyncs/leaves
+// range without the pvp plugin noticing. Without a bound, the calling task
+// hangs for the full 30 s timeout (diagnosis#2 §1.4).
+//
+// Resolution order (whichever comes first):
+//   1. bot event 'stoppedAttacking'
+//   2. maxMs wall-clock timeout
+//   3. ~500 ms poll: target invalid / position gone / out of engage range / HP ≤ 0
+//
+// On early-out (timeout or poll): bot.pvp.stop() is called before resolving
+// so the pvp plugin doesn't keep trying to attack a gone target.
+//
+// Always resolves (never rejects) — attack tasks should not crash on a
+// target disappearing mid-fight; the task checks target.isValid after return.
+const SAFE_ATTACK_POLL_MS   = 500
+const SAFE_ATTACK_ENGAGE_R  = 6  // blocks — reasonable melee + bow range
+
+function safeAttack(bot, target, { maxMs = 10_000, label = 'target' } = {}) {
+  return new Promise(resolve => {
+    let done = false
+
+    function finish(reason) {
+      if (done) return
+      done = true
+      clearInterval(pollTimer)
+      clearTimeout(wallTimer)
+      bot.removeListener('stoppedAttacking', onStopped)
+
+      const timedOut = reason !== 'stopped'
+      if (timedOut) {
+        log.warn('safe_attack_timeout', { label, reason, maxMs })
+        try { bot.pvp.stop() } catch {}
+      } else {
+        log.debug('safe_attack_done', { label, reason })
+      }
+      resolve()
+    }
+
+    function onStopped() { finish('stopped') }
+
+    function poll() {
+      if (!target || !target.isValid)           return finish('target_invalid')
+      if (!target.position)                     return finish('target_no_position')
+      if ((target.health ?? 1) <= 0)            return finish('target_dead')
+      const botPos = bot.entity?.position
+      if (botPos && target.position.distanceTo(botPos) > SAFE_ATTACK_ENGAGE_R * 3) {
+        return finish('target_out_of_range')
+      }
+    }
+
+    bot.on('stoppedAttacking', onStopped)
+    const pollTimer = setInterval(poll, SAFE_ATTACK_POLL_MS)
+    const wallTimer = setTimeout(() => finish('timeout'), maxMs)
+
+    try {
+      bot.pvp.attack(target)
+    } catch (err) {
+      log.warn('safe_attack_start_error', { label, message: err.message })
+      finish('start_error')
+    }
+  })
+}
+
+module.exports = { safeDig, safeCraft, safeEquip, safeConsume, safePlaceBlock, safeAttack }