Mineflayer Intelligent Player Bot Research¶

Date: 2026-07-09

Issue: GitLab #414, "Research Mineflayer intelligent-player bot ecosystem and architecture"

Status: research spike. This page is an implementation handoff, not a shipped feature promise.

Executive Recommendation¶

Keep Mineflayer as the base for joined-player behavior. It is still the most complete JavaScript Minecraft bot API, currently advertises Java support through 1.21.11, and already powers the repo-local scripts/dev/minecraft-player-bots prototype. Use minecraft-protocol as a companion for lightweight status, login-start, and modern-protocol fallback probes, not as the main behavior engine.

Do not embed Minecraft bot logic in agents/swarmhost-agent. The existing agent boundary is correct: the agent applies generic container, file, lifecycle, log, metrics, and support-operation work. Minecraft bot behavior should live in a game-specific runtime image or support container with a narrow control-plane contract.

At the time of this research, the customer-facing bot UI/API was temporary and misleading. Issue #415 removed those surfaces. Issue #426 later restored a new, dedicated Bots page only after live deployment proof covered the four bounded customer profiles, policy refusal, stop/cleanup, baseline restoration, and resource stability. Builder and Miner remain unavailable, and no public JSON bot-control API was restored.

Source Snapshot¶

Primary sources checked:

• Mineflayer README and API docs
• Mineflayer npm package
• node-minecraft-protocol
• mineflayer-pathfinder and its open issues
• mineflayer-collectblock
• mineflayer-tool
• mineflayer-pvp
• MineflayerArmorManager
• mineflayer-auto-eat
• prismarine-viewer
• prismarine-windows
• mineflayer-web-inventory
• mineflayer-statemachine
• mineflayer-scaffold
• MCProtocolLib
• Mindcraft
• Voyager project, Voyager GitHub, and Voyager arXiv paper

Package metadata was also checked with npm view from this worktree on 2026-07-09. The relevant snapshot is embedded in the comparison table below.

Current Swarm Hosts State¶

Repo inventory found during this spike:

Area	Current file(s)	Finding	Recommendation
Bot runtime package	packages/minecraft-bot-runtime/, images/support/minecraft-bot-runtime/Dockerfile	Node 22 support runtime uses Mineflayer 4.37.1, minecraft-protocol 1.66.2, mineflayer-pathfinder 2.4.5, desired-state authorization, redacted result events, bounded profile/count policies, cleanup reporting, and a Docker-layer minecraft_bot_session catalog operation.	Keep the immutable runtime and customer template allowlist aligned. Retain scripts/dev/minecraft-player-bots/ only as older validation-script compatibility.
Lightweight protocol clients	scripts/dev/minecraft_synthetic_clients.py	Performs Java status, ping, and login-start style traffic without joined gameplay.	Keep for reachability and relay/protocol checks. It is not a replacement for Mineflayer joined-player behavior.
Control-plane UI/API	apps/control-plane/app/templates/minecraft_bots.html, apps/control-plane/app/routes.py	A dedicated customer Bots page exposes server-owned Observer, Greeter, Patrol, and Survival helper templates. Retired managed-bot/synthetic-test routes return 410 Gone; internal session endpoints are not a public contract.	Preserve the profile-template boundary, visible stop/cleanup controls, and browser-only API boundary.
Control-plane state	apps/control-plane/app/state.py	Bot-session state records runtime version, policy, lifecycle, events, cleanup, and artifacts. The customer adapter fixes the endpoint and rejects mismatched profiles, counts, durations, reconnect settings, and unsupported templates.	Keep customer requests fail closed and keep result/event data sanitized.
Generic agent	agents/swarmhost-agent/	Search found no Minecraft bot handlers, and tests/test_agent_architecture_boundaries.py forbids game-specific markers including minecraft, rcon, synthetic_bot, and managed_bot.	Preserve this boundary. Add only generic support-operation primitives if needed. Put Minecraft behavior in image/support-container code.
Customer docs	docs/games/minecraft-bots.md, docs/games/minecraft.md, docs/api.md, apps/control-plane/app/changelog.py	Current docs describe the shipped profiles, limits, status/events, stop/cleanup behavior, unsupported features, and browser-only API boundary.	Keep public guidance aligned with the customer template catalog and production proof.
Existing research	docs/operations/minecraft-synthetic-player-activity.md	Earlier #76 research correctly recommended Mineflayer for joined-player activity, with minecraft-protocol for lightweight probes.	This page supersets that work for the production intelligent-bot epic while preserving the earlier prototype direction.

