aidevops 3.0.12 → 3.1.1

package/VERSION

@@ -1 +1 @@
-3.0.12
+3.1.1

package/aidevops.sh

@@ -3,7 +3,7 @@
 # AI DevOps Framework CLI
 # Usage: aidevops <command> [options]
 #
-# Version: 3.0.12
+# Version: 3.1.1
 
 set -euo pipefail
 
@@ -105,7 +105,9 @@ check_file() {
 # Ensure file ends with a trailing newline (prevents malformed appends)
 ensure_trailing_newline() {
 	local file="$1"
-	[[ -s "$file" && $(tail -c1 "$file" | wc -l) -eq 0 ]] && printf '\n' >>"$file"
+	local last
+	last="$(tail -c 1 "$file"; printf x)"
+	[[ -s "$file" ]] && [[ "$last" != $'\n'x ]] && printf '\n' >>"$file"
 }
 
 # Initialize repos.json if it doesn't exist

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aidevops",
-  "version": "3.0.12",
+  "version": "3.1.1",
   "description": "AI DevOps Framework - AI-assisted development workflows, code quality, and deployment automation",
   "type": "module",
   "bin": {

package/setup-modules/mcp-setup.sh

@@ -10,6 +10,13 @@ trap 'rc=$?; echo "[ERROR] ${BASH_SOURCE[0]}:${LINENO} exit $rc" >&2' ERR
 shopt -s inherit_errexit 2>/dev/null || true
 
 install_mcp_packages() {
+	# Check prerequisites before announcing setup (GH#5240)
+	if ! command -v bun &>/dev/null && ! command -v npm &>/dev/null; then
+		print_skip "MCP packages" "neither bun nor npm found" "Install bun: brew install oven-sh/bun/bun (or npm via Node.js)"
+		setup_track_deferred "MCP packages" "Install bun or npm"
+		return 0
+	fi
+
 	print_info "Installing MCP server packages globally (eliminates npx startup delay)..."
 
 	# Security note: MCP servers run as persistent processes with access to conversation
@@ -27,12 +34,6 @@ install_mcp_packages() {
 		"@steipete/claude-code-mcp"
 	)
 
-	if ! command -v bun &>/dev/null && ! command -v npm &>/dev/null; then
-		print_warning "Neither bun nor npm found - cannot install MCP packages"
-		print_info "Install bun (recommended): npm install -g bun OR brew install oven-sh/bun/bun"
-		return 0
-	fi
-
 	local installer="npm"
 	command -v bun &>/dev/null && installer="bun"
 	print_info "Using $installer to install/update Node.js MCP packages..."
@@ -205,36 +206,33 @@ update_mcp_paths_in_opencode() {
 }
 
 setup_localwp_mcp() {
-	print_info "Setting up LocalWP MCP server..."
-
-	# Check if LocalWP is installed
+	# Check prerequisites before announcing setup (GH#5240)
 	local localwp_found=false
 	if [[ -d "/Applications/Local.app" ]] || [[ -d "$HOME/Applications/Local.app" ]]; then
 		localwp_found=true
 	fi
 
 	if [[ "$localwp_found" != "true" ]]; then
-		print_info "LocalWP not found - skipping MCP server setup"
-		print_info "Install LocalWP from: https://localwp.com/"
+		print_skip "LocalWP MCP" "LocalWP not installed" "Install from https://localwp.com/ then re-run setup"
+		setup_track_skipped "LocalWP MCP" "LocalWP not installed"
 		return 0
 	fi
 
-	print_success "LocalWP found"
-
-	# Check if npm is available
 	if ! command -v npm &>/dev/null; then
-		print_warning "npm not found - cannot install LocalWP MCP server"
-		print_info "Install Node.js and npm first"
+		print_skip "LocalWP MCP" "npm not found" "Install Node.js and npm first"
+		setup_track_deferred "LocalWP MCP" "Install Node.js/npm, then re-run setup"
 		return 0
 	fi
 
-	# Check if mcp-local-wp is already installed
+	# Prerequisites met — proceed with setup
+	print_info "Setting up LocalWP MCP server..."
+
 	if command -v mcp-local-wp &>/dev/null; then
 		print_success "LocalWP MCP server already installed"
+		setup_track_configured "LocalWP MCP"
 		return 0
 	fi
 
-	# Offer to install mcp-local-wp
 	print_info "LocalWP MCP server enables AI assistants to query WordPress databases"
 	read -r -p "Install LocalWP MCP server (@verygoodplugins/mcp-local-wp)? [Y/n]: " install_mcp
 
@@ -242,6 +240,7 @@ setup_localwp_mcp() {
 		if run_with_spinner "Installing LocalWP MCP server" npm_global_install "@verygoodplugins/mcp-local-wp"; then
 			print_info "Start with: ~/.aidevops/agents/scripts/localhost-helper.sh start-mcp"
 			print_info "Or configure in OpenCode MCP settings for auto-start"
+			setup_track_configured "LocalWP MCP"
 		else
 			print_info "Try manually: sudo npm install -g @verygoodplugins/mcp-local-wp"
 		fi
@@ -254,48 +253,47 @@ setup_localwp_mcp() {
 }
 
 setup_augment_context_engine() {
-	print_info "Setting up Augment Context Engine MCP..."
-
-	# Check Node.js version (requires 22+)
+	# Check prerequisites before announcing setup (GH#5240)
 	if ! command -v node &>/dev/null; then
-		print_warning "Node.js not found - Augment Context Engine setup skipped"
-		print_info "Install Node.js 22+ to enable Augment Context Engine"
-		return
+		print_skip "Augment Context Engine" "Node.js not installed" "Install Node.js 22+: brew install node@22 (macOS) or nvm install 22"
+		setup_track_deferred "Augment Context Engine" "Install Node.js 22+"
+		return 0
 	fi
 
 	local node_version
 	node_version=$(node --version 2>/dev/null | cut -d'v' -f2 | cut -d'.' -f1)
 	if [[ -z "$node_version" ]] || ! [[ "$node_version" =~ ^[0-9]+$ ]]; then
-		print_warning "Could not determine Node.js version - Augment Context Engine setup skipped"
-		return
+		print_skip "Augment Context Engine" "could not determine Node.js version"
+		setup_track_skipped "Augment Context Engine" "Node.js version unknown"
+		return 0
 	fi
 	if [[ "$node_version" -lt 22 ]]; then
-		print_warning "Node.js 22+ required for Augment Context Engine, found v$node_version"
-		print_info "Install: brew install node@22 (macOS) or nvm install 22"
-		return
+		print_skip "Augment Context Engine" "requires Node.js 22+, found v$node_version" "Upgrade: brew install node@22 (macOS) or nvm install 22"
+		setup_track_deferred "Augment Context Engine" "Upgrade Node.js to 22+ (currently v$node_version)"
+		return 0
 	fi
 
-	# Check if auggie is installed
 	if ! command -v auggie &>/dev/null; then
-		print_warning "Auggie CLI not found"
-		print_info "Install with: npm install -g @augmentcode/auggie@prerelease"
-		print_info "Then run: auggie login"
-		return
+		print_skip "Augment Context Engine" "Auggie CLI not installed" "Install: npm install -g @augmentcode/auggie@prerelease && auggie login"
+		setup_track_deferred "Augment Context Engine" "Install Auggie CLI: npm install -g @augmentcode/auggie@prerelease"
+		return 0
 	fi
 
-	# Check if logged in
 	if [[ ! -f "$HOME/.augment/session.json" ]]; then
-		print_warning "Auggie not logged in"
-		print_info "Run: auggie login"
-		return
+		print_skip "Augment Context Engine" "Auggie not logged in" "Run: auggie login"
+		setup_track_deferred "Augment Context Engine" "Run: auggie login"
+		return 0
 	fi
 
+	# Prerequisites met — proceed with setup
+	print_info "Setting up Augment Context Engine MCP..."
 	print_success "Auggie CLI found and authenticated"
 
 	# MCP configuration is handled by generate-opencode-agents.sh for OpenCode
 
 	print_info "Augment Context Engine available as MCP in OpenCode"
 	print_info "Verification: 'What is this project? Please use codebase retrieval tool.'"
+	setup_track_configured "Augment Context Engine"
 
 	return 0
 }
@@ -479,34 +477,35 @@ add_opencode_plugin() {
 }
 
 setup_opencode_plugins() {
-	print_info "Setting up OpenCode plugins..."
-
-	# Check if OpenCode is installed
+	# Check prerequisites before announcing setup (GH#5240)
 	if ! command -v opencode &>/dev/null; then
-		print_warning "OpenCode not found - plugin setup skipped"
-		print_info "Install OpenCode first: https://opencode.ai"
+		print_skip "OpenCode plugins" "OpenCode not installed" "Install from https://opencode.ai"
+		setup_track_skipped "OpenCode plugins" "OpenCode not installed"
 		return 0
 	fi
 
-	# Check if config exists
 	local opencode_config
 	if ! opencode_config=$(find_opencode_config); then
-		print_warning "OpenCode config not found - plugin setup skipped"
+		print_skip "OpenCode plugins" "OpenCode config not found" "Run 'opencode' once to create config, then re-run setup"
+		setup_track_deferred "OpenCode plugins" "Run 'opencode' once to create config"
 		return 0
 	fi
 
-	# Check if jq is available
 	if ! command -v jq &>/dev/null; then
-		print_warning "jq not found - cannot update OpenCode config"
+		print_skip "OpenCode plugins" "jq not installed" "Install jq: brew install jq (macOS) or apt install jq"
+		setup_track_deferred "OpenCode plugins" "Install jq"
 		return 0
 	fi
 
+	# Prerequisites met — proceed with setup
+	print_info "Setting up OpenCode plugins..."
+
 	# Setup aidevops compaction plugin (local file plugin)
 	local aidevops_plugin_path="$HOME/.aidevops/agents/plugins/opencode-aidevops/index.mjs"
 	if [[ -f "$aidevops_plugin_path" ]]; then
-		print_info "Setting up aidevops compaction plugin..."
 		add_opencode_plugin "file://$HOME/.aidevops" "file://${aidevops_plugin_path}" "$opencode_config"
 		print_success "aidevops compaction plugin registered (preserves context across compaction)"
+		setup_track_configured "OpenCode plugins"
 	fi
 
 	# Note: opencode-anthropic-auth is built into OpenCode v1.1.36+
@@ -514,7 +513,7 @@ setup_opencode_plugins() {
 	# Removed in v2.90.0 - see PR #230.
 
 	print_info "After setup, authenticate with: opencode auth login"
-	print_info "  • For Claude OAuth: Select 'Anthropic' → 'Claude Pro/Max' (built-in)"
+	print_info "  - For Claude OAuth: Select 'Anthropic' -> 'Claude Pro/Max' (built-in)"
 
 	return 0
 }
@@ -566,32 +565,31 @@ setup_seo_mcps() {
 }
 
 setup_google_analytics_mcp() {
-	print_info "Setting up Google Analytics MCP..."
-
 	local gsc_creds="$HOME/.config/aidevops/gsc-credentials.json"
 
-	# Check if opencode.json exists
+	# Check prerequisites before announcing setup (GH#5240)
 	local opencode_config
 	if ! opencode_config=$(find_opencode_config); then
-		print_warning "OpenCode config not found - skipping Google Analytics MCP"
+		print_skip "Google Analytics MCP" "OpenCode config not found" "Run 'opencode' once to create config, then re-run setup"
+		setup_track_skipped "Google Analytics MCP" "OpenCode config not found"
 		return 0
 	fi
 
-	# Check if jq is available
 	if ! command -v jq &>/dev/null; then
-		print_warning "jq not found - cannot add Google Analytics MCP to config"
-		print_info "Install jq and re-run setup, or manually add the MCP config"
+		print_skip "Google Analytics MCP" "jq not installed" "Install jq: brew install jq (macOS) or apt install jq"
+		setup_track_deferred "Google Analytics MCP" "Install jq"
 		return 0
 	fi
 
-	# Check if pipx is available
 	if ! command -v pipx &>/dev/null; then
-		print_warning "pipx not found - Google Analytics MCP requires pipx"
-		print_info "Install pipx: brew install pipx (macOS) or pip install pipx"
-		print_info "Then re-run setup to add Google Analytics MCP"
+		print_skip "Google Analytics MCP" "pipx not installed" "Install pipx: brew install pipx (macOS) or pip install pipx"
+		setup_track_deferred "Google Analytics MCP" "Install pipx"
 		return 0
 	fi
 
+	# Prerequisites met — proceed with setup
+	print_info "Setting up Google Analytics MCP..."
+
 	# Auto-detect credentials from shared GSC service account
 	local creds_path=""
 	local project_id=""
@@ -672,19 +670,20 @@ setup_google_analytics_mcp() {
 }
 
 setup_quickfile_mcp() {
-	print_info "Setting up QuickFile MCP server..."
-
 	local quickfile_dir="$HOME/Git/quickfile-mcp"
 	local credentials_dir="$HOME/.config/.quickfile-mcp"
 	local credentials_file="$credentials_dir/credentials.json"
 
-	# Check if Node.js is available
+	# Check prerequisites before announcing setup (GH#5240)
 	if ! command -v node &>/dev/null; then
-		print_warning "Node.js not found - QuickFile MCP setup skipped"
-		print_info "Install Node.js 18+ to enable QuickFile MCP"
+		print_skip "QuickFile MCP" "Node.js not installed" "Install Node.js 18+: brew install node (macOS) or nvm install 18"
+		setup_track_deferred "QuickFile MCP" "Install Node.js 18+"
 		return 0
 	fi
 
+	# Prerequisites met — proceed with setup
+	print_info "Setting up QuickFile MCP server..."
+
 	# Check if already cloned and built
 	if [[ -f "$quickfile_dir/dist/index.js" ]]; then
 		print_success "QuickFile MCP already installed at $quickfile_dir"

package/setup-modules/migrations.sh

@@ -37,6 +37,22 @@ cleanup_deprecated_paths() {
 		"$agents_dir/youtube"
 		# osgrep removed — disproportionate CPU/disk cost vs rg + LLM comprehension
 		"$agents_dir/tools/context/osgrep.md"
+		# GH#5155: scripts archived upstream but orphaned in deployed installs
+		# (rsync only adds/overwrites, doesn't delete removed files)
+		"$agents_dir/scripts/pattern-tracker-helper.sh"
+		"$agents_dir/scripts/quality-sweep-helper.sh"
+		"$agents_dir/scripts/quality-loop-helper.sh"
+		"$agents_dir/scripts/review-pulse-helper.sh"
+		"$agents_dir/scripts/self-improve-helper.sh"
+		"$agents_dir/scripts/coderabbit-pulse-helper.sh"
+		"$agents_dir/scripts/coderabbit-task-creator-helper.sh"
+		"$agents_dir/scripts/audit-task-creator-helper.sh"
+		"$agents_dir/scripts/batch-cleanup-helper.sh"
+		"$agents_dir/scripts/coordinator-helper.sh"
+		"$agents_dir/scripts/finding-to-task-helper.sh"
+		"$agents_dir/scripts/objective-runner-helper.sh"
+		"$agents_dir/scripts/ralph-loop-helper.sh"
+		"$agents_dir/scripts/stale-pr-helper.sh"
 	)
 
 	for path in "${deprecated_paths[@]}"; do
@@ -963,3 +979,88 @@ migrate_pulse_repos_to_repos_json() {
 
 	return 0
 }
+
+# Migrate orphaned supervisor-helper.sh and supervisor/ modules (GH#5147)
+# After the supervisor-to-pulse-wrapper migration (PR #2291, PR #2475), the
+# upstream repo moved supervisor files to supervisor-archived/. But aidevops
+# update (rsync) only adds/overwrites — it doesn't delete files that no longer
+# exist in the source. Users who installed before the migration retain:
+#   - ~/.aidevops/agents/scripts/supervisor-helper.sh (old entry point)
+#   - ~/.aidevops/agents/scripts/supervisor/ (old module directory)
+#   - cron/launchd entries invoking supervisor-helper.sh pulse
+# These orphaned files shadow the new pulse-wrapper.sh architecture.
+# This migration removes the orphaned files and rewrites scheduler entries.
+migrate_orphaned_supervisor() {
+	local agents_dir="$HOME/.aidevops/agents"
+	local scripts_dir="$agents_dir/scripts"
+	local cleaned=0
+
+	# 1. Remove orphaned supervisor-helper.sh from deployed scripts
+	#    The canonical location is now supervisor-archived/supervisor-helper.sh
+	#    (shipped for reference/tests only, not as an active entry point)
+	if [[ -f "$scripts_dir/supervisor-helper.sh" ]]; then
+		rm -f "$scripts_dir/supervisor-helper.sh"
+		print_info "Removed orphaned supervisor-helper.sh from deployed scripts"
+		((++cleaned))
+	fi
+
+	# 2. Remove orphaned supervisor/ module directory
+	#    The canonical location is now supervisor-archived/ (shipped by rsync)
+	#    Only remove if it's the old modules dir (contains pulse.sh, dispatch.sh, etc.)
+	#    Do NOT remove supervisor-archived/ — that's the intentional archive
+	if [[ -d "$scripts_dir/supervisor" && ! -L "$scripts_dir/supervisor" ]]; then
+		# Verify it's the old module directory (not something user-created)
+		if [[ -f "$scripts_dir/supervisor/pulse.sh" ]] ||
+			[[ -f "$scripts_dir/supervisor/dispatch.sh" ]] ||
+			[[ -f "$scripts_dir/supervisor/_common.sh" ]]; then
+			rm -rf "$scripts_dir/supervisor"
+			print_info "Removed orphaned supervisor/ module directory from deployed scripts"
+			((++cleaned))
+		fi
+	fi
+
+	# 3. Migrate cron entries from supervisor-helper.sh to pulse-wrapper.sh
+	#    Old pattern: */2 * * * * ... supervisor-helper.sh pulse ...
+	#    New pattern: already installed by setup.sh's pulse section
+	#    Strategy: remove old entries; setup.sh will install the new one if pulse is enabled
+	local current_crontab
+	current_crontab=$(crontab -l 2>/dev/null) || current_crontab=""
+	if echo "$current_crontab" | grep -qF "supervisor-helper.sh"; then
+		# Remove all cron lines referencing supervisor-helper.sh
+		local new_crontab
+		new_crontab=$(echo "$current_crontab" | grep -v "supervisor-helper.sh")
+		if [[ -n "$new_crontab" ]]; then
+			printf '%s\n' "$new_crontab" | crontab - || true
+		else
+			# All entries were supervisor-helper.sh — remove crontab entirely
+			crontab -r || true
+		fi
+		print_info "Removed orphaned supervisor-helper.sh cron entries"
+		print_info "  pulse-wrapper.sh will be installed by setup.sh if supervisor pulse is enabled"
+		((++cleaned))
+	fi
+
+	# 4. Migrate launchd entries from old supervisor label (macOS only)
+	#    Old label: com.aidevops.supervisor-pulse (from cron.sh/launchd.sh)
+	#    New label: com.aidevops.aidevops-supervisor-pulse (from setup.sh)
+	#    setup.sh already handles the new label cleanup at line ~1000, but
+	#    the old label from cron.sh may also be present
+	if [[ "$(uname -s)" == "Darwin" ]]; then
+		local old_label="com.aidevops.supervisor-pulse"
+		local old_plist="$HOME/Library/LaunchAgents/${old_label}.plist"
+		if _launchd_has_agent "$old_label" || [[ -f "$old_plist" ]]; then
+			# Use launchctl remove by label — works even when the plist file is
+			# missing (orphaned agent loaded without a backing file on disk)
+			launchctl remove "$old_label" || true
+			rm -f "$old_plist"
+			print_info "Removed orphaned supervisor-pulse LaunchAgent ($old_label)"
+			((++cleaned))
+		fi
+	fi
+
+	if [[ $cleaned -gt 0 ]]; then
+		print_success "Cleaned up $cleaned orphaned supervisor artifact(s) — pulse-wrapper.sh is the active system"
+	fi
+
+	return 0
+}

package/setup-modules/plugins.sh

@@ -117,12 +117,13 @@ deploy_plugins() {
 	local target_dir="$1"
 	local plugins_file="$2"
 
-	# Skip if no plugins.json or no jq
+	# Skip if no plugins.json or no jq (GH#5240: clear skip messages)
 	if [[ ! -f "$plugins_file" ]]; then
 		return 0
 	fi
 	if ! command -v jq &>/dev/null; then
-		print_warning "jq not found; skipping plugin deployment"
+		print_skip "Plugin deployment" "jq not installed" "Install jq: brew install jq (macOS) or apt install jq"
+		setup_track_deferred "Plugin deployment" "Install jq"
 		return 0
 	fi
 
@@ -401,15 +402,18 @@ check_skill_updates() {
 }
 
 scan_imported_skills() {
-	print_info "Running security scan on imported skills..."
-
+	# Check prerequisites before announcing setup (GH#5240)
 	local security_helper="$HOME/.aidevops/agents/scripts/security-helper.sh"
 
 	if [[ ! -f "$security_helper" ]]; then
-		print_warning "security-helper.sh not found - skipping skill scan"
+		print_skip "Skill security scan" "security-helper.sh not found" "Deploy agents first (setup.sh), then re-run"
+		setup_track_skipped "Skill security scan" "security-helper.sh not found"
 		return 0
 	fi
 
+	# Prerequisites met — proceed with setup
+	print_info "Running security scan on imported skills..."
+
 	# Install skill-scanner if not present
 	# Pre-check: cisco-ai-skill-scanner requires Python >= 3.10
 	# Fallback chain: uv -> pipx -> venv+symlink -> pip3 --user (legacy)
@@ -484,8 +488,7 @@ scan_imported_skills() {
 }
 
 setup_multi_tenant_credentials() {
-	print_info "Multi-tenant credential storage..."
-
+	# Check prerequisites before announcing setup (GH#5240)
 	local credential_helper="$HOME/.aidevops/agents/scripts/credential-helper.sh"
 
 	if [[ ! -f "$credential_helper" ]]; then
@@ -494,10 +497,14 @@ setup_multi_tenant_credentials() {
 	fi
 
 	if [[ ! -f "$credential_helper" ]]; then
-		print_warning "credential-helper.sh not found - skipping"
+		print_skip "Multi-tenant credentials" "credential-helper.sh not found" "Deploy agents first (setup.sh), then re-run"
+		setup_track_skipped "Multi-tenant credentials" "credential-helper.sh not found"
 		return 0
 	fi
 
+	# Prerequisites met — proceed with setup
+	print_info "Multi-tenant credential storage..."
+
 	# Check if already initialized
 	if [[ -d "$HOME/.config/aidevops/tenants" ]]; then
 		local tenant_count
@@ -547,8 +554,7 @@ setup_multi_tenant_credentials() {
 }
 
 check_tool_updates() {
-	print_info "Checking for tool updates..."
-
+	# Check prerequisites before announcing setup (GH#5240)
 	local tool_check_script="$HOME/.aidevops/agents/scripts/tool-version-check.sh"
 
 	if [[ ! -f "$tool_check_script" ]]; then
@@ -557,10 +563,14 @@ check_tool_updates() {
 	fi
 
 	if [[ ! -f "$tool_check_script" ]]; then
-		print_warning "Tool version check script not found - skipping update check"
+		print_skip "Tool updates" "version check script not found" "Deploy agents first (setup.sh), then re-run"
+		setup_track_skipped "Tool updates" "version check script not found"
 		return 0
 	fi
 
+	# Prerequisites met — proceed with setup
+	print_info "Checking for tool updates..."
+
 	# Run the check in quiet mode first to see if there are updates
 	# Capture both output and exit code
 	local outdated_output

package/setup-modules/shell-env.sh

@@ -94,24 +94,25 @@ get_all_shell_rcs() {
 
 # Offer to install Oh My Zsh if zsh is the default shell and OMZ is not present
 setup_oh_my_zsh() {
-	# Only relevant if zsh is available
+	# Check prerequisites before announcing setup (GH#5240)
 	if ! command -v zsh >/dev/null 2>&1; then
-		print_info "zsh not found - skipping Oh My Zsh setup"
+		print_skip "Oh My Zsh" "zsh not installed" "Install zsh first, then re-run setup"
+		setup_track_skipped "Oh My Zsh" "zsh not installed"
 		return 0
 	fi
 
-	# Check if Oh My Zsh is already installed
 	if [[ -d "$HOME/.oh-my-zsh" ]]; then
 		print_success "Oh My Zsh already installed"
+		setup_track_configured "Oh My Zsh"
 		return 0
 	fi
 
 	local default_shell
 	default_shell=$(detect_default_shell)
 
-	# Only offer if zsh is the default shell (or on macOS where it's the system default)
 	if [[ "$default_shell" != "zsh" && "$(uname)" != "Darwin" ]]; then
-		print_info "Default shell is $default_shell (not zsh) - skipping Oh My Zsh"
+		print_skip "Oh My Zsh" "default shell is $default_shell (not zsh)" "Change default shell to zsh: chsh -s \$(which zsh)"
+		setup_track_skipped "Oh My Zsh" "default shell is $default_shell"
 		return 0
 	fi
 
@@ -386,6 +387,10 @@ check_optional_deps() {
 	print_info "Checking optional dependencies..."
 
 	local missing_optional=()
+	local recommended_python_formula
+	recommended_python_formula=$(get_recommended_python_formula)
+	local python_required_major="${PYTHON_REQUIRED_MAJOR:-3}"
+	local python_required_minor="${PYTHON_REQUIRED_MINOR:-10}"
 
 	if ! command -v sshpass >/dev/null 2>&1; then
 		missing_optional+=("sshpass")
@@ -393,6 +398,26 @@ check_optional_deps() {
 		print_success "sshpass found"
 	fi
 
+	local python3_bin=""
+	if python3_bin=$(find_python3); then
+		local python_version
+		python_version=$("$python3_bin" -c 'import sys; print("{}.{}.{}".format(sys.version_info[0], sys.version_info[1], sys.version_info[2]))' 2>/dev/null || true)
+		local python_major
+		python_major=$(echo "$python_version" | cut -d. -f1)
+		local python_minor
+		python_minor=$(echo "$python_version" | cut -d. -f2)
+
+		if [[ "$python_major" =~ ^[0-9]+$ ]] && [[ "$python_minor" =~ ^[0-9]+$ ]] && { ((python_major > python_required_major)) || { ((python_major == python_required_major)) && ((python_minor >= python_required_minor)); }; }; then
+			print_success "Python $python_version found ($python_required_major.$python_required_minor+ required)"
+		else
+			print_warning "Python $python_version found, but $python_required_major.$python_required_minor+ is recommended for all skills/tools"
+			offer_python_brew_install "upgrade" "$recommended_python_formula" || true
+		fi
+	else
+		print_warning "Python 3 not found"
+		offer_python_brew_install "install" "$recommended_python_formula" || true
+	fi
+
 	if [[ ${#missing_optional[@]} -gt 0 ]]; then
 		print_warning "Missing optional dependencies: ${missing_optional[*]}"
 		echo "  sshpass - needed for password-based SSH (like Hostinger)"
@@ -822,12 +847,12 @@ ALIASES
 
 # Install terminal title integration that syncs tab titles with git repo/branch
 setup_terminal_title() {
-	print_info "Setting up terminal title integration..."
-
+	# Check prerequisites before announcing setup (GH#5240)
 	local setup_script=".agents/scripts/terminal-title-setup.sh"
 
 	if [[ ! -f "$setup_script" ]]; then
-		print_warning "Terminal title setup script not found - skipping"
+		print_skip "Terminal title" "setup script not found" "Deploy agents first (setup.sh), then re-run"
+		setup_track_skipped "Terminal title" "setup script not found"
 		return 0
 	fi
 
@@ -843,10 +868,14 @@ setup_terminal_title() {
 	done < <(get_all_shell_rcs)
 
 	if [[ "$title_configured" == "true" ]]; then
-		print_info "Terminal title integration already configured - Skipping"
+		print_success "Terminal title integration already configured"
+		setup_track_configured "Terminal title"
 		return 0
 	fi
 
+	# Prerequisites met — proceed with setup
+	print_info "Setting up terminal title integration..."
+
 	# Show current status before asking
 	echo ""
 	print_info "Terminal title integration syncs your terminal tab with git repo/branch"

package/setup-modules/tool-install.sh

@@ -57,7 +57,7 @@ setup_git_clis() {
 					echo "📋 Next steps - authenticate each CLI:"
 					for pkg in "${missing_packages[@]}"; do
 						case "$pkg" in
-						gh) echo "  • gh auth login" ;;
+						gh) echo "  • gh auth login -s workflow  (workflow scope required for CI PRs)" ;;
 						glab) echo "  • glab auth login" ;;
 						esac
 					done
@@ -1001,6 +1001,92 @@ setup_ssh_key() {
 	return 0
 }
 
+# Check installed Python version against latest stable available from package manager.
+# Warns if an upgrade is available but never auto-upgrades (GH#5237).
+# Works on macOS (Homebrew) and Linux (apt/dnf).
+check_python_version() {
+	print_info "Checking Python version..."
+
+	# 1. Check currently installed Python
+	local python3_bin
+	if ! python3_bin=$(find_python3); then
+		print_warning "Python 3 not found"
+		echo ""
+		echo "  Install options:"
+		if [[ "$PLATFORM_MACOS" == "true" ]]; then
+			echo "    brew install python3"
+		elif command -v apt-get >/dev/null 2>&1; then
+			echo "    sudo apt install python3"
+		elif command -v dnf >/dev/null 2>&1; then
+			echo "    sudo dnf install python3"
+		else
+			echo "    Install Python 3 via your system package manager"
+		fi
+		echo ""
+		return 0
+	fi
+
+	local installed_version
+	installed_version=$("$python3_bin" --version 2>&1 | cut -d' ' -f2)
+	local installed_major installed_minor
+	installed_major=$(echo "$installed_version" | cut -d. -f1)
+	installed_minor=$(echo "$installed_version" | cut -d. -f2)
+
+	# 2. Determine latest stable version from package manager
+	local latest_version=""
+
+	if [[ "$PLATFORM_MACOS" == "true" ]] && command -v brew >/dev/null 2>&1; then
+		# Homebrew: `brew info python3` outputs "python@3.X: 3.X.Y" on the first line
+		latest_version=$(brew info --json=v2 python3 2>/dev/null |
+			python3 -c "import sys,json; d=json.load(sys.stdin); print(d['formulae'][0]['versions']['stable'])" 2>/dev/null) || latest_version=""
+	elif command -v apt-cache >/dev/null 2>&1; then
+		# Debian/Ubuntu: get candidate version from apt-cache
+		latest_version=$(apt-cache policy python3 2>/dev/null |
+			awk '/Candidate:/{print $2}' |
+			grep -oE '[0-9]+\.[0-9]+\.[0-9]+') || latest_version=""
+	elif command -v dnf >/dev/null 2>&1; then
+		# Fedora/RHEL: get available version from dnf
+		latest_version=$(dnf info python3 2>/dev/null |
+			awk '/^Version/{print $3}') || latest_version=""
+	fi
+
+	# 3. Compare versions and advise
+	if [[ -z "$latest_version" ]]; then
+		# Could not determine latest — just report installed version
+		print_success "Python $installed_version found"
+		return 0
+	fi
+
+	local latest_major latest_minor
+	latest_major=$(echo "$latest_version" | cut -d. -f1)
+	latest_minor=$(echo "$latest_version" | cut -d. -f2)
+
+	# Compare major.minor (patch differences are not worth warning about)
+	if [[ "$installed_major" -lt "$latest_major" ]] ||
+		{ [[ "$installed_major" -eq "$latest_major" ]] && [[ "$installed_minor" -lt "$latest_minor" ]]; }; then
+		print_warning "Python $installed_version installed, but $latest_version is available"
+		echo ""
+		echo "  Some tools and skills require Python 3.10+."
+		echo "  Upgrade is recommended but not required."
+		echo ""
+		if [[ "$PLATFORM_MACOS" == "true" ]]; then
+			echo "  Upgrade command:"
+			echo "    brew upgrade python3"
+		elif command -v apt-get >/dev/null 2>&1; then
+			echo "  Upgrade command:"
+			echo "    sudo apt update && sudo apt install python3"
+		elif command -v dnf >/dev/null 2>&1; then
+			echo "  Upgrade command:"
+			echo "    sudo dnf upgrade python3"
+		fi
+		echo ""
+	else
+		print_success "Python $installed_version found (latest stable: $latest_version)"
+	fi
+
+	return 0
+}
+
 setup_python_env() {
 	print_info "Setting up Python environment for DSPy..."
 
@@ -1370,36 +1456,32 @@ setup_ai_orchestration() {
 	print_info "Setting up AI orchestration frameworks..."
 
 	local has_python=false
-
-	# Check Python (prefer Homebrew/pyenv over system)
+	local python_required_major="${PYTHON_REQUIRED_MAJOR:-3}"
+	local python_required_minor="${PYTHON_REQUIRED_MINOR:-10}"
+	local recommended_python_formula
+	recommended_python_formula=$(get_recommended_python_formula)
+
+	# Check Python (prefer Homebrew/pyenv over system) — uses shared helpers
+	# from _common.sh (get_recommended_python_formula, find_python3,
+	# offer_python_brew_install) to avoid duplicating version-check logic.
 	local python3_bin
 	if python3_bin=$(find_python3); then
 		local python_version
-		python_version=$("$python3_bin" --version 2>&1 | cut -d' ' -f2)
+		python_version=$("$python3_bin" -c 'import sys; print("{}.{}.{}".format(sys.version_info[0], sys.version_info[1], sys.version_info[2]))' 2>/dev/null || true)
 		local major minor
 		major=$(echo "$python_version" | cut -d. -f1)
 		minor=$(echo "$python_version" | cut -d. -f2)
 
-		if [[ $major -ge 3 ]] && [[ $minor -ge 10 ]]; then
+		if [[ "$major" =~ ^[0-9]+$ ]] && [[ "$minor" =~ ^[0-9]+$ ]] && { ((major > python_required_major)) || { ((major == python_required_major)) && ((minor >= python_required_minor)); }; }; then
 			has_python=true
-			print_success "Python $python_version found (3.10+ required)"
+			print_success "Python $python_version found ($python_required_major.$python_required_minor+ required)"
 		else
-			print_warning "Python 3.10+ required for AI orchestration, found $python_version"
-			echo ""
-			echo "  Upgrade options:"
-			echo "    macOS (Homebrew): brew install python@3.12"
-			echo "    macOS (pyenv):    pyenv install 3.12 && pyenv global 3.12"
-			echo "    Ubuntu/Debian:    sudo apt install python3.12"
-			echo "    Fedora:           sudo dnf install python3.12"
-			echo ""
+			print_warning "Python $python_required_major.$python_required_minor+ required for AI orchestration, found $python_version"
+			offer_python_brew_install "upgrade" "$recommended_python_formula" || true
 		fi
 	else
 		print_warning "Python 3 not found - AI orchestration frameworks unavailable"
-		echo ""
-		echo "  Install options:"
-		echo "    macOS: brew install python@3.12"
-		echo "    Linux: sudo apt install python3 (or dnf/pacman)"
-		echo ""
+		offer_python_brew_install "install" "$recommended_python_formula" || true
 		return 0
 	fi
 

package/setup.sh

@@ -10,7 +10,7 @@ shopt -s inherit_errexit 2>/dev/null || true
 # AI Assistant Server Access Framework Setup Script
 # Helps developers set up the framework for their infrastructure
 #
-# Version: 3.0.12
+# Version: 3.1.1
 #
 # Quick Install:
 #   npm install -g aidevops && aidevops update          (recommended)
@@ -22,6 +22,7 @@ GREEN='\033[0;32m'
 BLUE='\033[0;34m'
 YELLOW='\033[1;33m'
 RED='\033[0;31m'
+GRAY='\033[0;90m'
 NC='\033[0m' # No Color
 
 # Global flags
@@ -29,6 +30,11 @@ CLEAN_MODE=false
 INTERACTIVE_MODE=false
 NON_INTERACTIVE="${AIDEVOPS_NON_INTERACTIVE:-false}"
 UPDATE_TOOLS_MODE=false
+# Python compatibility floor used by setup checks and skill/tool gating.
+# Keep in sync with setup-modules/plugins.sh requirements.
+PYTHON_REQUIRED_MAJOR=3
+PYTHON_REQUIRED_MINOR=10
+export PYTHON_REQUIRED_MAJOR PYTHON_REQUIRED_MINOR
 # Platform constants — exported for sourced setup-modules (shell-env.sh,
 # tool-install.sh) that reference them at runtime.
 PLATFORM_MACOS=$([[ "$(uname -s)" == "Darwin" ]] && echo true || echo false)
@@ -362,26 +368,8 @@ find_opencode_config() {
 	return 1
 }
 
-# Find best python3 binary (prefer Homebrew/pyenv over system)
-find_python3() {
-	local candidates=(
-		"/opt/homebrew/bin/python3"
-		"/usr/local/bin/python3"
-		"$HOME/.pyenv/shims/python3"
-	)
-	for candidate in "${candidates[@]}"; do
-		if [[ -x "$candidate" ]]; then
-			echo "$candidate"
-			return 0
-		fi
-	done
-	# Fallback to PATH
-	if command -v python3 &>/dev/null; then
-		command -v python3
-		return 0
-	fi
-	return 1
-}
+# get_latest_homebrew_python_formula() and find_python3() are defined in
+# _common.sh (sourced above). Not duplicated here — see GH#5239 review.
 
 # Install a package globally via npm, with sudo when needed on Linux.
 # Usage: npm_global_install "package-name" OR npm_global_install "package@version"
@@ -709,6 +697,7 @@ main() {
 		print_info "Non-interactive mode: deploying agents and running safe migrations only"
 		verify_location
 		check_requirements
+		check_python_version
 		set_permissions
 		migrate_old_backups
 		migrate_loop_state_directories
@@ -716,6 +705,7 @@ main() {
 		migrate_mcp_env_to_credentials
 		migrate_pulse_repos_to_repos_json
 		cleanup_deprecated_paths
+		migrate_orphaned_supervisor
 		cleanup_deprecated_mcps
 		cleanup_stale_bun_opencode
 		validate_opencode_config
@@ -772,6 +762,7 @@ main() {
 
 		# Optional steps with confirmation in interactive mode
 		confirm_step "Check optional dependencies (bun, node, python)" && check_optional_deps
+		confirm_step "Check Python version (recommend upgrade if outdated)" && check_python_version
 		confirm_step "Setup recommended tools (Tabby, Zed, etc.)" && setup_recommended_tools
 		confirm_step "Setup MiniSim (iOS/Android emulator launcher)" && setup_minisim
 		confirm_step "Setup Git CLIs (gh, glab, tea)" && setup_git_clis
@@ -795,6 +786,7 @@ main() {
 		confirm_step "Migrate mcp-env.sh -> credentials.sh" && migrate_mcp_env_to_credentials
 		confirm_step "Migrate pulse-repos.json into repos.json" && migrate_pulse_repos_to_repos_json
 		confirm_step "Cleanup deprecated agent paths" && cleanup_deprecated_paths
+		confirm_step "Migrate orphaned supervisor to pulse-wrapper" && migrate_orphaned_supervisor
 		confirm_step "Cleanup deprecated MCP entries (hetzner, serper, etc.)" && cleanup_deprecated_mcps
 		confirm_step "Cleanup stale bun opencode install" && cleanup_stale_bun_opencode
 		confirm_step "Validate and repair OpenCode config schema" && validate_opencode_config
@@ -833,8 +825,11 @@ main() {
 		confirm_step "Disable on-demand MCPs globally" && disable_ondemand_mcps
 	fi
 
+	# Print setup summary before final success message (GH#5240)
+	print_setup_summary
+
 	echo ""
-	print_success "🎉 Setup complete!"
+	print_success "Setup complete!"
 
 	# Enable auto-update if not already enabled
 	# Check both launchd (macOS) and cron (Linux) for existing installation
@@ -892,10 +887,6 @@ main() {
 	#   - Non-interactive: only installs if config explicitly says true
 	local wrapper_script="$HOME/.aidevops/agents/scripts/pulse-wrapper.sh"
 	local pulse_label="com.aidevops.aidevops-supervisor-pulse"
-	local _aidevops_dir _pulse_repo_dir
-	_aidevops_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-	_pulse_repo_dir=$(_resolve_main_worktree_dir "$_aidevops_dir")
-
 	# Read explicit user consent from config.jsonc (not merged defaults).
 	# Empty = user never configured this; "true"/"false" = explicit choice.
 	local _pulse_user_config=""
@@ -1009,12 +1000,14 @@ main() {
 
 			# XML-escape paths for safe plist embedding (prevents injection
 			# if $HOME or paths contain &, <, > characters)
-			local _xml_wrapper_script _xml_home _xml_opencode_bin _xml_aidevops_dir _xml_path
+			local _xml_wrapper_script _xml_home _xml_opencode_bin _xml_pulse_dir _xml_path
 			local _headless_xml_env=""
 			_xml_wrapper_script=$(_xml_escape "$wrapper_script")
 			_xml_home=$(_xml_escape "$HOME")
 			_xml_opencode_bin=$(_xml_escape "$opencode_bin")
-			_xml_aidevops_dir=$(_xml_escape "$_pulse_repo_dir")
+			# Use neutral workspace path for PULSE_DIR so supervisor sessions
+			# are not associated with any specific managed repo (GH#5136).
+			_xml_pulse_dir=$(_xml_escape "${HOME}/.aidevops/.agent-workspace")
 			_xml_path=$(_xml_escape "$PATH")
 			if [[ -n "${AIDEVOPS_HEADLESS_MODELS:-}" ]]; then
 				local _xml_headless_models
@@ -1061,7 +1054,7 @@ main() {
 		<key>OPENCODE_BIN</key>
 		<string>${_xml_opencode_bin}</string>
 		<key>PULSE_DIR</key>
-		<string>${_xml_aidevops_dir}</string>
+		<string>${_xml_pulse_dir}</string>
 		<key>PULSE_STALE_THRESHOLD</key>
 		<string>1800</string>
 		${_headless_xml_env}
@@ -1092,8 +1085,9 @@ PLIST
 			# PATH= here, it overrides the global line and breaks nvm/bun/cargo.
 			# OPENCODE_BIN removed — resolved from PATH at runtime via command -v.
 			# See #4099 and #4240 for history.
-			local _cron_aidevops_dir _cron_wrapper_script _cron_headless_env=""
-			_cron_aidevops_dir=$(_cron_escape "$_pulse_repo_dir")
+			local _cron_pulse_dir _cron_wrapper_script _cron_headless_env=""
+			# Use neutral workspace path for PULSE_DIR (GH#5136)
+			_cron_pulse_dir=$(_cron_escape "${HOME}/.aidevops/.agent-workspace")
 			_cron_wrapper_script=$(_cron_escape "$wrapper_script")
 			if [[ -n "${AIDEVOPS_HEADLESS_MODELS:-}" ]]; then
 				local _cron_headless_models
@@ -1107,7 +1101,7 @@ PLIST
 			fi
 			(
 				crontab -l 2>/dev/null | grep -v 'aidevops: supervisor-pulse'
-				echo "*/2 * * * * PULSE_DIR=${_cron_aidevops_dir}${_cron_headless_env} /bin/bash ${_cron_wrapper_script} >> \"\$HOME/.aidevops/logs/pulse-wrapper.log\" 2>&1 # aidevops: supervisor-pulse"
+				echo "*/2 * * * * PULSE_DIR=${_cron_pulse_dir}${_cron_headless_env} /bin/bash ${_cron_wrapper_script} >> \"\$HOME/.aidevops/logs/pulse-wrapper.log\" 2>&1 # aidevops: supervisor-pulse"
 			) | crontab - || true
 			if crontab -l 2>/dev/null | grep -qF "aidevops: supervisor-pulse"; then
 				print_info "Supervisor pulse enabled (cron, every 2 min). Disable: crontab -e and remove the supervisor-pulse line"