Improve MCC testing workflow resilience

.skills/mcc-integration-testing/SKILL.md

@@ -56,7 +56,7 @@ If the environment cannot run a real server, say so and report the result as une
 - Use a real local server.
 - Launch MCC against an explicit `localhost:<server-port>` target for repeatable local tests.
 - Keep version matrices sequential in shared local environments. The tmux server harness is shared state by default.
-- Prefer temporary MCC configs for scripted runs so one test does not contaminate the next.
+- Prefer generated temporary MCC configs for scripted runs so one test does not contaminate the next.
 - Default to offline auth in generated temp configs. Do not trust the repo-root `MinecraftClient.ini` account defaults.
 - If the user explicitly asks for Microsoft online login, honor that request and generate the temp config for Microsoft auth instead of offline mode.
 - For Microsoft auth, prefer an interactive TTY launch with `BasicIO-NoColor` so the device code is easy to read and relay to the user.
@@ -65,8 +65,10 @@ If the environment cannot run a real server, say so and report the result as une
 - Legacy and modern command syntax differ. Do not assume one server-command profile fits every version.
 - Use actual MCC output and actual server logs for assertions. Do not invent success strings.
 - Treat server `Done` as startup progress, not RCON readiness. Retry the first RCON command before assuming the setup is broken.
+- Run preflight before scripted test loops. On macOS, Java may be installed but not exported on PATH in the shell the harness uses.
 - If a change touches shared routing or a version range, test at least one adjacent version that shares that path, or explicitly mark adjacent versions as unexecuted and inferred.
 - For palette or version-content changes, probe at least one neighboring or existing item, entity, or block. Do not only check the headline addition.
+- Separate product failures from harness failures. Missing logs, stale tmux state, stale `stdin.pipe`, or pre-join `Connection refused` errors are usually environment problems until proven otherwise.
 
 ## Choose the test mode
 
@@ -117,11 +119,19 @@ Run them against a real server with a temp config and summarize counts from the
 
 Before running any scenario:
 
+0. run preflight and clear stale shared state when the environment is reused
 1. configure the target server for offline testing
 2. ensure `eula=true`
 3. ensure RCON is enabled
 4. build MCC unless the task explicitly reuses a fresh build
 