Plugin And Library Comparison¶

Package / project	Version snapshot	Behavior coverage	Maturity and maintenance risk	Version compatibility and limits	Swarm Hosts recommendation
mineflayer / npm	npm 4.37.1, modified 2026-05-03; package metadata says Node >=22.	High-level bot API: chat, movement controls, entity tracking, block queries, dig/place, inventory, crafting, chests, health, death/respawn events, item use, attacks, mounts, and plugin loading.	Best ecosystem anchor. Active PrismarineJS project, broad adoption, many examples and plugins.	README advertises Java 1.8 through 1.21.11. Package metadata is stricter than the README install note, so standardize production on Node 22.	Use as the primary joined-player runtime. Pin exact versions and validate each Swarm Hosts-supported Minecraft version before exposing behavior.
node-minecraft-protocol / npm	npm 1.66.2, modified 2026-05-13; Node >=22. Mineflayer depends on ^1.66.0.	Packet protocol, status/login/play clients, authentication/encryption plumbing.	Active, low-level, used under Mineflayer.	Broad Java protocol support, but behavior must be built by Swarm Hosts if used directly.	Keep for protocol/status helpers, fallback join/hold probes, and high-fanout non-gameplay load. Do not build a custom player AI on it first.
mineflayer-pathfinder / npm	npm 2.4.5, modified 2023-09-04.	Static, dynamic, and composite movement goals with Movements settings. Required by many behavior plugins.	Mostly stable but not freshly released. Open issues include 1.21.11 and >1.21.8 pathfinding reports, stuck cases, and obstacle handling.	Should be validated on every target server minor version, terrain type, and movement profile.	Use for V1 pathfinding with watchdogs: timeout, stuck detection, safe teleport/stop in validation worlds, and per-version canaries. Avoid risky bridge/scaffold movement in customer worlds.
mineflayer-collectblock / npm	npm 1.6.0, modified 2025-01-24.	Higher-level block and drop collection. Wraps pathfinder movement, tool selection, mining, drop pickup, chest deposit, and queued collections.	Useful but riskier than core Mineflayer. Some old issue history around block data, reachability, and target handling.	Depends on pathfinder and tool behavior, so it inherits their version and terrain risks.	V2 candidate for miner/collector profiles after pathfinding and tool selection pass live proofs. Keep it inside prepared zones with material and quota limits.
mineflayer-tool / npm	npm 1.2.0, modified 2022-05-11.	Automatically equips suitable tools or weapons before tasks.	Small and old, but simple.	Needs tests against current item registry and modded item assumptions.	Use only behind mining/collection tasks after Mineflayer inventory and item registry tests pass. Prefer explicit fallback if it cannot resolve a tool.
mineflayer-pvp / npm	npm 1.3.2, modified 2022-07-03.	Basic PvP and PvE target management; depends on pathfinder.	Old release and high abuse/product risk.	Combat behavior varies by server rules, anti-cheat, latency, and version.	Do not include in MVP or default customer controls. Consider future PvE-only defense in a prepared validation arena; keep player PvP disabled unless explicitly approved later.
MineflayerArmorManager / npm	npm 2.0.1, modified 2023-07-01; Node >=18.	Equips best available armor from inventory.	Moderate; simple plugin, not very fresh.	Depends on item metadata and equipment slots matching target version.	V2 survival helper. Safe if limited to inventory the bot already has and tested on 1.21.x.
mineflayer-auto-eat / npm	npm 5.0.3, modified 2025-08-01.	Automatic food selection/eating based on hunger and health, with banned-food and timeout settings.	Not PrismarineJS-owned but more recent than several behavior plugins.	Needs survival-mode validation and item registry checks.	Good V1/V2 survival candidate. Enable only in survival profiles, with configured banned foods and action timeouts.
prismarine-viewer / npm	npm 1.33.0, modified 2025-02-09.	Web/headless bot or world visualization, path drawing, screenshots/video streams.	Useful diagnostic tool, but native/headless rendering can add dependency friction.	README lists viewer support through 1.21.4, behind Mineflayer's 1.21.11 support.	Use for operator/debug artifacts and validation screenshots, not as a customer-required runtime dependency in MVP.
prismarine-windows / npm	npm 2.10.0, modified 2026-03-30.	Window/inventory representation.	Active PrismarineJS component; lower-level helper.	Good fit for window modeling, but Mineflayer already exposes common inventory/window APIs.	Use indirectly through Mineflayer unless a runtime diagnostic needs direct window serialization.
mineflayer-web-inventory / npm	npm 1.8.5, modified 2024-03-22.	Web inventory viewer for Mineflayer windows, real-time updates.	Third-party, moderate age.	Visual helper only; do not rely on it for game logic.	Optional validation/debug artifact. Do not expose raw inventory viewer to customers until auth, isolation, and visual privacy are designed.
mineflayer-statemachine / npm	npm 1.7.0, modified 2023-01-23.	Finite-state behavior orchestration, target passing, reusable behavior nodes.	Useful pattern, older release.	Movement behaviors rely on pathfinder.	Either use it as a reference or vendor a small internal behavior-state layer. Production bots need explicit states, timeouts, and recovery regardless of this package choice.
mineflayer-scaffold	Deprecated by its README in favor of pathfinder.	Dig/build-to-target scaffolding.	Deprecated.	Older navigation dependency.	Do not use. Implement safe building as explicit blueprint placement plus pathfinder, not deprecated scaffold traversal.
MCProtocolLib	GitHub Java library; latest GitHub release shown as 1.21.4-1 on 2025-01-18 during this check.	Low-level Java protocol library for custom clients, bots, and servers.	Mature Java alternative, but not aligned with current Node prototype.	Would require Swarm Hosts to implement most behavior itself.	Do not switch for MVP. Reconsider only if Node ecosystem cannot satisfy a future protocol or auth requirement.
Mindcraft	Active LLM + Mineflayer project; README recommends Java up to 1.21.11 and warns against public servers with code writing enabled.	LLM-driven agents, profiles, task execution, local/API model support.	Valuable architecture reference, not drop-in product code. Explicit code-execution/injection warning is a major product risk.	Requires API keys or local model stack. Native dependency and model/provider complexity.	Use as research inspiration for optional V2 LLM chat/planning. Do not ship dynamic LLM code execution or customer-editable agent code.
Voyager / paper	2023 research project using LLM-generated code, skill library, automatic curriculum, and Mineflayer environment.	Open-ended exploration and skill learning, not product-hosting operations.	Strong research signal for skill-library/critic loops, but heavyweight and not a managed-host feature.	Requires a controlled Minecraft instance, model credentials, and code-generation safeguards.	Use the skill-library concept for future curated skills. Do not expose autonomous code generation to customer servers.

