Minecraft Helper Bot Support Runbook

Use this runbook to diagnose the shipped Minecraft Bots page, collect safe evidence, stop failed sessions, and verify cleanup. For normal customer use, start with the Minecraft Helper Bots guide.

The supported customer contract is intentionally narrow: Observer, Greeter, Patrol, and Survival helper on the current verified endpoint of a private/test, offline-mode Minecraft Java deployment. Builder, Miner, public bot-control API calls, arbitrary targets, free-form chat, combat, customer code, and LLM-driven behavior are not supported.

First response

  1. Confirm the deployment is Minecraft Java, running, and still reachable by the Minecraft Java status check.
  2. Confirm Bot auth shows Private/test mode. Do not tell a customer to disable authentication on an internet-facing server.
  3. Confirm the reporter has deployment manage access and no deployment action is pending.
  4. Record the profile, desired/online counts, lifecycle status, last reconcile time, visible blocker, latest five event types, and artifact identifiers.
  5. If behavior or player presence is unexpected, choose Stop all bots before investigating further.

Do not use the retired managed-bot or synthetic-test routes as a workaround. They intentionally return 410 Gone and cannot queue actions. The current customer feature is an authenticated browser workflow; there is no supported public JSON bot-control API.

Triage by failure class

Policy or preflight refusal

Treat these as expected fail-closed behavior:

  • deployment is not running;
  • Minecraft Java status is not reachable;
  • Mojang authentication is on;
  • the user has only view access;
  • another deployment action is pending;
  • profile, count, duration, or reconnect mode is outside its server-owned template; or
  • Builder or Miner was requested.

Correct the deployment state or permissions, then retry once with Observer. Never bypass the customer template adapter, substitute an internal endpoint, or edit a desired-state payload for a customer.

Waiting, starting, or reconnecting too long

  1. Refresh the Bots page and compare the deployment status with Last reconcile.
  2. For Waiting to start, verify the action queue is clear, then use Start now on that session.
  3. For Starting, look for a lifecycle event followed by a join or error event. Check the deployment action/log tail for support-image pull, launch, protocol, or runtime exit errors.
  4. For Reconnecting, confirm the profile is Survival helper and the event history shows a bounded replacement attempt. Other customer profiles must not reconnect.
  5. If progress does not resume, request Stop, wait for a terminal status, and clean up. Do not create a second session to test around a stuck first one.

Desired count does not match online count

  1. Confirm the Java status check is fresh and reachable.
  2. Check for one Join event per expected helper and an Error, Stop, or Cleanup event for any missing helper.
  3. For Patrol, review movement outcomes for stuck recovery or a goal timeout.
  4. For Survival helper, review action/reconnect events without requesting chest or player-inventory access.
  5. Stop and clean up the session if the count remains wrong. Verify the normal player baseline before retrying.

Failed or timed-out session

  1. Preserve the visible blocker, status, last reconcile time, recent events, and artifact IDs before cleanup.
  2. Classify the last useful event:
  3. Join without later profile evidence suggests behavior/runtime failure;
  4. Movement stuck or timeout is a bounded Patrol failure, not permission to enable digging or bridging;
  5. Action danger/limit events are expected Survival helper stops;
  6. Error before Join usually points to endpoint, protocol, auth, image, or runtime startup; and
  7. a missing Cleanup event requires explicit cleanup verification.
  8. Stop the session if the control is still available, then clean it up.
  9. Retry only with Observer after the root condition is understood.

Cleanup or baseline failure

  1. Choose Stop all bots and wait for every session to become Stopped, Failed, or Timed out.
  2. Choose Clean up on every terminal session.
  3. Confirm active, desired, and online bot counts are zero.
  4. Refresh the structured Minecraft player state and confirm it matches the pre-session baseline.
  5. Confirm Java status remains reachable and the deployment/container did not restart unexpectedly.
  6. If a bot remains online or cleanup is not recorded, do not start another session. Escalate with the sanitized evidence package.

For a disposable validation deployment, delete it after evidence capture and verify the deployment lookup returns 404. A retained test deployment must have an owner, reason, and expiration recorded in the issue. Customer worlds and deployments must never be deleted as support cleanup.

Evidence and redaction rules

Safe support evidence includes:

  • deployment ID in a private support thread;
  • the session ID suffix shown in the UI;
  • profile template, desired count, duration, and reconnect choice;
  • lifecycle status, last reconcile time, visible blocker, and event types;
  • sanitized artifact ID, kind, checksum, and cleanup result;
  • Minecraft protocol state/version and counts; and
  • a cropped Bots-page screenshot after checking visible account, host, player, chat, and network details.

Never paste or upload:

  • user/API/host tokens, bot-session internal secrets, cookies, authorization headers, private keys, or .env contents;
  • RCON passwords, Microsoft credentials, auth caches, raw desired-state files, or unredacted request/response dumps;
  • private/internal hostnames, LAN addresses, database paths, kubeconfigs, or registry credentials; or
  • unrelated player names, chat, world coordinates, or customer log history.

Prefer endpoint hashes and the UI's session suffix over raw endpoints and full runtime identifiers. Review sanitized artifacts again before attaching them; automatic redaction is a guardrail, not permission to publish customer data.

Repeatable live validation

The known-good production proof is recorded on GitLab issue #426. It proved the four customer templates, protocol-visible joins, bounded Greeter chat, Patrol movement, Survival inventory-only decisions, policy refusal, desktop/mobile stop controls, baseline restoration, five-minute stability, and deletion of every disposable deployment.

Authorized operators can use the hidden-session harness for runtime diagnosis:

.venv/bin/python scripts/validation/minecraft_bot_session_live_validation.py \
  --env-file .env \
  --issue <ISSUE> \
  --profile observe

The harness loads credentials without printing them, creates a disposable relay-backed offline-mode Minecraft deployment by default, records a baseline, checks protocol-visible join and behavior evidence, verifies stop/cleanup, observes stability for 300 seconds, and deletes the deployment. It writes a sanitized live-result.json under /tmp/swarmhosts-minecraft-bot-session-validation/issue<ISSUE>-bot-session-<RUN_ID>/.

The harness exercises an internal validation contract; it does not by itself prove the customer browser form. A release acceptance run must also start and stop the supported templates through the deployed Bots page.

Before accepting an artifact, verify:

  • every required live_validation step is pass or an explicitly justified skipped step;
  • the terminal session reports success and verified cleanup;
  • player count returns to the captured baseline;
  • stability covers 300 seconds unless the issue explicitly requires more;
  • cleanup.retained is false, or retention has owner/reason/expiration; and
  • a credential/secret scan of the artifact is clean.

Do not pass --keep-deployment unless the issue records both --retention-reason and --retention-expires-at. A reused deployment is kept by default; use --delete-reused-deployment only for a task-owned disposable deployment, never a customer deployment.

Escalation package

Record these fields in the private support or GitLab thread:

Deployment ID:
Session ID suffix:
Profile / desired count / duration / reconnect:
Deployment status and pending action:
Minecraft Java status and player baseline:
Session lifecycle / blocker / last reconcile:
Recent event types and sanitized artifact IDs:
Stop requested (yes/no, timestamp):
Cleanup recorded (yes/no):
Counts returned to baseline (yes/no):
Disposable deployment deleted or retained with owner/reason/expiration:

If runtime validation is repeated, attach only the reviewed sanitized artifact and record its checksum. Do not attach .env, raw console capture, or request headers.