create-claude-cabinet 0.48.0 → 0.49.0

package/templates/mux/config/worktree-session-health.sh

@@ -1,20 +1,164 @@
 #!/bin/bash
-# Worktree health check — single source of truth.
+# Worktree health check — single source of truth for the worktree lifecycle:
+# provision (env files at spawn), verify (health checks + preflight), reap
+# (lane containers at removal).
 #
-# Called three ways:
+# Called five ways:
 #   1. CC SessionStart hook (no args) — uses $PWD, exits silently outside worktrees
 #   2. mux worktree health (args: proj_path wt_path) — checks a specific worktree
 #   3. mux worktree refresh (args: proj_path wt_path --refresh) — forces an
 #      infra re-sync even when nothing is stale. Refresh delegates here so
 #      the authored-record carve-out (sync_claude_infra) lives in exactly
 #      one place — never a wholesale rm -rf of .claude/.
+#   4. mux worktree preflight (args: proj_path --preflight) — pre-spawn source
+#      check: every declared provision file exists in MAIN and every declared
+#      `check:` command passes. Run BEFORE parallel lane spawns; exit 1 on any
+#      failure so orchestrators can gate the spawn.
+#   5. worktree removal (args: proj_path wt_path --reap) — stops and removes
+#      lane-scoped docker containers (exact compose-project-label match on the
+#      worktree dir name; containers only, never volumes). Both removal paths
+#      (bin/mux and the pane-exited worktree-cleanup.sh hook) delegate here.
+#      Always exits 0 — a failed reap never blocks worktree removal, but it
+#      reports loudly so a leak is never silent.
+#
+# Per-project declaration: .mux-worktree-provision at the project root.
+#   - one gitignored file path per line (copied main → worktree at creation,
+#     freshness-checked on later runs; a locally-modified worktree copy is
+#     NEVER overwritten)
+#   - `check: <command>` lines are preflight checks (run from the project
+#     root, time-boxed). Probes should verify identity/freshness, not bare
+#     liveness — a leftover stack answers a bare port probe.
+#   - `#` comments and blank lines ignored. No file → every mode no-ops.
 #
 # Self-heals all fixable issues. Positive confirmation for every check.
+# Reports name file paths, hashes, and mtimes only — never env-file CONTENTS
+# (health output lands in session logs; provisioned files may hold secrets).
 # Exit codes: 0 = healthy (possibly after auto-fix), 1 = unfixable issue
 