Behavior Findings¶

Pathfinding And Navigation¶

Mineflayer core provides low-level movement controls, entity/world state, block queries, and physics. mineflayer-pathfinder is the practical navigation layer for goals, movements, and following entities or positions.

Production implications:

• Validate pathfinder on each Swarm Hosts Minecraft version, especially 1.21.x. Mineflayer itself advertises 1.21.11 support, but pathfinder has recent open issues around >1.21.8 behavior.
• Add stuck recovery: movement deadline, no-position-change detector, goal cancellation, safe stop, and a reportable reason.
• Disable risky scaffolding/bridging in customer worlds. The pathfinder issue history includes block placement while bridging failures; this is not an MVP customer behavior.
• Keep a protocol-only fallback for newest protocol compatibility. The existing runner already holds modern sessions through minecraft-protocol when full Mineflayer behavior is not safe; this is good as a degraded health proof, not as a behavior profile.

Building, Placing, Mining, And Collection¶

Mineflayer core exposes bot.dig, bot.placeBlock, bot.equip, inventory state, and block queries. mineflayer-collectblock can combine pathfinding, tool selection, mining, and drop pickup. mineflayer-tool helps choose the right tool.

Production implications:

• MVP building should be blueprint/place-only in a prepared validation area, not arbitrary chat-driven "build anything" behavior.
• Mining should be scoped to allowed materials, maximum block count, maximum radius, and explicit prepared zones. Default customer worlds should not allow automated griefing.
• Require backup or disposable-world proof before any destructive profile is available.
• Treat collectblock as V2 after pathfinding and tool selection are proven against current Minecraft and modded item registries.

