diff --git a/tools/mcc-env.sh b/tools/mcc-env.sh
index 904a8a00..490bf10b 100644
--- a/tools/mcc-env.sh
+++ b/tools/mcc-env.sh
@@ -12,9 +12,105 @@ else
 fi
 
 TOOLS_DIR="$(cd "$(dirname "$_mcc_env_source")" && pwd)"
+MCC_REPO_ROOT="$(cd "$TOOLS_DIR/.." && pwd)"
 unset _mcc_env_source
-export MCC_REPO="$(cd "$TOOLS_DIR/.." && pwd)"
-export MCC_SERVERS="${MCC_SERVERS:-$MCC_REPO/MinecraftOfficial/downloads}"
+export MCC_REPO="$MCC_REPO_ROOT"
+export MCC_SERVERS="${MCC_SERVERS:-$MCC_REPO_ROOT/MinecraftOfficial/downloads}"
+
+_mcc_repo_root() {
+  printf '%s\n' "$MCC_REPO_ROOT"
+}
+
+_mcc_servers_root() {
+  printf '%s\n' "${MCC_SERVERS:-$MCC_REPO_ROOT/MinecraftOfficial/downloads}"
+}
+
+_mcc_current_worktree_name() {
+  git -C "$MCC_REPO_ROOT" rev-parse --show-toplevel 2>/dev/null | xargs basename
+}
+
+_mcc_resolve_session() {
+  local explicit="${1:-}"
+  if [[ -n "$explicit" ]]; then
+    printf '%s\n' "$explicit"
+    return 0
+  fi
+
+  local worktree
+  worktree="$(_mcc_current_worktree_name)"
+  if [[ -n "$worktree" ]]; then
+    printf '%s\n' "$worktree"
+    return 0
+  fi
+
+  basename "$MCC_REPO_ROOT"
+}
+
+_mcc_sha1_short() {
+  if command -v sha1sum >/dev/null 2>&1; then
+    printf '%s' "$1" | sha1sum | awk '{print substr($1, 1, 4)}'
+  else
+    printf '%s' "$1" | shasum -a 1 | awk '{print substr($1, 1, 4)}'
+  fi
+}
+
+_mcc_resolve_username() {
+  local session="$1"
+  local normalized
+  normalized="$(printf '%s' "$session" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9_]/_/g')"
+  local candidate="mcc_${normalized}"
+  if (( ${#candidate} <= 16 )); then
+    printf '%s\n' "$candidate"
+    return 0
+  fi
+
+  local hash
+  hash="$(_mcc_sha1_short "$normalized")"
+  printf '%s_%s\n' "${candidate:0:11}" "$hash"
+}
+
+_mcc_session_root() {
+  printf '%s/mcc-debug/%s\n' "${TMPDIR:-/tmp}" "$1"
+}
+
+_mcc_session_log_file() {
+  printf '%s/mcc-debug.log\n' "$(_mcc_session_root "$1")"
+}
+
+_mcc_session_input_file() {
+  printf '%s/mcc_input.txt\n' "$(_mcc_session_root "$1")"
+}
+
+_mcc_session_pid_file() {
+  printf '%s/mcc.pid\n' "$(_mcc_session_root "$1")"
+}
+
+_mcc_session_meta_file() {
+  printf '%s/session.meta\n' "$(_mcc_session_root "$1")"
+}
+
+_mcc_tmux_session_name() {
+  printf 'mcc-%s\n' "$1"
+}
+
+_mcc_build_root() {
+  local worktree
+  worktree="$(_mcc_current_worktree_name)"
+  if [[ -z "$worktree" ]]; then
+    worktree="$(basename "$MCC_REPO_ROOT")"
+  fi
+
+  if [[ "${MCC_BUILD_MODE:-local}" == "tmpfs" ]]; then
+    if [[ -d /dev/shm && -w /dev/shm ]]; then
+      printf '/dev/shm/mcc-build/%s\n' "$worktree"
+    else
+      printf '%s/mcc-build/%s\n' "${TMPDIR:-/tmp}" "$worktree"
+    fi
+    return 0
+  fi
+
+  printf '%s\n' "$MCC_REPO_ROOT"
+}
 
 # Helper: convert version to tmux session name (dots -> underscores)
 _mc-session() { echo "mc-${1//\./_}"; }
diff --git a/tools/test-mcc-env.sh b/tools/test-mcc-env.sh
new file mode 100755
index 00000000..73278e1f
--- /dev/null
+++ b/tools/test-mcc-env.sh
@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+source "$REPO_ROOT/tools/mcc-env.sh"
+
+assert_eq() {
+    local expected="$1"
+    local actual="$2"
+    local label="$3"
+    if [[ "$expected" != "$actual" ]]; then
+        echo "FAIL: $label" >&2
+        echo "  expected: $expected" >&2
+        echo "  actual:   $actual" >&2
+        exit 1
+    fi
+}
+
+assert_regex() {
+    local regex="$1"
+    local actual="$2"
+    local label="$3"
+    if [[ ! "$actual" =~ $regex ]]; then
+        echo "FAIL: $label" >&2
+        echo "  regex:  $regex" >&2
+        echo "  actual: $actual" >&2
+        exit 1
+    fi
+}
+
+session="$(_mcc_resolve_session "demo-branch")"
+assert_eq "demo-branch" "$session" "explicit session"
+
+short_name="$(_mcc_resolve_username "feature-ai")"
+assert_eq "mcc_feature_ai" "$short_name" "short derived username"
+
+long_name="$(_mcc_resolve_username "very-long-worktree-name")"
+assert_regex '^mcc_[a-z0-9_]{7}_[0-9a-f]{4}$' "$long_name" "long derived username shape"
+assert_eq "16" "${#long_name}" "long derived username length"
+
+assert_eq "${TMPDIR:-/tmp}/mcc-debug/demo-branch" "$(_mcc_session_root "demo-branch")" "session root"
+assert_eq "mcc-demo-branch" "$(_mcc_tmux_session_name "demo-branch")" "tmux session name"
+
+MCC_BUILD_MODE=tmpfs
+build_root="$(_mcc_build_root)"
+assert_regex '^(/dev/shm|/tmp)/mcc-build/.+$' "$build_root" "tmpfs build root"
+
+echo "PASS"