-proj_path="${1:-}"
-wt_path="${2:-}"
-force_refresh="${3:-}"
+mode="health"
+force_refresh=""
+positional=()
+for arg in "$@"; do
+  case "$arg" in
+    --refresh) force_refresh="--refresh" ;;
+    --preflight) mode="preflight" ;;
+    --reap) mode="reap" ;;
+    *) positional+=("$arg") ;;
+  esac
+done
+proj_path="${positional[0]:-}"
+wt_path="${positional[1]:-}"
+
+PROVISION_FILE=".mux-worktree-provision"
+
+# Portable time-box (macOS ships no `timeout`): run "$@" but kill it after
+# $1 seconds. Returns the command's exit code, or non-zero if killed.
+run_with_timeout() {
+  local secs="$1"; shift
+  "$@" &
+  local pid=$!
+  ( sleep "$secs"; kill -9 "$pid" 2>/dev/null ) &
+  local watchdog=$!
+  local rc=0
+  wait "$pid" 2>/dev/null || rc=$?
+  kill "$watchdog" 2>/dev/null
+  wait "$watchdog" 2>/dev/null
+  return "$rc"
+}
+
+# Emit the declared provision entries, one per line, prefixed "file<TAB>" or
+# "check<TAB>". Single parser — provisioning, preflight, and tests all read
+# the declaration through this one shape.
+parse_provision_file() {
+  local list="$1"
+  [[ -f "$list" ]] || return 0
+  local line
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    line="${line%%$'\r'}"
+    [[ -z "$line" || "$line" == \#* ]] && continue
+    if [[ "$line" == check:* ]]; then
+      printf 'check\t%s\n' "$(echo "${line#check:}" | sed 's/^ *//')"
+    else
+      printf 'file\t%s\n' "$line"
+    fi
+  done < "$list"
+}
+
+# --reap: remove this lane's docker containers before the worktree dir (the
+# compose-project-name source) disappears. Exact label match only — a
+# substring/name match could kill a sibling lane's live stack. Containers
+# only; volumes are never touched (a lane's database state outlives the reap
+# decision). Fail-open for the removal, loud on anything left behind.
+reap_lane_containers() {
+  local wp="$1" name ids left
+  name=$(basename "$wp" | tr '[:upper:]' '[:lower:]')
+  if ! [[ "$name" =~ ^[a-z0-9][a-z0-9_-]*$ ]]; then
+    echo "⚠ reap: '$name' is not a valid compose project slug — skipped"
+    return 0
+  fi
+  command -v docker >/dev/null 2>&1 || return 0
+  if ! run_with_timeout 5 docker info >/dev/null 2>&1; then
+    echo "⚠ reap: docker daemon unreachable — lane containers for '${name}' not verified (may leak)"
+    return 0
+  fi
+  ids=$(run_with_timeout 10 docker ps -aq --filter "label=com.docker.compose.project=${name}" 2>/dev/null) || ids=""
+  [[ -n "$ids" ]] || return 0
+  # shellcheck disable=SC2086 — ids is a docker-generated id list
+  run_with_timeout 30 docker rm -f $ids >/dev/null 2>&1 || true
+  left=$(run_with_timeout 10 docker ps -aq --filter "label=com.docker.compose.project=${name}" 2>/dev/null) || left=""
+  if [[ -n "$left" ]]; then
+    echo "⚠ reap INCOMPLETE for compose project '${name}' — still running: ${left}"
+  else
+    echo "✓ reaped lane container(s) for compose project '${name}' (containers only, volumes kept)"
+  fi
+  return 0
+}
+
+# --preflight: verify the SOURCE side before N parallel lanes derive from it.
+# Declared files must exist in main; declared checks must pass. This is not
+# the per-worktree freshness check (that runs in health mode) — it answers
+# "is main's environment sound enough to spawn lanes against?".
+run_preflight() {
+  local sp="$1" fail=0 kind value
+  local list="$sp/$PROVISION_FILE"
+  if [[ ! -f "$list" ]]; then
+    echo "✓ preflight: no $PROVISION_FILE declared in $sp — nothing to verify"
+    exit 0
+  fi
+  while IFS=$'\t' read -r kind value; do
+    case "$kind" in
+      file)
+        if [[ -f "$sp/$value" ]]; then
+          echo "✓ preflight: present in main: $value"
+        else
+          echo "✗ preflight: declared provision file missing in main: $value"
+          fail=1
+        fi
+        ;;
+      check)
+        if ( cd "$sp" && run_with_timeout 30 bash -c "$value" >/dev/null 2>&1 ); then
+          echo "✓ preflight: check passed: $value"
+        else
+          echo "✗ preflight: check FAILED (or timed out): $value"
+          fail=1
+        fi
+        ;;
+    esac
+  done < <(parse_provision_file "$list")
+  exit "$fail"
+}
+
+case "$mode" in
+  preflight)
+    [[ -n "$proj_path" ]] || { echo "usage: worktree-session-health.sh <proj_path> --preflight" >&2; exit 2; }
+    run_preflight "$proj_path"
+    ;;
+  reap)
+    [[ -n "$wt_path" ]] || { echo "usage: worktree-session-health.sh <proj_path> <wt_path> --reap" >&2; exit 2; }
+    reap_lane_containers "$wt_path"
+    exit 0
+    ;;
+esac
 
 if [[ -z "$wt_path" ]]; then
   # SessionStart mode — detect from environment
@@ -39,19 +183,179 @@ fails=()
 # created beside them stay visible and commit. The managed lines are rebuilt
 # on every run, so the negation set follows what's actually committed (and
 # the old static plans/methodology pair migrates automatically).