Chat And LLM Boundaries¶

Mineflayer supports chat and chat-pattern APIs. The repo already blocks slash commands and caps chat text length for existing temporary bot flows; keep those rules.

Production implications:

• Default chat should be scripted and bounded: one-line messages, cooldowns, per-session limits, no slash commands, no impersonation of operators, and visible bot usernames.
• The hidden bot-session runtime accepts only on-join scripted chat templates with redacted previews and safety-decision events. Slash commands, multiline text, over-limit messages, and excessive session quotas are rejected before bot.chat() is called.
• LLM chat should be optional V2, not MVP. Put it behind tenant opt-in, content moderation, rate limits, transcript audit, and a "no commands/no secrets/no code execution" policy.
• Dynamic code generation, as seen in research projects such as Voyager and Mindcraft, is too dangerous for hosted customer servers unless it is replaced with a curated skill catalog and a strict interpreter.

Survival, Inventory, And Respawn¶

Mineflayer exposes health, food, death, respawn, inventory, container, equip, consume, crafting, and window APIs. mineflayer-auto-eat and mineflayer-armor-manager can reduce boilerplate for survival profiles.

Production implications:

• V1 can include survival basics only after live proof: eat from inventory, equip armor, respawn, and rejoin.
• Chest/inventory workflows require stricter privacy and anti-theft controls. A bot should only interact with configured chests or validation containers, not arbitrary player storage.
• PvP should stay off. PvE defense may be a later prepared-world profile, but it requires combat-specific validation and product approval.

Version And Protocol Support¶

Mineflayer is the correct base for Java Edition. Bedrock should remain out of scope for this epic. The current Swarm Hosts strategy is Minecraft Java-first, and the control-plane probes, templates, docs, and runner all target Java.

Production implications:

• Use Node 22 in the runtime image because npm metadata for mineflayer and minecraft-protocol now requires Node >=22.
• Pin exact versions for mineflayer, minecraft-protocol, pathfinder, and each plugin. Do not float to latest in production images.
• Add a compatibility matrix for each server version Swarm Hosts exposes: connect, spawn, chat, pathfind, dig, place, inventory, eat, respawn, cleanup.
• Keep minecraft-protocol status/login probes as a diagnostic path when full behavior fails on a new protocol.

Recommended Roadmap¶

MVP: Internal Validation Runtime¶

Goal: prove the runtime contract and live deployment evidence before customer UI returns.

Scope:

• Package packages/minecraft-bot-runtime into the Node 22 swarmhost/minecraft-bot-runtime support image with scripts/release/publish_minecraft_bot_runtime_image.sh.
• Offline-mode validation deployments only.
• Profiles: observe and a bounded smoke/join profile. Movement/pathfinder, dig, place, build, and mine behavior require follow-up prepared-zone proof.
• Hard limits: default 1 bot, maximum 5 for validation, 60-120 second default sessions, spawn staggering >=500 ms, no external arbitrary targets.
• Control-plane records structured events and artifacts, but customer UI remains hidden until proof is complete.

Exit proof:

• Real disposable Swarm Hosts Minecraft Java deployment.
• Java status passes through the player-facing endpoint.
• Bot joins are visible in Java status, structured online-player discovery, and server logs.
• Chat/action/build or dig evidence is captured.
• CPU, memory, network, and cleanup are recorded.
• No generic-agent Minecraft logic is added.

V1: Safe Customer Beta¶

Goal: make bots useful for non-technical server owners without giving them raw automation controls.

Profiles:

• Observer: joined presence, reconnect, status events.
• Greeter: scripted greeting and bounded response snippets.
• Patrol: pathfinder route or stay-near-player goal in a configured radius.
• Builder sandbox: place a small curated blueprint in a marked area.
• Miner sandbox: collect allowed blocks in a marked validation/resource area.
• Survival helper: eat, equip available armor, respawn, and stop on repeated danger.

Controls:

• Template cards, desired bot count, duration, stop all, reconnect policy, safety scope, and logs/events.
• No raw plugin names, arbitrary target hosts, slash commands, LLM code execution, or PvP.
• Default max 1-3 customer bots, elevated max behind tier/feature flag after measured capacity.

V2: Intelligent And Extensible¶

Goal: higher-level behavior after operational safety exists.

The accepted detailed boundary for this stage is the V2 curated intelligence plan. It keeps deterministic, reviewed skills as the execution layer and separates optional LLM chat from closed-schema plan proposal.

Candidates:

• Curated skill library inspired by Voyager, but implemented as reviewed TypeScript skills instead of arbitrary LLM-generated code.
• Optional LLM chat/planning with strict tool permissions, transcript audit, content safety, cooldowns, and no command execution.
• Inventory/chest helper for explicitly selected chests.
• PvE arena or mob-defense profile in prepared worlds.
• Viewer/debug artifacts for support and validation.
• Larger capacity benchmarks per host class.

Runtime Architecture¶

Recommended architecture:

1. Control plane owns desired bot-session state: deployment id, profile, count, duration, reconnect policy, safety scope, runtime version, and audit metadata.
2. Control plane converts that state into a game-specific support operation or support-container launch instruction for the Minecraft image/runtime layer.
3. The generic swarmhost agent executes only generic primitives: pull image, start/stop support container, pass scoped environment, collect logs/results, enforce timeouts, and cleanup.
4. The bot runtime container runs Node 22 with pinned Mineflayer dependencies. It connects only to the deployment endpoint supplied by the control plane and exactly authorized in runtime config.
5. The runtime reports status, per-bot events, errors, cleanup proof, and artifact paths back through a scoped deployment/runtime token. Logs redact credentials, tokens, host internals, and chat bodies where appropriate.
6. A watchdog reconciles desired count, reconnects allowed slots, records terminal blockers, and stops sessions when the deployment stops, updates, or is deleted.

Why this preserves the agent boundary:

• Minecraft-specific protocol, RCON, Mineflayer, pathfinder, inventory, and behavior code stays in images/games/minecraft or a dedicated Minecraft-support image.
• The agent remains a generic executor for containers, lifecycle, logs, resource limits, and result transport.
• The existing architecture test can keep forbidding Minecraft markers inside agents/swarmhost-agent/.

Safety And Abuse Constraints¶

Baseline constraints:

• Targets: only the current Swarm Hosts deployment endpoint selected by the control plane. No arbitrary public server field in customer UI/API.
• Auth: offline/test-mode first. Online-mode Microsoft account pools require separate product/legal/security review and secret-handling design.
• Identity: generated visible bot usernames with a Swarm Hosts prefix or customer-approved prefix; do not hide that bots are bots.
• Counts: default 1, customer beta max 3 until measured, absolute per-deployment max behind feature flag. Validation-only max can remain 10.
• Spawn staggering: at least 500 ms by default; larger for live customer servers.
• Chat: no slash commands, no multiline input, max length, cooldown, per-session quota, moderation for generated text, and transcript audit.
• Building/mining: disabled by default; require explicit prepared zone, material allowlist, block quota, backup expectation, and cleanup/reporting.
• Combat: no PvP. PvE only in a future prepared-world profile.
• Inventory/chests: only explicitly configured bot-owned or validation chests.
• Resources: support container CPU/memory limits, max duration, kill switch, deployment stop hooks, and artifact retention.
• Audit: record launcher, deployment, endpoint, profile, counts, duration, runtime version, result, and blocker without storing secrets.
• Anti-abuse: do not bypass anti-bot systems, do not run against third-party public servers, and do not provide stealth or evasion options.

