aidevops 3.13.93 → 3.13.94

package/VERSION

@@ -1 +1 @@
-3.13.93
+3.13.94

package/aidevops-init-lib.sh

@@ -31,6 +31,92 @@
 [[ -n "${_AIDEVOPS_INIT_LIB_LOADED:-}" ]] && return 0
 _AIDEVOPS_INIT_LIB_LOADED=1
 
+_AGENT_SOURCE_TEMPLATE_VERSION="1"
+
+_agent_source_template_dir() {
+	printf '%s\n' "${AGENTS_DIR}/templates/agent-source-repo"
+	return 0
+}
+
+_agent_source_apply_managed_template_file() {
+	local project_root="$1"
+	local relative_path="$2"
+	local template_dir dest src dest_dir
+	template_dir=$(_agent_source_template_dir)
+	src="$template_dir/$relative_path"
+	dest="$project_root/$relative_path"
+	dest_dir="${dest%/*}"
+
+	[[ -f "$src" ]] || return 1
+	[[ "$dest_dir" != "$dest" ]] && mkdir -p "$dest_dir"
+
+	if [[ ! -f "$dest" ]]; then
+		cp "$src" "$dest"
+		return 0
+	fi
+
+	if ! grep -q '<!-- aidevops:agent-source-template:start -->' "$dest" 2>/dev/null; then
+		return 0
+	fi
+	if ! grep -q '<!-- aidevops:agent-source-template:end -->' "$dest" 2>/dev/null; then
+		return 0
+	fi
+
+	python3 - "$dest" "$src" <<'PY'
+from pathlib import Path
+import sys
+
+dest = Path(sys.argv[1])
+src = Path(sys.argv[2])
+start = "<!-- aidevops:agent-source-template:start -->"
+end = "<!-- aidevops:agent-source-template:end -->"
+old = dest.read_text()
+new = src.read_text()
+if start not in old or end not in old or start not in new or end not in new:
+    sys.exit(0)
+old_prefix = old.split(start, 1)[0]
+old_suffix = old.split(end, 1)[1]
+new_block = start + new.split(start, 1)[1].split(end, 1)[0] + end
+dest.write_text(old_prefix + new_block + old_suffix)
+PY
+	return 0
+}
+
+seed_agent_source_repo_templates() {
+	local project_root="$1"
+	local template_dir
+	template_dir=$(_agent_source_template_dir)
+
+	if [[ ! -d "$template_dir" ]]; then
+		print_warning "Agent source template directory missing: $template_dir"
+		return 1
+	fi
+
+	local rel_dir
+	for rel_dir in \
+		".agents" \
+		".agents/tools" \
+		".agents/services" \
+		".agents/workflows" \
+		".agents/reference" \
+		".agents/scripts" \
+		".agents/scripts/commands" \
+		".agents/configs" \
+		".agents/bundles" \
+		".agents/templates" \
+		".agents/rules" \
+		".agents/tests" \
+		".agents/custom" \
+		".agents/draft"; do
+		mkdir -p "$project_root/$rel_dir"
+	done
+
+	_agent_source_apply_managed_template_file "$project_root" "AGENTS.md" || return 1
+	_agent_source_apply_managed_template_file "$project_root" ".agents/AGENTS.md" || return 1
+	print_success "Seeded agent-source repository templates (v${_AGENT_SOURCE_TEMPLATE_VERSION})"
+	return 0
+}
+
 # Scaffold standard repo courtesy files if they don't exist
 # Scaffold helpers (extracted for complexity reduction)
 _scaffold_contributing() {
@@ -639,6 +725,12 @@ cmd_init() {
 	init_scope=$(_infer_init_scope "$project_root")
 	print_info "Init scope: $init_scope (controls which scaffolding files are created)"
 
+	local is_agent_source=false
+	if is_agent_source_repo "$project_root"; then
+		is_agent_source=true
+		print_info "Agent source repo: true (seeding core-style agent organization)"
+	fi
+
 	# Create .aidevops.json config
 	local config_file="$project_root/.aidevops.json"
 	local aidevops_version
@@ -650,6 +742,7 @@ cmd_init() {
   "version": "$aidevops_version",
   "initialized": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
   "init_scope": "$init_scope",
+  "agent_source": $is_agent_source,
   "features": {
     "planning": $enable_planning,
     "git_workflow": $enable_git_workflow,
@@ -747,19 +840,23 @@ EOF
 	# (symlinked) can see the aidevops main-agent slash commands.
 	_init_scaffold_commands_symlinks "$project_root"
 
-	# Scaffold or update .agents/AGENTS.md (idempotent — creates if missing,
-	# updates Security section if file already exists)
-	local _agents_md_existed=false
-	[[ -f "$project_root/.agents/AGENTS.md" ]] && _agents_md_existed=true
-	scaffold_agents_md "$project_root"
-	if [[ "$_agents_md_existed" == "true" ]]; then
-		print_success "Updated Security section in .agents/AGENTS.md"
+	if [[ "$is_agent_source" == "true" ]]; then
+		seed_agent_source_repo_templates "$project_root"
 	else
-		print_success "Created .agents/AGENTS.md"
+		# Scaffold or update .agents/AGENTS.md (idempotent — creates if missing,
+		# updates Security section if file already exists)
+		local _agents_md_existed=false
+		[[ -f "$project_root/.agents/AGENTS.md" ]] && _agents_md_existed=true
+		scaffold_agents_md "$project_root"
+		if [[ "$_agents_md_existed" == "true" ]]; then
+			print_success "Updated Security section in .agents/AGENTS.md"
+		else
+			print_success "Created .agents/AGENTS.md"
+		fi
 	fi
 
 	# Scaffold root AGENTS.md if missing
-	if [[ ! -f "$project_root/AGENTS.md" ]]; then
+	if [[ "$is_agent_source" != "true" && ! -f "$project_root/AGENTS.md" ]]; then
 		cat >"$project_root/AGENTS.md" <<ROOTAGENTSEOF
 # $repo_name
 

package/aidevops-repos-lib.sh

@@ -246,7 +246,61 @@ _scope_includes() {
 		*)        required_level=1 ;;
 	esac
 
-	[[ $current_level -ge $required_level ]]
+	if [[ $current_level -ge $required_level ]]; then
+		return 0
+	fi
+	return 1
+}
+
+# Check whether a repo is marked as an agent source repo in local project
+# config or repos.json. Agent source repos use the same organization model as
+# the core `.agents/` tree and receive safe template seeding/updating.
+# Usage: is_agent_source_repo <project_root>
+is_agent_source_repo() {
+	local project_root="$1"
+
+	if command -v jq &>/dev/null && [[ -f "$project_root/.aidevops.json" ]]; then
+		local project_flag
+		project_flag=$(jq -r 'if .agent_source == true or .role == "agent-source" then "true" else "false" end' "$project_root/.aidevops.json" 2>/dev/null || echo "false")
+		if [[ "$project_flag" == "true" ]]; then
+			return 0
+		fi
+	fi
+
+	if command -v jq &>/dev/null && [[ -f "${REPOS_FILE:-$HOME/.config/aidevops/repos.json}" ]]; then
+		local repos_file="${REPOS_FILE:-$HOME/.config/aidevops/repos.json}"
+		local canonical_path
+		canonical_path=$(cd "$project_root" 2>/dev/null && pwd -P) || canonical_path="$project_root"
+		local repo_flag
+		repo_flag=$(jq -r --arg path "$canonical_path" --arg raw_path "$project_root" '
+			.initialized_repos // []
+			| map(select(.path == $path or .path == $raw_path))
+			| if length > 0 and (.[0].agent_source == true or .[0].role == "agent-source") then "true" else "false" end
+		' "$repos_file" 2>/dev/null || echo "false")
+		if [[ "$repo_flag" == "true" ]]; then
+			return 0
+		fi
+	fi
+
+	return 1
+}
+
+# Print registered repo paths marked as agent source repos.
+# Usage: get_agent_source_repos
+get_agent_source_repos() {
+	init_repos_file
+
+	if ! command -v jq &>/dev/null; then
+		return 0
+	fi
+
+	jq -r '
+		.initialized_repos // []
+		| .[]
+		| select(.agent_source == true or .role == "agent-source")
+		| .path // empty
+	' "$REPOS_FILE" 2>/dev/null || true
+	return 0
 }
 
 # Resolve a worktree path to its canonical main-worktree path, if applicable.
@@ -644,4 +698,3 @@ check_protected_branch() {
 		;;
 	esac
 }
-

package/aidevops-update-lib.sh

@@ -63,6 +63,7 @@ _update_sync_projects() {
 		[[ -z "$repo_path" ]] && continue
 		[[ -d "$repo_path" ]] && check_repo_needs_upgrade "$repo_path" && repos_needing_upgrade+=("$repo_path")
 	done < <(get_registered_repos)
+	_update_sync_agent_source_repos "$current_ver" || true
 	if [[ ${#repos_needing_upgrade[@]} -eq 0 ]]; then
 		print_success "All registered projects are up to date"
 		return 0
@@ -95,6 +96,34 @@ _update_sync_projects() {
 	return 0
 }
 
+_update_sync_agent_source_repos() {
+	local current_ver="$1"
+	local synced=0 skipped=0 failed=0
+	local repo
+
+	while IFS= read -r repo; do
+		[[ -z "$repo" ]] && continue
+		if [[ ! -d "$repo" ]]; then
+			skipped=$((skipped + 1))
+			continue
+		fi
+		if seed_agent_source_repo_templates "$repo"; then
+			synced=$((synced + 1))
+			if [[ -f "$repo/.aidevops.json" ]] && command -v jq &>/dev/null; then
+				local temp_file="${repo}/.aidevops.json.tmp"
+				jq --arg version "$current_ver" '.version = $version | .agent_source = true' "$repo/.aidevops.json" >"$temp_file" 2>/dev/null && mv "$temp_file" "$repo/.aidevops.json" || rm -f "$temp_file"
+			fi
+		else
+			failed=$((failed + 1))
+		fi
+	done < <(get_agent_source_repos)
+
+	[[ $synced -gt 0 ]] && print_success "Synced $synced agent-source repo template(s)"
+	[[ $skipped -gt 0 ]] && print_info "Skipped $skipped unavailable agent-source repo(s)"
+	[[ $failed -gt 0 ]] && print_warning "$failed agent-source repo template sync(s) failed"
+	return 0
+}
+
 _update_check_planning() {
 	echo ""
 	print_header "Checking Planning Templates"

package/aidevops.sh

@@ -5,7 +5,7 @@
 # AI DevOps Framework CLI
 # Usage: aidevops <command> [options]
 #
-# Version: 3.13.93
+# Version: 3.13.94
 
 set -euo pipefail
 
@@ -766,6 +766,7 @@ _help_commands() {
 	echo "  email [cmd]        Email mailbox management (mailbox add/list/test/remove)"
 	echo "  ip-check <cmd>     IP reputation checks (check/batch/report/providers)"
 	echo "  review-gate <cmd>  Configure review_gate.rate_limit_behavior (list/set/unset)"
+	echo "  github-app-auth    GitHub App auth setup/status and API route decisions"
 	echo "  secret <cmd>       Manage secrets (set/list/run/init/import/status)"
 	echo "  config <cmd>       Feature toggles (list/get/set/reset/path/help)"
 	echo "  knowledge <cmd>    Knowledge plane management (init/status/provision)"
@@ -842,6 +843,11 @@ _help_detailed_sections() {
 	echo "  aidevops secret import       # Import from credentials.sh to gopass"
 	echo "  aidevops secret status       # Show backend status"
 	echo ""
+	echo "GitHub App Auth:"
+	echo "  aidevops github-app-auth status --json       # Show active auth mode and budgets"
+	echo "  aidevops github-app-auth route issue-list    # Explain route decision"
+	echo "  aidevops github-app-auth rate-limit --json   # Show cached per-pool budgets"
+	echo ""
 	echo "Feature Toggles:"
 	echo "  aidevops config list         # List all toggles with current values"
 	echo "  aidevops config get <key>    # Get a toggle value"
@@ -1500,6 +1506,7 @@ main() {
 		esac
 		;;
 	client-format) _cmd_client_format "$@" ;;
+	github-app-auth | github-app | gh-auth) _dispatch_helper "github-app-auth-helper.sh" "github-app-auth-helper.sh" "$@" ;;
 	opencode-db | oc-db) _dispatch_helper "opencode-db-maintenance-helper.sh" "opencode-db-maintenance-helper.sh" "$@" ;;
 	opencode-sandbox | oc-sandbox) _dispatch_helper "opencode-sandbox-helper.sh" "opencode-sandbox-helper.sh" "$@" ;;
 	review-gate | review_gate) _dispatch_helper "review-gate-config-helper.sh" "review-gate-config-helper.sh" "$@" ;;

package/package.json

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

package/setup-modules/agent-deploy.sh

@@ -355,6 +355,9 @@ _restore_latest_agents_backup() {
 	local target_dir="$1"
 	local backup_base="$HOME/.aidevops/agents-backups"
 	local latest_backup=""
+	local parent_dir=""
+	local restore_staging=""
+	local old_dir=""
 
 	if [[ ! -d "$backup_base" ]]; then
 		print_warning "No agents backup directory found for restore: $backup_base"
@@ -368,14 +371,44 @@ _restore_latest_agents_backup() {
 	fi
 
 	print_warning "Restoring agents from latest backup: $latest_backup"
-	rm -rf "$target_dir"
-	mkdir -p "$(dirname "$target_dir")"
-	if cp -a "$latest_backup" "$target_dir"; then
+	parent_dir=$(dirname "$target_dir")
+	mkdir -p "$parent_dir"
+	restore_staging=$(mktemp -d "${target_dir}.restore.XXXXXX") || {
+		print_error "Failed to create agents restore staging directory"
+		return 1
+	}
+	old_dir="${target_dir}.restore-old.$$"
+	rm -rf "$old_dir"
+
+	if ! cp -a "$latest_backup/." "$restore_staging/"; then
+		print_error "Failed to stage agents backup for restore: $latest_backup"
+		rm -rf "$restore_staging"
+		return 1
+	fi
+
+	if [[ -d "$target_dir" ]]; then
+		if ! mv "$target_dir" "$old_dir"; then
+			print_error "Failed to move current agents directory aside during restore — agents directory preserved"
+			rm -rf "$restore_staging"
+			return 1
+		fi
+	fi
+
+	if mv "$restore_staging" "$target_dir"; then
+		rm -rf "$old_dir"
 		print_success "Restored agents directory from backup"
 		return 0
 	fi
 
-	print_error "Failed to restore agents directory from backup: $latest_backup"
+	print_error "Failed to move staged agents backup into place — attempting restore rollback"
+	if [[ -d "$old_dir" ]]; then
+		if mv "$old_dir" "$target_dir"; then
+			print_info "Restore rollback successful — previous agents directory restored"
+		else
+			print_error "Restore rollback failed — previous agents directory preserved in $old_dir"
+		fi
+	fi
+	rm -rf "$restore_staging"
 	return 1
 }
 

package/setup.sh

@@ -12,7 +12,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.13.93
+# Version: 3.13.94
 #
 # Quick Install:
 #   npm install -g aidevops && aidevops update          (recommended)
@@ -88,6 +88,10 @@ if [[ -d "$SETUP_MODULES_DIR" ]]; then
 	# shellcheck disable=SC1091
 	source "$SETUP_MODULES_DIR/_routines.sh"
 	# shellcheck disable=SC1091
+	source "$SETUP_MODULES_DIR/_scheduler_runtime.sh"
+	# shellcheck disable=SC1091
+	source "$SETUP_MODULES_DIR/_runtime_helpers.sh"
+	# shellcheck disable=SC1091
 	source "$SETUP_MODULES_DIR/_privacy_guard.sh"
 	# shellcheck disable=SC1091
 	source "$SETUP_MODULES_DIR/_complexity_guard.sh"
@@ -195,625 +199,11 @@ _resolve_main_worktree_dir() {
 	return 0
 }
 
-# Ensure the crontab has a single PATH= line at the top with the current $PATH.
-# Individual cron entries must NOT set inline PATH= — it overrides the global one
-# and hardcodes system-specific paths (nvm, bun, cargo, etc.). This function
-# manages a tagged comment + PATH line pair; re-running setup.sh updates it
-# idempotently. The marker must be a separate comment line because crontab does
-# NOT support inline comments on environment variable lines — anything after
-# PATH= is treated as part of the value.
-_ensure_cron_path() {
-	local current_crontab marker="# aidevops-path"
-	current_crontab=$(crontab -l 2>/dev/null) || current_crontab=""
-
-	# Deduplicate PATH entries (preserving order)
-	# Bash 3.2 compat: no associative arrays — use string-based seen list
-	local deduped_path=""
-	local seen_dirs=" "
-	local IFS=':'
-	for dir in $PATH; do
-		if [[ -n "$dir" && "$seen_dirs" != *" ${dir} "* ]]; then
-			seen_dirs="${seen_dirs}${dir} "
-			deduped_path="${deduped_path:+${deduped_path}:}${dir}"
-		fi
-	done
-	unset IFS
-
-	# Marker on its own line, PATH on the next — crontab treats everything
-	# after PATH= as the value (no inline comments)
-	local path_block="${marker}
-PATH=${deduped_path}"
-
-	# Remove only the aidevops-managed marker + PATH pair.
-	# User-owned PATH= lines are left untouched.
-	local filtered
-	filtered=$(printf '%s\n' "$current_crontab" | awk -v marker="$marker" '
-		$0 == marker { drop_next_path=1; next }
-		drop_next_path && /^PATH=/ { drop_next_path=0; next }
-		{ drop_next_path=0; print }
-	')
-
-	if [[ -n "$filtered" ]]; then
-		current_crontab="${path_block}
-${filtered}"
-	else
-		current_crontab="$path_block"
-	fi
-
-	printf '%s\n' "$current_crontab" | crontab - 2>/dev/null || true
-	return 0
-}
-
-# Check if a launchd agent is loaded (SIGPIPE-safe for pipefail, t1265)
-_launchd_has_agent() {
-	local label="$1"
-	local output
-	output=$(launchctl list 2>/dev/null) || true
-	echo "$output" | grep -qF "$label"
-	return $?
-}
-
-_launchd_agent_state() {
-	local label="$1"
-	local state=""
-	state=$(launchctl print "gui/$(id -u)/${label}" 2>/dev/null | awk -F'= ' '/state =/ { print $2; exit }' || true)
-	printf '%s\n' "$state"
-	return 0
-}
-
-_launchd_bootout_bootstrap() {
-	local label="$1"
-	local plist_path="$2"
-	local domain
-	domain="gui/$(id -u)"
-
-	launchctl bootout "${domain}/${label}" 2>/dev/null || true
-	launchctl bootstrap "$domain" "$plist_path" 2>/dev/null
-	return $?
-}
-
-_launchd_recover_xpcproxy_if_stuck() {
-	local label="$1"
-	local plist_path="$2"
-	local state
-	state=$(_launchd_agent_state "$label")
-	if [[ "$state" != "xpcproxy" ]]; then
-		return 0
-	fi
-
-	print_warning "LaunchAgent $label stuck in xpcproxy; reloading with bootout/bootstrap"
-	if ! _launchd_bootout_bootstrap "$label" "$plist_path"; then
-		return 1
-	fi
-
-	state=$(_launchd_agent_state "$label")
-	if [[ "$state" == "xpcproxy" ]]; then
-		print_warning "LaunchAgent $label still stuck in xpcproxy after recovery"
-		return 1
-	fi
-	return 0
-}
-
-_launchd_load_agent() {
-	local label="$1"
-	local plist_path="$2"
-
-	if launchctl load "$plist_path" 2>/dev/null; then
-		_launchd_recover_xpcproxy_if_stuck "$label" "$plist_path" || return 1
-		return 0
-	fi
-
-	if _launchd_bootout_bootstrap "$label" "$plist_path"; then
-		_launchd_recover_xpcproxy_if_stuck "$label" "$plist_path" || return 1
-		return 0
-	fi
-	return 1
-}
-
-_launchd_kickstart_and_recover() {
-	local label="$1"
-	local plist_path="$2"
-	local domain
-	domain="gui/$(id -u)"
-
-	launchctl kickstart -k "${domain}/${label}" 2>/dev/null || return 1
-	_launchd_recover_xpcproxy_if_stuck "$label" "$plist_path"
-	return $?
-}
-
-# Install a launchd plist only if its content has changed.
-# Avoids unnecessary unload/reload which resets StartInterval timers.
-# Usage: _launchd_install_if_changed <label> <plist_path> <new_content>
-# Returns: 0 = installed or unchanged, 1 = failed to load
-_launchd_install_if_changed() {
-	local label="$1"
-	local plist_path="$2"
-	local new_content="$3"
-
-	# Compare with existing plist — skip reload if identical
-	if [[ -f "$plist_path" ]]; then
-		local existing_content
-		existing_content=$(cat "$plist_path")
-		if [[ "$existing_content" == "$new_content" ]]; then
-			# Ensure it's loaded even if content unchanged
-			if ! _launchd_has_agent "$label"; then
-				_launchd_load_agent "$label" "$plist_path" || return 1
-			else
-				_launchd_recover_xpcproxy_if_stuck "$label" "$plist_path" || return 1
-			fi
-			return 0
-		fi
-		# Content changed — unload before replacing
-		if _launchd_has_agent "$label"; then
-			launchctl unload "$plist_path" 2>/dev/null || true
-		fi
-	fi
-
-	# Atomic write: build at sibling tmp path, then rename into place.
-	# If printf is killed mid-write, the destination is untouched.
-	# mktemp avoids predictable tmp names (defense-in-depth against symlink attacks).
-	local tmp_plist
-	tmp_plist=$(mktemp "${plist_path}.XXXXXX") || return 1
-	# Guard: refuse to write empty content — catching this before the write avoids
-	# creating a tmp file that the file-size check would also catch, but the
-	# content check is more direct and gives a clearer failure point.
-	if [[ -z "$new_content" ]]; then
-		rm -f "$tmp_plist"
-		return 1
-	fi
-	if ! printf '%s\n' "$new_content" >"$tmp_plist"; then
-		rm -f "$tmp_plist"
-		return 1
-	fi
-	# Defensive: refuse to install an empty file (should be guaranteed by the
-	# caller's content check, but guard here too).
-	if [[ ! -s "$tmp_plist" ]]; then
-		rm -f "$tmp_plist"
-		return 1
-	fi
-	if ! mv -f "$tmp_plist" "$plist_path"; then
-		rm -f "$tmp_plist"
-		return 1
-	fi
-	_launchd_load_agent "$label" "$plist_path" || return 1
-	return 0
-}
-
-# Detect whether a scheduler is already installed via launchd, cron, or systemd.
-# Optionally migrates legacy launchd labels / cron entries to launchd on macOS.
-# Args: arg1=scheduler_name, arg2=launchd_label, arg3=legacy_launchd_label,
-#       arg4=cron_marker, arg5=migrate_script, arg6=migrate_arg, arg7=migrate_hint
-#       arg8=systemd_unit (optional — base name without .timer suffix, e.g. "aidevops-supervisor-pulse")
-_scheduler_detect_installed() {
-	local scheduler_name="$1"
-	local launchd_label="$2"
-	local legacy_launchd_label="$3"
-	local cron_marker="$4"
-	local migrate_script="$5"
-	local migrate_arg="$6"
-	local migrate_hint="$7"
-	local systemd_unit="${8:-}"
-	local installed=false
-
-	if _launchd_has_agent "$launchd_label"; then
-		installed=true
-	elif [[ -n "$legacy_launchd_label" ]] && _launchd_has_agent "$legacy_launchd_label"; then
-		if [[ -n "$migrate_script" ]] && [[ -x "$migrate_script" ]]; then
-			if bash "$migrate_script" "$migrate_arg" >/dev/null 2>&1; then
-				print_info "$scheduler_name LaunchAgent migrated to new label"
-			else
-				print_warning "$scheduler_name label migration failed. Run: $migrate_hint"
-			fi
-		fi
-		installed=true
-	elif crontab -l 2>/dev/null | grep -qF "$cron_marker"; then
-		if [[ "$PLATFORM_MACOS" == "true" ]] && [[ -n "$migrate_script" ]] && [[ -x "$migrate_script" ]]; then
-			if bash "$migrate_script" "$migrate_arg" >/dev/null 2>&1; then
-				print_info "$scheduler_name migrated from cron to launchd"
-			else
-				print_warning "$scheduler_name cron->launchd migration failed. Run: $migrate_hint"
-			fi
-		fi
-		installed=true
-	elif [[ -n "$systemd_unit" ]] && command -v systemctl >/dev/null 2>&1 &&
-		systemctl --user is-enabled "${systemd_unit}.timer" >/dev/null 2>&1; then
-		# Systemd user timer detected (GH#17381 — Linux systemd path was missing)
-		installed=true
-	fi
-
-	if [[ "$installed" == "true" ]]; then
-		return 0
-	fi
-
-	return 1
-}
-
-_should_setup_noninteractive_supervisor_pulse() {
-	local pulse_label="com.aidevops.aidevops-supervisor-pulse"
-
-	if _scheduler_detect_installed \
-		"Supervisor pulse" \
-		"$pulse_label" \
-		"" \
-		"pulse-wrapper" \
-		"" \
-		"" \
-		"" \
-		"aidevops-supervisor-pulse"; then
-		return 0
-	fi
-
-	if type config_enabled &>/dev/null && config_enabled "orchestration.supervisor_pulse"; then
-		return 0
-	fi
-
-	return 1
-}
-
-# Generic non-interactive scheduler detection (GH#17695 Finding B).
-# Returns 0 if the named scheduler is already installed on any backend,
-# meaning it should be regenerated during non-interactive setup.
-# Args: arg1=name arg2=launchd_label arg3=cron_marker arg4=systemd_unit
-_should_setup_noninteractive_scheduler() {
-	local name="$1"
-	local launchd_label="$2"
-	local cron_marker="$3"
-	local systemd_unit="${4:-}"
-
-	if _scheduler_detect_installed \
-		"$name" \
-		"$launchd_label" \
-		"" \
-		"$cron_marker" \
-		"" \
-		"" \
-		"" \
-		"$systemd_unit"; then
-		return 0
-	fi
-
-	return 1
-}
-
-# Stats-wrapper is a REQUIRED dependency of the supervisor pulse — the pulse
-# delegates all health dashboard + quality sweep work to it (t1429). If the
-# supervisor pulse is installed or consented, stats-wrapper must also be
-# installed, even on first-time non-interactive runs. Without this escape
-# hatch, auto-update on a fresh machine installs the pulse but not the
-# stats-wrapper, leaving the health dashboard permanently stale (t2418,
-# GH#20016 — canonical 11-day staleness on #10944 on 2026-04-20).
-_should_setup_noninteractive_stats_wrapper() {
-	if _should_setup_noninteractive_scheduler \
-		"Stats wrapper" \
-		"com.aidevops.aidevops-stats-wrapper" \
-		"aidevops: stats-wrapper" \
-		"aidevops-stats-wrapper"; then
-		return 0
-	fi
-
-	# Pulse-dependency escape hatch: install stats-wrapper whenever the
-	# supervisor pulse is (or will be) enabled. Pulse itself also honours
-	# config consent in the non-interactive path, so following its gate
-	# keeps the two schedulers in lockstep.
-	if _should_setup_noninteractive_supervisor_pulse; then
-		return 0
-	fi
-
-	return 1
-}
-
-# Pulse-merge-routine is a REQUIRED dependency of the supervisor pulse — it
-# is the merge-side of pulse, running merge_ready_prs_all_repos() on a fast
-# 120s cadence so green PRs land within ~3 min of CI completion instead of
-# waiting for the next full pulse cycle (t2862, GH#20919). Without this
-# escape hatch, auto-update on existing systems never installs the routine
-# (the generic _should_setup_noninteractive_scheduler chicken-and-egg gate
-# returns 0 only when the scheduler is ALREADY installed). The result on
-# the wild was the deterministic_merge_pass running 1-2x/24h instead of
-# every 2 min, leaving green PRs unmerged for 30+ hours (t3036, GH#21616).
-# Mirrors the stats-wrapper escape hatch above (t2418, GH#20016).
-_should_setup_noninteractive_pulse_merge_routine() {
-	if _should_setup_noninteractive_scheduler \
-		"Pulse merge routine" \
-		"sh.aidevops.pulse-merge-routine" \
-		"aidevops: pulse-merge-routine" \
-		"aidevops-pulse-merge-routine"; then
-		return 0
-	fi
+# Scheduler runtime helpers are sourced from .agents/scripts/setup/_scheduler_runtime.sh
+# with the rest of the setup modules near the top of this file.
 
-	# Pulse-dependency escape hatch: install the merge routine whenever the
-	# supervisor pulse is (or will be) enabled. The routine is layered
-	# defense for the in-cycle merge call in pulse-wrapper.sh, which is
-	# kept as a safety net but short-circuits when this routine ran within
-	# the last 60s.
-	if _should_setup_noninteractive_supervisor_pulse; then
-		return 0
-	fi
-
-	return 1
-}
-
-# Spinner for long-running operations
-# Usage: run_with_spinner "Installing package..." command arg1 arg2
-run_with_spinner() {
-	local message="$1"
-	shift
-	local pid
-	local spin_chars='⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏'
-	local i=0
-
-	# Suppress Homebrew's slow auto-update for all backgrounded brew commands.
-	# run_with_spinner backgrounds via "$@" &, so env var prefix syntax
-	# (VAR=x cmd) doesn't propagate. Export globally for the child process.
-	local _brew_was_set="${HOMEBREW_NO_AUTO_UPDATE:-}"
-	local _cmd="${1:-}"
-	local _subcmd="${2:-}"
-	if [[ "$_cmd" == "brew" && "$_subcmd" != "update" ]]; then
-		export HOMEBREW_NO_AUTO_UPDATE=1
-	fi
-
-	# Start command in background
-	"$@" &>/dev/null &
-	pid=$!
-
-	# Show spinner while command runs
-	printf "${BLUE}[INFO]${NC} %s " "$message"
-	while kill -0 "$pid" 2>/dev/null; do
-		printf "\r${BLUE}[INFO]${NC} %s %s" "$message" "${spin_chars:i++%${#spin_chars}:1}"
-		sleep 0.1
-	done
-
-	# Check exit status
-	wait "$pid"
-	local exit_code=$?
-
-	# Restore HOMEBREW_NO_AUTO_UPDATE to previous state
-	if [[ -z "$_brew_was_set" ]]; then
-		unset HOMEBREW_NO_AUTO_UPDATE
-	fi
-
-	# Clear spinner and show result
-	printf "\r"
-	if [[ $exit_code -eq 0 ]]; then
-		print_success "$message done"
-	else
-		print_error "$message failed"
-	fi
-
-	return $exit_code
-}
-
-# Verified install: download script to temp file, inspect, then execute
-# Replaces unsafe curl|sh patterns with download-verify-execute
-# Usage: verified_install "description" "url" [extra_args...]
-# Options (set before calling):
-#   VERIFIED_INSTALL_SUDO="true"  - run with sudo
-#   VERIFIED_INSTALL_SHELL="sh"  - use sh instead of bash (default: bash)
-# Returns: 0 on success, 1 on failure
-verified_install() {
-	local description="$1"
-	local url="$2"
-	shift 2
-	local extra_args=("$@")
-	local shell="${VERIFIED_INSTALL_SHELL:-bash}"
-	local use_sudo="${VERIFIED_INSTALL_SUDO:-false}"
-
-	# Reset options for next call
-	VERIFIED_INSTALL_SUDO="false"
-	VERIFIED_INSTALL_SHELL="bash"
-
-	# Create secure temp file
-	local tmp_script
-	# t2997: drop .sh — XXXXXX must be at end for BSD mktemp.
-	tmp_script=$(mktemp "${TMPDIR:-/tmp}/aidevops-install-XXXXXX") || {
-		print_error "Failed to create temp file for $description"
-		return 1
-	}
-
-	# Ensure cleanup on exit from this function
-	# shellcheck disable=SC2064
-	trap "rm -f '$tmp_script'" RETURN
-
-	# Download script to file (not piped to shell)
-	print_info "Downloading $description install script..."
-	if ! curl -fsSL "$url" -o "$tmp_script" 2>/dev/null; then
-		print_error "Failed to download $description install script from $url"
-		return 1
-	fi
-
-	# Verify download is non-empty and looks like a script
-	if [[ ! -s "$tmp_script" ]]; then
-		print_error "Downloaded $description script is empty"
-		return 1
-	fi
-
-	# Basic content safety check: reject binary content
-	if file "$tmp_script" 2>/dev/null | grep -qv 'text'; then
-		print_error "Downloaded $description script appears to be binary, not a shell script"
-		return 1
-	fi
-
-	# Make executable
-	chmod +x "$tmp_script"
-
-	# Execute from file
-	# Build cmd array once; prepend sudo conditionally to avoid duplicating the safe expansion
-	# Use ${extra_args[@]+"${extra_args[@]}"} for safe expansion under set -u when array is empty
-	local cmd=()
-	[[ "$use_sudo" == "true" ]] && cmd+=(sudo)
-	cmd+=("$shell" "$tmp_script" ${extra_args[@]+"${extra_args[@]}"})
-
-	if "${cmd[@]}"; then
-		print_success "$description installed"
-		return 0
-	else
-		print_error "$description installation failed"
-		return 1
-	fi
-}
-
-# Find OpenCode config file (checks multiple possible locations)
-# Returns: path to config file, or empty string if not found
-find_opencode_config() {
-	local candidates=(
-		"$HOME/.config/opencode/opencode.json"                     # XDG standard (Linux, some macOS)
-		"$HOME/.opencode/opencode.json"                            # Alternative location
-		"$HOME/Library/Application Support/opencode/opencode.json" # macOS standard
-	)
-	for candidate in "${candidates[@]}"; do
-		if [[ -f "$candidate" ]]; then
-			echo "$candidate"
-			return 0
-		fi
-	done
-	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"
-# On Linux with apt-installed npm, automatically prepends sudo.
-# Returns: 0 on success, 1 on failure
-npm_global_install() {
-	local pkg="$1"
-
-	if command -v npm >/dev/null 2>&1; then
-		# npm global installs need sudo on Linux when prefix dir isn't writable
-		if [[ "$(uname)" != "Darwin" ]] && [[ ! -w "$(npm config get prefix 2>/dev/null)/lib" ]]; then
-			sudo npm install -g "$pkg"
-		else
-			npm install -g "$pkg"
-		fi
-		return $?
-	else
-		return 1
-	fi
-}
-
-# Prompt the user for input, with non-interactive fallback.
-# Canonical definition in .agents/scripts/setup/_common.sh; this fallback
-# ensures the function exists even when _common.sh was not sourced (e.g.
-# bootstrap from curl where setup-modules/ doesn't exist yet).
-if ! type setup_prompt &>/dev/null; then
-	setup_prompt() {
-		local var_name="$1"
-		local prompt_text="$2"
-		local default_value="${3:-}"
-
-		# Non-interactive: use default without prompting
-		if [[ "${NON_INTERACTIVE:-false}" == "true" ]] || [[ ! -t 0 ]]; then
-			# shellcheck disable=SC2059  # var_name is a variable name, not a format string
-			printf -v "$var_name" '%s' "$default_value"
-			return 0
-		fi
-
-		local _setup_prompt_reply=""
-		read -r -p "$prompt_text" _setup_prompt_reply || _setup_prompt_reply="$default_value"
-		# shellcheck disable=SC2059  # var_name is a variable name, not a format string
-		printf -v "$var_name" '%s' "$_setup_prompt_reply"
-		return 0
-	}
-fi
-
-# Confirm step in interactive mode
-# Usage: confirm_step "Step description" && function_to_run
-# Returns: 0 if confirmed or not interactive, 1 if skipped
-confirm_step() {
-	local step_name="$1"
-
-	# Skip confirmation in non-interactive mode
-	if [[ "$INTERACTIVE_MODE" != "true" ]]; then
-		return 0
-	fi
-
-	echo ""
-	echo -e "${YELLOW}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
-	echo -e "${BLUE}Step:${NC} $step_name"
-	echo -e "${YELLOW}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
-
-	while true; do
-		echo -n -e "${GREEN}Run this step? [Y]es / [n]o / [q]uit: ${NC}"
-		read -r response
-		# Convert to lowercase (bash 3.2 compatible)
-		response=$(echo "$response" | tr '[:upper:]' '[:lower:]')
-		case "$response" in
-		y | yes | "")
-			return 0
-			;;
-		n | no | s | skip)
-			print_warning "Skipped: $step_name"
-			return 1
-			;;
-		q | quit | exit)
-			echo ""
-			print_info "Setup cancelled by user"
-			exit 0
-			;;
-		*)
-			echo "Please answer: y (yes), n (no), or q (quit)"
-			;;
-		esac
-	done
-}
-
-# Backup rotation settings
-BACKUP_KEEP_COUNT=10
-
-# Create a backup with rotation (keeps last N backups)
-# Usage: create_backup_with_rotation <source_path> <backup_name>
-# Example: create_backup_with_rotation "$target_dir" "agents"
-# Creates: ~/.aidevops/agents-backups/20251221_123456/
-create_backup_with_rotation() {
-	local source_path="$1"
-	local backup_name="$2"
-	local backup_base="$HOME/.aidevops/${backup_name}-backups"
-	local backup_dir
-	backup_dir="$backup_base/$(date +%Y%m%d_%H%M%S)"
-
-	# Create backup directory
-	mkdir -p "$backup_dir"
-
-	# Copy source to backup (tolerant of broken symlinks / missing entries)
-	if [[ -d "$source_path" ]]; then
-		if command -v rsync >/dev/null 2>&1 && rsync --help 2>&1 | grep -q -- '--ignore-missing-args'; then
-			# rsync >= 3.1.0: --ignore-missing-args skips missing/broken entries gracefully
-			if ! rsync -a --ignore-missing-args "$source_path/" "$backup_dir/$(basename "$source_path")/" 2>/dev/null; then
-				print_warning "Backup had partial failures (broken symlinks?), continuing"
-			fi
-		else
-			# Fallback: cp -R may fail on broken symlinks under set -e,
-			# so run in a subshell that tolerates errors
-			if ! (cp -R "$source_path" "$backup_dir/" 2>/dev/null); then
-				print_warning "Backup had partial failures (broken symlinks?), continuing"
-			fi
-		fi
-	elif [[ -f "$source_path" ]]; then
-		cp "$source_path" "$backup_dir/"
-	else
-		print_warning "Source path does not exist: $source_path"
-		return 1
-	fi
-
-	print_info "Backed up to $backup_dir"
-
-	# Rotate old backups (keep last N)
-	local backup_count
-	backup_count=$(find "$backup_base" -maxdepth 1 -type d -name "20*" 2>/dev/null | wc -l | tr -d ' ')
-
-	if [[ $backup_count -gt $BACKUP_KEEP_COUNT ]]; then
-		local to_delete=$((backup_count - BACKUP_KEEP_COUNT))
-		print_info "Rotating backups: removing $to_delete old backup(s), keeping last $BACKUP_KEEP_COUNT"
-
-		# Delete oldest backups (sorted by name = sorted by date)
-		find "$backup_base" -maxdepth 1 -type d -name "20*" 2>/dev/null | sort | head -n "$to_delete" | while read -r old_backup; do
-			rm -rf "$old_backup"
-		done
-	fi
-
-	return 0
-}
+# Runtime helper functions are sourced from .agents/scripts/setup/_runtime_helpers.sh
+# with the rest of the setup modules near the top of this file.
 
 # Validate namespace string for safe use in paths and shell commands
 # Returns 0 if valid, 1 if invalid