+Preflight and reset helpers:
+
+```bash
+.skills/mcc-integration-testing/scripts/preflight_test_env.sh 1.21.11-Vanilla
+.skills/mcc-integration-testing/scripts/reset_shared_test_state.sh 1.21.11-Vanilla
+```
+
 Offline configuration helper:
 
 ```bash
@@ -141,8 +151,12 @@ Optionally override the login name with the fourth argument to the config helper
 
 - `.skills/mcc-integration-testing/scripts/ensure_offline_server.sh`
   - configures persistent offline mode and RCON
+- `.skills/mcc-integration-testing/scripts/preflight_test_env.sh`
+  - verifies Java, tmux, dotnet, python3, server directories, and resolves common Java PATH issues
+- `.skills/mcc-integration-testing/scripts/reset_shared_test_state.sh`
+  - clears stale tmux sessions and stale `stdin.pipe` files before a rerun
 - `.skills/mcc-integration-testing/scripts/prepare_offline_mcc_config.sh`
-  - copies `MinecraftClient.ini`, prepares offline login by default, and can switch to Microsoft auth when explicitly requested
+  - generates a clean temporary MCC config, prepares offline login by default, disables noisy bots, and can switch to Microsoft auth when explicitly requested
 - `.skills/mcc-integration-testing/scripts/get_server_port.sh`
   - resolves the actual local server port from `server.properties` or the latest server log
 - `.skills/mcc-integration-testing/scripts/run_full_spectrum_test.sh`
@@ -159,6 +173,7 @@ In every report, separate:
 - `Executed`: exact scripts, commands, versions, auth mode, and whether the run was sequential or single-version
 - `Observed`: exact MCC output, exact server-log evidence, and the saved log directory
 - `Inferred`: conclusions not directly shown by that run's runtime evidence
+- `Harness issues`: setup or runner problems such as missing Java on PATH, stale tmux sessions, stale `stdin.pipe`, missing log artifacts, or failed config generation
 
 Never upgrade inferred claims to observed facts. Absence of errors is supporting evidence only; pair it with a positive assertion for the feature under test.
 
@@ -196,6 +211,7 @@ Always summarize:
 ## Troubleshooting
 
 - If the first RCON command fails, retry it before assuming the setup is broken.
+- If Java is installed but the harness still says it is missing, run `preflight_test_env.sh`. This resolves common Homebrew Java paths on macOS.
 - If MCC reaches Microsoft device-code login during an offline test, stop and inspect the generated temp config before retrying.
 - If the user explicitly requests Microsoft online login, set `MCC_TEST_ACCOUNT_TYPE=microsoft` before launching the harness.
 - If the user explicitly requests Microsoft online login, use `BasicIO-NoColor` in a real TTY, relay the device code from the TUI, and avoid pressing empty Enter at any auth prompt.
@@ -203,7 +219,8 @@ Always summarize:
 - If `dotnet run` cannot see an existing Microsoft session, check whether `SessionCache.db` and `ProfileKeyCache.ini` need to be synced from `MinecraftClient/bin/Release/net10.0/` to the repo root.
 - If Microsoft auth keeps prompting even with a valid session cache, verify `Account.Login` matches the cached username exactly.
 - If MCC reports `Connection refused`, verify the launched target matches the server's actual `server-port`.
+- If MCC reports `Connection refused` immediately after a server start, also check for stale shared state: old tmux sessions, a stale `stdin.pipe`, or a server that never actually reached `Done (`.
 - If multiple versions are being tested, do not start them in parallel unless the harness isolates tmux sessions and input files.
 - If a test assertion fails, inspect the real MCC output before changing the code or weakening the assertion.
 - If an older server behaves oddly on Linux, check `use-native-transport=false` in `server.properties`.
-- If a test should be repeatable, avoid mutating the repo-root `MinecraftClient.ini`.
+- If a matrix row fails before producing `mcc.log` or a command transcript, treat it as a harness failure, fix the environment, and rerun that row before drawing product conclusions.

.skills/mcc-integration-testing/scripts/common.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+
+sed_in_place() {
+    if [[ "$(uname)" == "Darwin" ]]; then
+        sed -i '' "$@"
+    else
+        sed -i "$@"
+    fi
+}
+
+ensure_java_in_path() {
+    if command -v java >/dev/null 2>&1 && java -version >/dev/null 2>&1; then
+        return 0
+    fi
+
+    local candidate
+    for candidate in \
+        "${JAVA_BIN:-}" \
+        "/opt/homebrew/opt/openjdk/bin/java" \
+        "/usr/local/opt/openjdk/bin/java" \
+        "/usr/lib/jvm/default-java/bin/java"
+    do
+        [[ -z "$candidate" ]] && continue
+        if [[ -x "$candidate" ]]; then
+            export PATH="$(dirname "$candidate"):$PATH"
+            export JAVA_BIN="$candidate"
+            if java -version >/dev/null 2>&1; then
+                return 0
+            fi
+        fi
+    done
+
+    echo "java was not found on PATH. Install Java or set JAVA_BIN." >&2
+    return 1
+}
+
+server_session_name() {
+    printf 'mc-%s\n' "${1//./_}"
+}
+
+server_running() {
+    local version="$1"
+    mc-list | grep -Fq "$(server_session_name "$version")"
+}
+
+wait_for_server_ready() {
+    local version="$1"
+    local timeout="${2:-60}"
+    local elapsed=0
+
+    while (( elapsed < timeout )); do
+        if mc-log "$version" 250 2>/dev/null | grep -Fq "Done ("; then
+            return 0
+        fi
+        sleep 1
+        ((elapsed += 1))
+    done
+
+    echo "Timed out waiting for $version to become ready" >&2
+    return 1
+}
+
+wait_for_server_stop() {
+    local version="$1"
+    local timeout="${2:-60}"
+    local elapsed=0
+
+    while (( elapsed < timeout )); do
+        if ! server_running "$version"; then
+            return 0
+        fi
+        sleep 1
+        ((elapsed += 1))
+    done
+
+    mc-kill "$version" >/dev/null 2>&1 || true
+
+    if ! server_running "$version"; then
+        return 0
+    fi
+
+    echo "Timed out waiting for $version to stop" >&2
+    return 1
+}
+
+disable_noisy_bots_in_ini() {
+    local ini_file="$1"
+    local section
+
+    for section in \
+        ScriptScheduler \
+        DiscordRpc \
+        AntiAFK \
+        AutoDig \
+        AutoAttack \
+        PlayerListLogger \
+        ReplayCapture
+    do
+        sed_in_place "/^\\[ChatBot\\.${section}\\]/,/^\\[/ { s/^Enabled = true/Enabled = false/; }" "$ini_file"
+    done
+}
+
+remove_stale_stdin_pipe() {
+    local version="$1"
+    local pipe_path="$MCC_SERVERS/$version/stdin.pipe"
+
+    if [[ -e "$pipe_path" && ! -p "$pipe_path" ]]; then
+        rm -f "$pipe_path"
+    fi
+}

.skills/mcc-integration-testing/scripts/ensure_offline_server.sh

@@ -5,14 +5,8 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
 # shellcheck source=tools/mcc-env.sh
 source "$REPO_ROOT/tools/mcc-env.sh"
-
-sed_in_place() {
-    if [[ "$(uname)" == "Darwin" ]]; then
-        sed -i '' "$@"
-    else
-        sed -i "$@"
-    fi
-}
+# shellcheck source=.skills/mcc-integration-testing/scripts/common.sh
+source "$SCRIPT_DIR/common.sh"
 
 VERSION="${1:-1.21.11-Vanilla}"
 SERVER_DIR="${MCC_SERVERS:?}/$VERSION"
@@ -33,43 +27,6 @@ server_running() {
     mc-list | grep -Fq "$SESSION_NAME"
 }
 
-wait_for_server_ready() {
-    local timeout="${1:-60}"
-    local elapsed=0
-    while (( elapsed < timeout )); do
-        if mc-log "$VERSION" 200 2>/dev/null | grep -Fq "Done ("; then
-            return 0
-        fi
-        sleep 1
-        ((elapsed += 1))
-    done
-    echo "Timed out waiting for $VERSION to become ready" >&2
-    return 1
-}
-
-wait_for_server_stop() {
-    local timeout="${1:-60}"
-    local elapsed=0
-    while (( elapsed < timeout )); do
-        if ! server_running; then
-            return 0
-        fi
-        sleep 1
-        ((elapsed += 1))
-    done
-
-    # Legacy servers can leave the tmux session around after stdin stop.
-    # Fall back to force-killing the session so the harness can continue.
-    mc-kill "$VERSION" >/dev/null 2>&1 || true
-
-    if ! server_running; then
-        return 0
-    fi
-
-    echo "Timed out waiting for $VERSION to stop" >&2
-    return 1
-}
-
 upsert_property() {
     local key="$1"
     local value="$2"
@@ -83,14 +40,14 @@ upsert_property() {
 
 if [[ ! -f "$PROPS_FILE" ]]; then
     mc-start "$VERSION"
-    wait_for_server_ready
+    wait_for_server_ready "$VERSION"
     mc-stop "$VERSION"
-    wait_for_server_stop
+    wait_for_server_stop "$VERSION"
 fi
 
 if server_running; then
     mc-stop "$VERSION"
-    wait_for_server_stop
+    wait_for_server_stop "$VERSION"
 fi
 
 upsert_property "online-mode" "false"

.skills/mcc-integration-testing/scripts/preflight_test_env.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+# shellcheck source=tools/mcc-env.sh
+source "$REPO_ROOT/tools/mcc-env.sh"
+# shellcheck source=.skills/mcc-integration-testing/scripts/common.sh
+source "$SCRIPT_DIR/common.sh"
+
+usage() {
+    cat <<'EOF'
+Usage: preflight_test_env.sh [server-dir...]
+
+Checks the local MCC test environment and resolves common Java path issues.
+EOF
+}
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+    usage
+    exit 0
+fi
+
+ensure_java_in_path
+command -v tmux >/dev/null 2>&1 || { echo "tmux was not found on PATH." >&2; exit 1; }
+command -v dotnet >/dev/null 2>&1 || { echo "dotnet was not found on PATH." >&2; exit 1; }
+command -v python3 >/dev/null 2>&1 || { echo "python3 was not found on PATH." >&2; exit 1; }
+
+if [[ ! -d "$MCC_SERVERS" ]]; then
+    echo "Server root not found: $MCC_SERVERS" >&2
+    exit 1
+fi
+
+for server_dir in "$@"; do
+    [[ -z "$server_dir" ]] && continue
+    if [[ ! -d "$MCC_SERVERS/$server_dir" ]]; then
+        echo "Server directory not found: $MCC_SERVERS/$server_dir" >&2
+        exit 1
+    fi
+
+    remove_stale_stdin_pipe "$server_dir"
+done
+
+printf 'MCC_REPO=%s\n' "$MCC_REPO"
+printf 'MCC_SERVERS=%s\n' "$MCC_SERVERS"
+printf 'JAVA=%s\n' "$(command -v java)"
+printf 'TMUX=%s\n' "$(command -v tmux)"
+printf 'DOTNET=%s\n' "$(command -v dotnet)"

.skills/mcc-integration-testing/scripts/prepare_offline_mcc_config.sh

@@ -1,23 +1,40 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-sed_in_place() {
-    if [[ "$(uname)" == "Darwin" ]]; then
-        sed -i '' "$@"
-    else
-        sed -i "$@"
-    fi
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+# shellcheck source=.skills/mcc-integration-testing/scripts/common.sh
+source "$SCRIPT_DIR/common.sh"
+
+usage() {
+    cat <<'EOF' >&2
+Usage:
+  prepare_offline_mcc_config.sh <output-ini> <mc-version> [login]
+  prepare_offline_mcc_config.sh <template-ini> <output-ini> <mc-version> [login]
+EOF
 }
 
-if [[ $# -lt 3 || $# -gt 4 ]]; then
-    echo "Usage: $0 <template-ini> <output-ini> <mc-version> [login]" >&2
+if [[ $# -lt 2 || $# -gt 4 ]]; then
+    usage
     exit 1
 fi
 
-TEMPLATE_INI="$1"
-OUTPUT_INI="$2"
-MC_VERSION="$3"
-LOGIN_NAME="${4:-CursorBot}"
+TEMPLATE_INI=""
+OUTPUT_INI=""
+MC_VERSION=""
+LOGIN_NAME=""
+
+if [[ $# -ge 3 && -f "$1" ]]; then
+    TEMPLATE_INI="$1"
+    OUTPUT_INI="$2"
+    MC_VERSION="$3"
+    LOGIN_NAME="${4:-CursorBot}"
+else
+    OUTPUT_INI="$1"
+    MC_VERSION="$2"
+    LOGIN_NAME="${3:-CursorBot}"
+fi
+
 ACCOUNT_TYPE="${MCC_TEST_ACCOUNT_TYPE:-mojang}"
 PASSWORD_VALUE="${MCC_TEST_PASSWORD-}"
 
@@ -34,6 +51,32 @@ if [[ -z "${MCC_TEST_PASSWORD+x}" ]]; then
     fi
 fi
 
+generate_template_ini() {
+    local template_root
+    template_root="$(mktemp -d "${TMPDIR:-/tmp}/mcc-config-template.XXXXXX")"
+
+    if [[ ! -f "$REPO_ROOT/MinecraftClient/bin/Release/net10.0/MinecraftClient.dll" ]]; then
+        dotnet build "$REPO_ROOT/MinecraftClient.sln" -c Release -v quiet --nologo >/dev/null
+    fi
+
+    (
+        cd "$template_root"
+        dotnet run --project "$REPO_ROOT/MinecraftClient" -c Release --no-build -- --help >/dev/null 2>&1
+    )
+
+    if [[ ! -f "$template_root/MinecraftClient.ini" ]]; then
+        echo "Failed to generate a temporary MCC config template." >&2
+        exit 1
+    fi
+
+    TEMPLATE_INI="$template_root/MinecraftClient.ini"
+}
+
+if [[ -z "$TEMPLATE_INI" ]]; then
+    generate_template_ini
+fi
+
+mkdir -p "$(dirname "$OUTPUT_INI")"
 cp "$TEMPLATE_INI" "$OUTPUT_INI"
 
 sed_in_place \
@@ -46,6 +89,8 @@ sed_in_place \
     -e 's#^AutoRespawn = false#AutoRespawn = true#' \
     "$OUTPUT_INI"
 
+disable_noisy_bots_in_ini "$OUTPUT_INI"
+
 grep -Fq "AccountType = \"$ACCOUNT_TYPE\"" "$OUTPUT_INI" || {
     echo "Failed to enforce account type $ACCOUNT_TYPE in $OUTPUT_INI" >&2
     exit 1

.skills/mcc-integration-testing/scripts/reset_shared_test_state.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+# shellcheck source=tools/mcc-env.sh
+source "$REPO_ROOT/tools/mcc-env.sh"
+# shellcheck source=.skills/mcc-integration-testing/scripts/common.sh
+source "$SCRIPT_DIR/common.sh"
+
+usage() {
+    cat <<'EOF'
+Usage: reset_shared_test_state.sh [--all | <server-dir>...]
+
+Kills shared tmux test sessions and removes stale stdin pipes.
+EOF
+}
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+    usage
+    exit 0
+fi
+
+kill_named_session() {
+    local session_name="$1"
+    tmux kill-session -t "$session_name" 2>/dev/null || true
+}
+
+kill_named_session "mcc-debug"
+
+if [[ $# -eq 0 || "${1:-}" == "--all" ]]; then
+    while IFS= read -r session_name; do
+        [[ -z "$session_name" ]] && continue
+        kill_named_session "$session_name"
+    done < <(tmux list-sessions 2>/dev/null | awk -F: '/^mc-/{print $1}' || true)
+
+    while IFS= read -r pipe_path; do
+        [[ -z "$pipe_path" ]] && continue
+        if [[ ! -p "$pipe_path" ]]; then
+            rm -f "$pipe_path"
+        fi
+    done < <(find "$MCC_SERVERS" -maxdepth 2 -name 'stdin.pipe' 2>/dev/null || true)
+else
+    for version in "$@"; do
+        kill_named_session "$(server_session_name "$version")"
+        remove_stale_stdin_pipe "$version"
+    done
+fi
+
+rm -f "$MCC_REPO/mcc_input.txt"

.skills/mcc-integration-testing/scripts/run_achievements_matrix.sh

@@ -64,6 +64,16 @@ run_version() {
     # shellcheck disable=SC1090
     source "$summary_env"
 
+    if [[ -n "${MCC_LOG:-}" && ! -f "$MCC_LOG" ]]; then
+        NOTE="Harness failure: MCC log was not produced."
+        VERDICT="❌ Fail"
+    fi
+
+    if [[ -n "${COMMAND_LOG:-}" && ! -f "$COMMAND_LOG" ]]; then
+        NOTE="Harness failure: command transcript was not produced."
+        VERDICT="❌ Fail"
+    fi
+
     write_row "$VERSION" "$SERVER_DIR" "$PORT" "$FAMILY" "$INITIAL_STATUS" "$GRANT_STATUS" "$REVOKE_STATUS" \
         "$API_STATUS" "$VERDICT" "$NOTE" "$RUN_DIR" "$MCC_LOG" "$COPIED_SERVER_LOG" "$COMMAND_LOG"
 }
@@ -94,6 +104,7 @@ if ! command -v tmux >/dev/null 2>&1; then
 fi
 
 if [[ "$DOTNET_OK" == "yes" ]]; then
+    bash "$SCRIPT_DIR/preflight_test_env.sh" >/dev/null 2>&1 || true
     if ! dotnet build "$REPO_ROOT/MinecraftClient.sln" -c Release > "$BUILD_LOG" 2>&1; then
         BUILD_OK="no"
     fi

.skills/mcc-integration-testing/scripts/run_achievements_test.sh

@@ -5,14 +5,8 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
 # shellcheck source=tools/mcc-env.sh
 source "$REPO_ROOT/tools/mcc-env.sh"
-
-sed_in_place() {
-    if [[ "$(uname)" == "Darwin" ]]; then
-        sed -i '' "$@"
-    else
-        sed -i "$@"
-    fi
-}
+# shellcheck source=.skills/mcc-integration-testing/scripts/common.sh
+source "$SCRIPT_DIR/common.sh"
 
 usage() {
     cat <<'EOF'
@@ -131,6 +125,7 @@ cleanup() {
     fi
 
     mc-stop "$SERVER_DIR" >/dev/null 2>&1 || true
+    wait_for_server_stop "$SERVER_DIR" 20 >/dev/null 2>&1 || true
     ln -sfn "$RUN_DIR" "$LATEST_LINK"
     write_summary
 }
@@ -165,43 +160,6 @@ wait_for_file_pattern() {
     return 1
 }
 
-wait_for_server_ready() {
-    local timeout="${1:-60}"
-    local elapsed=0
-
-    while (( elapsed < timeout )); do
-        if mc-log "$SERVER_DIR" 250 2>/dev/null | grep -Fq "Done ("; then
-            return 0
-        fi
-        sleep 1
-        ((elapsed += 1))
-    done
-
-    echo "Timed out waiting for server readiness" >&2
-    return 1
-}
-
-disable_noisy_bots() {
-    sed_in_place '/^\[ChatBot.ScriptScheduler\]/,/^\[/ { s/^Enabled = true/Enabled = false/; }' "$REPO_ROOT/MinecraftClient.ini"
-    sed_in_place '/^\[ChatBot.DiscordRpc\]/,/^\[/ { s/^Enabled = true/Enabled = false/; }' "$REPO_ROOT/MinecraftClient.ini"
-    sed_in_place '/^\[ChatBot.AntiAFK\]/,/^\[/ { s/^Enabled = true/Enabled = false/; }' "$REPO_ROOT/MinecraftClient.ini"
-    sed_in_place '/^\[ChatBot.AutoDig\]/,/^\[/ { s/^Enabled = true/Enabled = false/; }' "$REPO_ROOT/MinecraftClient.ini"
-    sed_in_place '/^\[ChatBot.AutoAttack\]/,/^\[/ { s/^Enabled = true/Enabled = false/; }' "$REPO_ROOT/MinecraftClient.ini"
-    sed_in_place '/^\[ChatBot.PlayerListLogger\]/,/^\[/ { s/^Enabled = true/Enabled = false/; }' "$REPO_ROOT/MinecraftClient.ini"
-    sed_in_place '/^\[ChatBot.ReplayCapture\]/,/^\[/ { s/^Enabled = true/Enabled = false/; }' "$REPO_ROOT/MinecraftClient.ini"
-}
-
-ensure_root_config() {
-    if [[ -f "$REPO_ROOT/MinecraftClient.ini" ]]; then
-        return
-    fi
-
-    (
-        cd "$REPO_ROOT"
-        dotnet run --project MinecraftClient -c Release --no-build -- --help >/dev/null 2>&1
-    )
-}
-
 write_probe_script() {
     cat > "$PROBE_SCRIPT" <<EOF
 //MCCScript 1.0
@@ -314,29 +272,6 @@ assert_pattern() {
     grep -Fq "$pattern" "$file" || fail "$description"
 }
 
-if ! command -v java >/dev/null 2>&1 || ! java -version >/dev/null 2>&1; then
-    fail "java was not found on PATH."
-fi
-
-if ! command -v tmux >/dev/null 2>&1; then
-    fail "tmux was not found on PATH."
-fi
-
-if [[ ! -d "$MCC_SERVERS/$SERVER_DIR" ]]; then
-    fail "Server directory not found: $MCC_SERVERS/$SERVER_DIR"
-fi
-
-PORT="$(bash "$SCRIPT_DIR/get_server_port.sh" "$SERVER_DIR")"
-
-ensure_root_config
-"$SCRIPT_DIR/ensure_offline_server.sh" "$SERVER_DIR"
-disable_noisy_bots
-write_probe_script
-
-if [[ "$PROFILE" == "legacy" && -f "$MCC_SERVERS/$SERVER_DIR/server.properties" ]]; then
-    sed_in_place 's/^use-native-transport=.*/use-native-transport=false/' "$MCC_SERVERS/$SERVER_DIR/server.properties"
-fi
-
 if $DO_BUILD; then
     log_step "BUILD> dotnet build MinecraftClient.sln -c Release"
     mcc-build > "$BUILD_LOG" 2>&1 || fail "dotnet build failed."
@@ -344,17 +279,35 @@ else
     : > "$BUILD_LOG"
 fi
 
+bash "$SCRIPT_DIR/preflight_test_env.sh" "$SERVER_DIR" >/dev/null || fail "Test environment preflight failed."
+bash "$SCRIPT_DIR/reset_shared_test_state.sh" "$SERVER_DIR" >/dev/null || fail "Failed to reset shared test state."
+
+if [[ ! -d "$MCC_SERVERS/$SERVER_DIR" ]]; then
+    fail "Server directory not found: $MCC_SERVERS/$SERVER_DIR"
+fi
+
+bash "$SCRIPT_DIR/prepare_offline_mcc_config.sh" "$CFG" "$MC_VERSION" CursorBot >/dev/null || fail "Failed to prepare temporary MCC config."
+PORT="$(bash "$SCRIPT_DIR/get_server_port.sh" "$SERVER_DIR")"
+
+"$SCRIPT_DIR/ensure_offline_server.sh" "$SERVER_DIR"
+write_probe_script
+
+if [[ "$PROFILE" == "legacy" && -f "$MCC_SERVERS/$SERVER_DIR/server.properties" ]]; then
+    sed_in_place 's/^use-native-transport=.*/use-native-transport=false/' "$MCC_SERVERS/$SERVER_DIR/server.properties"
+fi
+
 : > "$INPUT_FILE"
 rm -f "$MCC_LOG"
 
 log_step "Starting server $SERVER_DIR on port $PORT"
 mc-start "$SERVER_DIR" >/dev/null
-wait_for_server_ready || fail "Server did not become ready."
+wait_for_server_ready "$SERVER_DIR" || fail "Server did not become ready."
 
 log_step "Starting MCC for $MC_VERSION"
 (
     cd "$REPO_ROOT"
     MCC_FILE_INPUT=1 dotnet run --project MinecraftClient -c Release --no-build -- \
+        "$CFG" \
         CursorBot \
         - \
         "localhost:$PORT" \

.skills/mcc-integration-testing/scripts/run_full_spectrum_test.sh

@@ -5,6 +5,8 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
 # shellcheck source=tools/mcc-env.sh
 source "$REPO_ROOT/tools/mcc-env.sh"
+# shellcheck source=.skills/mcc-integration-testing/scripts/common.sh
+source "$SCRIPT_DIR/common.sh"
 
 VERSION="${1:-1.21.11-Vanilla}"
 MC_VERSION="${VERSION%-Vanilla}"
@@ -34,46 +36,12 @@ cleanup() {
     fi
 
     mc-stop "$VERSION" >/dev/null 2>&1 || true
+    wait_for_server_stop "$VERSION" 20 >/dev/null 2>&1 || true
 }
 trap cleanup EXIT
 
 prepare_config() {
-    bash "$SCRIPT_DIR/prepare_offline_mcc_config.sh" "$REPO_ROOT/MinecraftClient.ini" "$CFG" "$MC_VERSION" >/dev/null
-}
-
-wait_for_file_pattern() {
-    local file="$1"
-    local pattern="$2"
-    local description="$3"
-    local timeout="${4:-60}"
-    local elapsed=0
-
-    while (( elapsed < timeout )); do
-        if [[ -f "$file" ]] && grep -Fq "$pattern" "$file"; then
-            return 0
-        fi
-        sleep 1
-        ((elapsed += 1))
-    done
-
-    echo "Timed out waiting for: $description" >&2
-    return 1
-}
-
-wait_for_server_ready() {
-    local timeout="${1:-60}"
-    local elapsed=0
-
-    while (( elapsed < timeout )); do
-        if mc-log "$VERSION" 250 2>/dev/null | grep -Fq "Done ("; then
-            return 0
-        fi
-        sleep 1
-        ((elapsed += 1))
-    done
-
-    echo "Timed out waiting for server readiness" >&2
-    return 1
+    bash "$SCRIPT_DIR/prepare_offline_mcc_config.sh" "$CFG" "$MC_VERSION" CursorBot >/dev/null
 }
 
 wait_for_server_log_pattern() {
@@ -101,6 +69,25 @@ capture_server_logs() {
     fi
 }
 
+wait_for_file_pattern() {
+    local file="$1"
+    local pattern="$2"
+    local description="$3"
+    local timeout="${4:-60}"
+    local elapsed=0
+
+    while (( elapsed < timeout )); do
+        if [[ -f "$file" ]] && grep -Fq "$pattern" "$file"; then
+            return 0
+        fi
+        sleep 1
+        ((elapsed += 1))
+    done
+
+    echo "Timed out waiting for: $description" >&2
+    return 1
+}
+
 fail() {
     capture_server_logs
     echo "FAIL: $1" >&2
@@ -146,18 +133,19 @@ run_mcc_command() {
     sleep 2
 }
 
+bash "$SCRIPT_DIR/preflight_test_env.sh" "$VERSION" >/dev/null
+bash "$SCRIPT_DIR/reset_shared_test_state.sh" "$VERSION" >/dev/null
 "$SCRIPT_DIR/ensure_offline_server.sh" "$VERSION"
+echo "Building MCC..."
+mcc-build > "$BUILD_LOG" 2>&1 || fail "mcc-build failed"
 prepare_config
 SERVER_PORT="$(bash "$SCRIPT_DIR/get_server_port.sh" "$VERSION")"
 
 : > "$INPUT_FILE"
 
-echo "Building MCC..."
-mcc-build > "$BUILD_LOG" 2>&1 || fail "mcc-build failed"
-
 echo "Starting server..."
 mc-start "$VERSION" >/dev/null
-wait_for_server_ready || fail "Server did not become ready"
+wait_for_server_ready "$VERSION" || fail "Server did not become ready"
 
 echo "Starting MCC..."
 (

.skills/mcc-integration-testing/scripts/summarize_achievements_matrix.sh

@@ -54,4 +54,4 @@ echo "## Inferred"
 echo
 echo "- Only rows with real MCC and server-log artifacts count as executed proof."
 echo "- Rows blocked by missing Java, tmux, or server directories are environment-limited, not product pass results."
-echo "- Legacy rows remain the highest-risk bucket because static inspection suggests pre-1.12 \`Statistics\` packets may not currently reach the achievements handler."
+echo "- Rows with missing MCC or command-log artifacts should be treated as harness failures until rerun confirms a product issue."