Product And UI Outcome¶

Issue #415 removed the temporary Managed Minecraft bots and One-time Minecraft bot run panels, summaries, and public API queue paths. Those retired routes remain unavailable. Issue #426 later shipped the replacement after runtime proof:

• Use a dedicated Bots surface for the bounded customer workflow.
• Present profile templates, not plugin names: Observer, Greeter, Patrol, Builder sandbox, Miner sandbox, Survival helper.
• Show current endpoint, desired count, online count, runtime state, last reconcile, active blockers, and stop/cleanup controls.
• Use clear safety copy in context: where bots can build/mine, what they can say, and what they cannot do.
• Keep advanced settings behind a compact disclosure and avoid exposing Node versions, raw Mineflayer versions, plugin names, arbitrary targets, auth cache paths, or internal tokens.
• Include mobile-friendly event timelines and a single prominent "Stop all bots" control.

The shipped page follows these recommendations. Builder and Miner stay visible but unavailable. The V2 curated-intelligence plan is separate research and does not expand the current customer behavior.

Validation Plan¶

Local validation for implementation issues:

• Node package tests for config parsing, target authorization, username generation, report redaction, aggregate result reporting, cancellation, and failure handling.
• Unit tests for behavior state machines: path goal timeouts, stuck recovery, chat rate limits, safe block selection, zone enforcement, inventory policy, and terminal cleanup states.
• Python/control-plane tests for desired session state, unavailable API behavior while hidden, permission checks, result sanitization, diagnostics redaction, and no arbitrary target acceptance.
• Architecture boundary test remains green: tests/test_agent_architecture_boundaries.py.
• MkDocs build for docs updates.
• Playwright UI proof across desktop, laptop, tablet, and mobile before any customer UI returns.

Live proof requirements:

• Disposable Minecraft Java deployment through Swarm Hosts, preferably offline-mode for validation.
• Java status protocol proof from the player-facing endpoint before, during, and after bot sessions.
• Joined bots visible in server logs and structured online-player discovery.
• Behavior-specific evidence:
• pathfinding: target reached or explicit stuck reason;
• chat: bounded non-command message appears once;
• building: exact placed blocks in prepared zone;
• mining/collection: exact mined/collected items and quota stop;
• survival: eat/equip/respawn proof where applicable.
• Stability observation: no deployment restart, no runaway process, container cleanup verified, CPU/memory/network recorded.
• Cleanup: stop sessions, verify player count returns to baseline, delete disposable deployment, and record artifact paths.

Runtime/game-changing child issues should require independent validation before merge or after candidate deployment, following the factory validation gate.

Live Validation Harness¶

Issue #421 added the repeatable proof path at scripts/validation/minecraft_bot_session_live_validation.py. The harness requires the normal validation user token plus the hidden bot-session internal secret from .env; both are redacted from command output and the generated artifact.

Default operator command:

set -a
source .env
set +a
.venv/bin/python scripts/validation/minecraft_bot_session_live_validation.py

By default it creates a disposable offline-mode Minecraft deployment with relay networking, waits for the Java status endpoint, records a baseline player snapshot through the structured online-player refresh/read endpoints, creates and reconciles a hidden bot session, polls status while the Mineflayer runtime is active, verifies the sanitized runtime result and cleanup events, confirms the player count returns to baseline with a final structured player-discovery refresh, observes stability, and deletes the deployment. The JSON result is written under /tmp/swarmhosts-minecraft-bot-session-validation/issue421-bot-session-<RUN_ID>/. RCON remains enabled through the Minecraft catalog default for the control plane's constrained player-discovery refresh; the harness does not call the raw /actions/game_command endpoint or submit raw command payloads.