-exclude_claude_dir() {
-  local wp="$1" gd
-  gd=$(git -C "$wp" rev-parse --git-dir 2>/dev/null) || return 0
+#
+# LIVENESS (act:c008862c): git reads info/exclude from the COMMON git dir
+# only — a linked worktree's worktrees/<name>/info/exclude is a file git
+# never consults, so these rules were silently dead in every mux worktree
+# (hidden only where the project's own .gitignore overlapped). The fix:
+# enable extensions.worktreeConfig and point this worktree's
+# core.excludesFile at the managed file. That displaces the user's own
+# excludesFile (any scope) for this worktree, so its patterns are copied
+# into the managed file each rebuild — BEFORE the managed rules, so the
+# authored-record negations always win over a user hide-pattern.
+#
+# The managed rules also hide, per worktree only (never main's status):
+#   - machine-written generated state inside otherwise-authored .claude/
+#     dirs (advisories-state.json, checklist-stats.json, verification/) plus
+#     the /verify progress journal (e2e/.verify-progress.jsonl) —
+#     re-excluded AFTER the negations, later lines win. Names must stay in
+#     step with the shell GENERATED_STATE_RE in worktree-dirty-check.sh and
+#     the lib classification in watchtower-lib.mjs (Lane A; guarded by the
+#     drift test in worktree-status-clean.test.mjs).
+#   - the mux identity symlinks when untracked — ROOT-ANCHORED (/.mcp.json:
+#     an unanchored pattern would hide a nested authored copy at any depth)
+#     and emitted ONLY while the path is actually a symlink into main, so a
+#     real user-created file at the same path is never hidden (a lazily
+#     created real pib.db is real work, not churn). The TRACKED case
+#     (typechange) is exclude-immune; hide_identity_symlink_typechange owns
+#     it. node_modules stays unanchored and unconditional — nested
+#     node_modules is never authored record.
+# (formerly exclude_claude_dir — renamed when it outgrew .claude/)
+rebuild_worktree_excludes() {
+  local wp="$1" sp="$2" gd
+  gd=$(git -C "$wp" rev-parse --path-format=absolute --git-dir 2>/dev/null) || return 0
   [[ -n "$gd" ]] || return 0
   mkdir -p "$gd/info"
   local ex="$gd/info/exclude"
   touch "$ex"
-  { grep -vE '^(\.claude/\*?|!\.claude/.*)$' "$ex" 2>/dev/null || true; } > "$ex.tmp"
-  echo '.claude/*' >> "$ex.tmp"
-  git -C "$wp" ls-files '.claude/' 2>/dev/null \
-    | awk -F/ 'NF>2 {print "!.claude/" $2 "/"} NF==2 {print "!" $0}' \
-    | sort -u >> "$ex.tmp"
+  # Strip marker-fenced managed blocks + legacy unmarked managed lines.
+  # The fenced blocks are always the file's TAIL, so an orphaned open
+  # marker (hand-edit) can only eat managed content, never user lines.
+  awk '
+    /^# >>> mux-managed/ {skip=1; next}
+    /^# <<< mux-managed/ {skip=0; next}
+    skip {next}
+    /^(\.claude\/\*?|!\.claude\/.*)$/ {next}
+    /^\/?(\.mcp\.json|\.claudeignore|pib\.db)$/ {next}
+    /^node_modules$/ {next}
+    /^\.claude\/(cabinet\/(advisories-state|checklist-stats)\.json|verification\/)$/ {next}
+    /^e2e\/\.verify-progress\.jsonl$/ {next}
+    {print}
+  ' "$ex" 2>/dev/null > "$ex.tmp" || true
+  # User excludesFile copy FIRST (displaced by our core.excludesFile wire;
+  # scopes local > global > system, then the XDG default — never the
+  # worktree scope, which is our own value and would self-copy).
+  local user_ignore="" scope
+  for scope in --local --global --system; do
+    user_ignore=$(git -C "$wp" config "$scope" --get --type=path core.excludesFile 2>/dev/null) && [[ -n "$user_ignore" ]] && break
+    user_ignore=""
+  done
+  [[ -n "$user_ignore" ]] || user_ignore="${XDG_CONFIG_HOME:-$HOME/.config}/git/ignore"
+  if [[ -f "$user_ignore" ]]; then
+    { echo '# >>> mux-managed user ignore copy (rebuilt each health run; do not hand-edit)'
+      cat "$user_ignore"
+      echo '# <<< mux-managed user ignore copy'; } >> "$ex.tmp"
+  fi
+  {
+    echo '# >>> mux-managed worktree rules (rebuilt each health run; hand edits to these patterns are rebuilt away)'
+    echo '.claude/*'
+    git -C "$wp" ls-files '.claude/' 2>/dev/null \
+      | awk -F/ 'NF>2 {print "!.claude/" $2 "/"} NF==2 {print "!" $0}' \
+      | sort -u
+    echo '.claude/cabinet/advisories-state.json'
+    echo '.claude/cabinet/checklist-stats.json'
+    echo '.claude/verification/'
+    echo 'e2e/.verify-progress.jsonl'
+    local f
+    for f in .mcp.json .claudeignore pib.db; do
+      if [[ -L "$wp/$f" && "$(readlink "$wp/$f")" == "$sp/$f" ]]; then
+        echo "/$f"
+      fi
+    done
+    echo 'node_modules'
+    echo '# <<< mux-managed worktree rules'
+  } >> "$ex.tmp"
   mv "$ex.tmp" "$ex"
+  enable_worktree_excludes "$wp" "$gd"
+}
+
+# Make the managed exclude file the one git actually reads for THIS worktree.
+# Linked worktrees only (main's .git/info/exclude is already live). Every
+# skip/degradation path reports — a worktree silently staying on the old
+# dead-exclude behavior is the exact failure this fix exists to close. The
+# report is emitted once per run (EXCLUDES_REPORTED) because the rebuild
+# runs at more than one check site.
+enable_worktree_excludes() {
+  local wp="$1" gd="$2" common cur
+  common=$(git -C "$wp" rev-parse --path-format=absolute --git-common-dir 2>/dev/null) || return 0
+  [[ -n "$common" && "$gd" != "$common" ]] || return 0
+  [[ -z "${EXCLUDES_REPORTED:-}" ]] || {
+    # Later same-run rebuild — keep config in step, skip the duplicate note.
+    cur=$(git -C "$wp" config --worktree --get core.excludesFile 2>/dev/null) || cur=""
+    [[ "$cur" == "$gd/info/exclude" ]] || git -C "$wp" config --worktree core.excludesFile "$gd/info/exclude" 2>/dev/null || true
+    return 0
+  }
+  EXCLUDES_REPORTED=1
+  # worktreeConfig relocation hazards: core.worktree / core.bare in the
+  # SHARED config must be relocated before enabling the extension — a
+  # half-migration bricks every worktree (verified live: bare=true +
+  # worktreeConfig => 'fatal: this operation must be run in a work tree').
+  # mux never creates these layouts; skip with a visible note, never brick.
+  if git -C "$wp" config --get core.worktree >/dev/null 2>&1; then
+    passes+=("⚠ per-worktree excludes NOT enabled (core.worktree set in shared config) — status may show mux churn; dirty-check stays immune")
+    return 0
+  fi
+  if git -C "$wp" config --get --type=bool core.bare 2>/dev/null | grep -qx true; then
+    passes+=("⚠ per-worktree excludes NOT enabled (core.bare=true in shared config) — status may show mux churn; dirty-check stays immune")
+    return 0
+  fi
+  cur=$(git -C "$wp" config --worktree --get core.excludesFile 2>/dev/null) || cur=""
+  if [[ "$cur" != "$gd/info/exclude" ]]; then
+    git -C "$wp" config extensions.worktreeConfig true 2>/dev/null || true
+    git -C "$wp" config --worktree core.excludesFile "$gd/info/exclude" 2>/dev/null || true
+  fi
+  # Positive confirmation from READ-BACK, never from the write's exit code.
+  if [[ "$(git -C "$wp" config --worktree --get core.excludesFile 2>/dev/null)" == "$gd/info/exclude" ]]; then
+    passes+=("✓ per-worktree exclude rules live (core.excludesFile wired)")
+  else
+    passes+=("⚠ per-worktree excludes NOT live (git too old for worktreeConfig?) — status may show mux churn; dirty-check stays immune")
+  fi
+}
+
+# mux replaces tracked identity files (.mcp.json, .claudeignore) with
+# symlinks to main's copies. gitignore/exclude rules NEVER apply to tracked
+# files, so the typechange (` T`) rendered in every worktree's status for the
+# session's life — and `git add -A` would stage the symlink (the ELOOP
+# class). skip-worktree is the per-worktree index bit for exactly this state:
+# hidden from status, unstageable by add -A, invisible to main and siblings.
+#
+# Discipline (the assume-unchanged lesson from the .claude/ carve-out):
+#   - the bit is granted ONLY while the path is a symlink resolving into
+#     MAIN's checkout — a foreign-target symlink stays visible;
+#   - it is CLEARED whenever the path holds a real file, so a genuine edit
+#     is never frozen invisible past the next health run. Between health
+#     runs (SessionStart / creation / refresh) a mid-session symlink→real
+#     swap IS hidden from porcelain — that window is closed on the deletion
+#     side by worktree-dirty-check.sh, which counts any skip-worktree'd
+#     path that is no longer a symlink as dirty (fail-DIRTY);
+#   - a failed CLEAR while a real file sits behind the bit is a FAILURE,
+#     not a shrug — that is exactly the frozen-edit state;
+#   - success is claimed from the update-index exit, never the attempt.
+#
+# Known symptom to recognize (pre-existing either way, verified): if MAIN
+# changes .mcp.json after the worktree branched, `git merge main` aborts
+# citing "local changes" while status shows clean. Recovery:
+#   git update-index --no-skip-worktree .mcp.json
+#   git checkout -- .mcp.json && git merge main
+# (the next health run re-symlinks and re-hides).
+hide_identity_symlink_typechange() {
+  local wp="$1" sp="$2" f hidden=0
+  for f in .mcp.json .claudeignore; do
+    git -C "$wp" ls-files --error-unmatch "$f" >/dev/null 2>&1 || continue
+    if [[ -L "$wp/$f" && "$(readlink "$wp/$f")" == "$sp/$f" ]]; then
+      if git -C "$wp" update-index --skip-worktree "$f" 2>/dev/null; then
+        hidden=1
+      fi
+    else
+      if ! git -C "$wp" update-index --no-skip-worktree "$f" 2>/dev/null; then
+        if git -C "$wp" ls-files -v -- "$f" 2>/dev/null | grep -q '^S '; then
+          fails+=("⚠ could not clear skip-worktree on $f — a real edit may be hidden from status. Run: git update-index --no-skip-worktree $f")
+        fi
+      fi
+    fi
+  done
+  [[ "$hidden" -eq 1 ]] && passes+=("✓ identity symlink typechange hidden from status (skip-worktree; cleared whenever a real file returns)")
+  return 0
 }
 
 # Clear git's assume-unchanged bit on every tracked .claude/ file — tracked
@@ -103,7 +407,7 @@ if [[ -L "$wt_path/.claude" ]]; then
     unprotect_authored_records "$wt_path"
     git -C "$wt_path" checkout -- .claude/ 2>/dev/null || true
     sync_claude_infra "$proj_path" "$wt_path"
-    exclude_claude_dir "$wt_path"
+    rebuild_worktree_excludes "$wt_path" "$proj_path"
     passes+=("✓ .claude/ auto-fixed: was symlink, now local copy (path isolation restored)")
   else
     fails+=("⚠ .claude/ is a symlink and main repo has no .claude/ to copy from")
@@ -111,19 +415,23 @@ if [[ -L "$wt_path/.claude" ]]; then
 elif [[ -d "$wt_path/.claude" ]]; then
   # Heal existing worktrees: un-freeze authored records + migrate the exclude.
   unprotect_authored_records "$wt_path"
-  exclude_claude_dir "$wt_path"
+  rebuild_worktree_excludes "$wt_path" "$proj_path"
   passes+=("✓ .claude/ is a local copy (path isolation intact)")
 elif [[ -d "$proj_path/.claude" ]]; then
   mkdir -p "$wt_path/.claude"
   unprotect_authored_records "$wt_path"
   git -C "$wt_path" checkout -- .claude/ 2>/dev/null || true
   sync_claude_infra "$proj_path" "$wt_path"
-  exclude_claude_dir "$wt_path"
+  rebuild_worktree_excludes "$wt_path" "$proj_path"
   passes+=("✓ .claude/ auto-fixed: was missing, copied from main repo")
 else
   fails+=("⚠ .claude/ missing and main repo has no .claude/ either")
 fi
 
+# 1b. Tracked identity files replaced by mux symlinks must not render as a
+#     typechange (exclude rules can't touch tracked files — skip-worktree).
+hide_identity_symlink_typechange "$wt_path" "$proj_path"
+
 # 2. node_modules linked for MCP dependencies
 if [[ -d "$proj_path/node_modules" ]]; then
   if [[ -e "$wt_path/node_modules" ]]; then
@@ -157,7 +465,7 @@ if [[ -d "$proj_path/.claude" ]] && [[ -d "$wt_path/.claude" ]] && [[ ! -L "$wt_
       done | wc -l | tr -d ' ')
   if [[ "$stale_count" -gt 0 || "$force_refresh" == "--refresh" ]]; then
     sync_claude_infra "$proj_path" "$wt_path"
-    exclude_claude_dir "$wt_path"
+    rebuild_worktree_excludes "$wt_path" "$proj_path"
     unprotect_authored_records "$wt_path"
     passes+=("✓ .claude/ infra refreshed ($stale_count stale file(s); authored records preserved)")
   else
@@ -165,6 +473,82 @@ if [[ -d "$proj_path/.claude" ]] && [[ -d "$wt_path/.claude" ]] && [[ ! -L "$wt_
   fi
 fi
 
+# 5. Declared env-file provisioning (spawn-time copy + freshness on later
+#    runs). Rules, in order, per declared file:
+#      - source missing in main            → FAIL (loud; the declaration says
+#                                            the project needs it)
+#      - destination not gitignored        → FAIL, refuse to copy (a declared
+#                                            secrets file must never land as a
+#                                            committable untracked file)
+#      - absent in worktree                → copy from main (auto-fix)
+#      - identical to main                 → current
+#      - differs, untouched since provision → refresh from main (auto-fix; the
+#                                            recorded provisioned-at hash
+#                                            proves the lane never edited it)
+#      - differs, locally modified (or no  → LEFT ALONE, reported. Lanes may
+#        provisioning record)                diverge env on purpose (ports);
+#                                            never clobber — the same rule the
+#                                            .claude/ carve-out encodes.
+provision_env_files() {
+  local sp="$1" wp="$2"
+  local list="$sp/$PROVISION_FILE"
+  [[ -f "$list" ]] || return 0
+  local gd hash_store kind rel src dst src_hash dst_hash prov_hash
+  gd=$(git -C "$wp" rev-parse --git-dir 2>/dev/null) || gd=""
+  hash_store=""
+  if [[ -n "$gd" ]]; then
+    mkdir -p "$gd" 2>/dev/null
+    hash_store="$gd/mux-provision-hashes"
+    touch "$hash_store" 2>/dev/null || hash_store=""
+  fi
+  record_hash() { # rel hash — last write wins on re-provision
+    [[ -n "$hash_store" ]] || return 0
+    { grep -v "^$1	" "$hash_store" 2>/dev/null || true; } > "$hash_store.tmp"
+    printf '%s\t%s\n' "$1" "$2" >> "$hash_store.tmp"
+    mv "$hash_store.tmp" "$hash_store"
+  }
+  lookup_hash() { # rel → provisioned-at hash (empty if none)
+    [[ -n "$hash_store" ]] || return 0
+    { grep "^$1	" "$hash_store" 2>/dev/null || true; } | cut -f2 | head -1
+  }
+  while IFS=$'\t' read -r kind rel; do
+    [[ "$kind" == "file" ]] || continue
+    src="$sp/$rel"
+    dst="$wp/$rel"
+    if [[ ! -f "$src" ]]; then
+      fails+=("⚠ provision: source missing in main: $rel (declared in $PROVISION_FILE)")
+      continue
+    fi
+    if ! git -C "$wp" check-ignore -q -- "$rel" 2>/dev/null; then
+      fails+=("⚠ provision: $rel is NOT gitignored — refusing to copy (a declared env file must be ignored; fix .gitignore or the declaration)")
+      continue
+    fi
+    src_hash=$(git hash-object "$src" 2>/dev/null) || src_hash=""
+    if [[ ! -f "$dst" ]]; then
+      mkdir -p "$(dirname "$dst")"
+      cp "$src" "$dst"
+      [[ -n "$src_hash" ]] && record_hash "$rel" "$src_hash"
+      passes+=("✓ provisioned $rel from main")
+      continue
+    fi
+    dst_hash=$(git hash-object "$dst" 2>/dev/null) || dst_hash=""
+    if [[ -n "$src_hash" && "$dst_hash" == "$src_hash" ]]; then
+      [[ -n "$(lookup_hash "$rel")" ]] || record_hash "$rel" "$src_hash"
+      passes+=("✓ provision: $rel current with main")
+      continue
+    fi
+    prov_hash=$(lookup_hash "$rel")
+    if [[ -n "$prov_hash" && "$dst_hash" == "$prov_hash" ]]; then
+      cp "$src" "$dst"
+      [[ -n "$src_hash" ]] && record_hash "$rel" "$src_hash"
+      passes+=("✓ provision: $rel refreshed from main (was stale, locally untouched)")
+    else
+      passes+=("✓ provision: $rel differs from main — left alone (locally modified or no provisioning record; never clobbered)")
+    fi
+  done < <(parse_provision_file "$list")
+}
+provision_env_files "$proj_path" "$wt_path"
+
 # Cache status + update tmux indicator color
 cache_dir="$HOME/.local/share/mux/wt-health"
 mkdir -p "$cache_dir"