For a retained or pre-existing validation deployment, pass --reuse-deployment with --deployment-id; reused deployments are retained unless --delete-reused-deployment is supplied. A created deployment can be retained only with --keep-deployment --retention-reason ... --retention-expires-at ... so issue comments can record owner, reason, and expiration.

Epic And Child Issues¶

Issue #416 converted the accepted research into GitLab work items on 2026-07-09. The parent tracker is #417. Cleanup of the misleading temporary UI/API was completed in #415 before these children were created.

The table below preserves the initial routing snapshot from July 9; it is not a current status board. The linked GitLab issues are the durable source of truth. The runtime and four customer templates subsequently shipped through #426 with live end-to-end proof, #427 owns current docs/support guidance, and #428 is a V2 design plan rather than shipped behavior.

Issue	Scope	Initial status	Lane	Parallelism	Validation
#418	Lock runtime contract and safety policy.	status:ready	lane:runtime	parallel:serialized	Design review, agent boundary guard, focused local checks.
#419	Package the Mineflayer Node 22 support runtime.	status:in-progress	lane:runtime	parallel:serialized	Node tests plus live disposable join, stop, cleanup, and resource proof.
#420	Add hidden bot-session API/state and reconciler.	status:blocked	lane:runtime	parallel:serialized	Backend tests and runtime validation if sessions are queued.
#421	Build the live validation harness.	status:blocked	lane:runtime	parallel:serialized	scripts/validation/minecraft_bot_session_live_validation.py creates or reuses a disposable deployment, drives the hidden bot-session API, records status/join/behavior/cleanup evidence, and deletes the deployment by default.
#422	Ship observe and pathfinder patrol MVP.	status:blocked	lane:runtime	parallel:serialized	Live target-reached and stuck/timeout evidence.
#423	Add scripted chat safety controls.	status:blocked	lane:runtime	parallel:serialized	Policy tests and live bounded non-command chat proof.
#424	Add builder and miner sandbox profiles.	status:blocked	lane:runtime	parallel:serialized	Zone/quota tests plus live block placement and mining proof.
#425	Add survival helper profile.	status:blocked	lane:runtime	parallel:serialized	Survival-mode eat/equip/respawn proof where feasible.
#426	Restore safe customer Bots UI.	status:blocked	lane:ui-product	parallel:safe after runtime proof	Playwright/browser evidence across desktop, laptop, tablet, and mobile.
#427	Publish docs and support runbooks.	status:blocked	lane:docs-content	parallel:safe	MkDocs strict build and stale temporary-bot-copy grep.
#428	Plan V2 curated intelligence and LLM boundaries.	status:blocked	lane:research-grooming	parallel:safe	Source-backed planning only; no runtime/UI change.

Historical dependency order:

1. 418 locked the contract and safety policy.¶

2. That contract unblocked the runtime package and state/reconciler work.

3. 421 established the hidden runtime proof before behavior work expanded.¶

4. 426 remained gated until joined-bot, stop/cleanup, status, event, browser,¶

   and production proof existed.

5. 427 followed the accepted UI/runtime behavior; #428 remained planning only.¶

Decision Summary¶

• Base runtime: Mineflayer, pinned, Node 22.
• Companion protocol library: minecraft-protocol for status/login/fallback probes.
• Navigation: mineflayer-pathfinder with strict stuck recovery and 1.21.x canaries.
• Building/mining: hidden validation profiles only; customer Builder and Miner remain unavailable pending separate world-change and cleanup proof.
• Survival: shipped through explicit Mineflayer APIs with bot-owned inventory only; no container access or combat.
• Visualization: prismarine-viewer and web inventory are validation/support tools, not MVP customer dependencies.
• LLM intelligence: curated skill library first; no arbitrary generated code in customer servers.
• Architecture: game-specific runtime/support container, generic swarmhost agent unchanged.
• Product posture: #415 removed the half-built prototype; #426 restored only the bounded, production-proven customer templates and kept public JSON bot control unavailable.