aidevops 3.13.0 → 3.13.1

package/README.md

@@ -238,6 +238,23 @@ This creates:
 
 **Available features:** `planning`, `git-workflow`, `code-quality`, `time-tracking`, `beads`
 
+### Per-repo platform setup
+
+After `aidevops init` registers a new repo, run `/setup-git` in your AI assistant
+to apply per-repo platform secrets. Most notably, this sets `SYNC_PAT` — a
+GitHub Actions secret that lets `issue-sync.yml` push TODO.md auto-completion
+past branch protection.
+
+This is distinct from `/onboarding` (per-account credentials like `gh auth login`):
+GitHub Actions secrets are scoped per-repo, so each repo needs its own. You need
+`gh auth login` to succeed before any per-repo helper can run, so `/onboarding`
+comes first, `/setup-git` second.
+
+Run `/setup-git` again whenever you register a new repo with `aidevops repos add`
+or when a `SYNC_PAT` advisory appears in the session greeting toast. If you skip
+this step, `issue-sync.yml` will post a remediation comment when it hits branch
+protection — `/setup-git` walks through the fix.
+
 ### Upgrade Planning Files
 
 When aidevops templates evolve, upgrade existing projects to the latest format:

package/VERSION

@@ -1 +1 @@
-3.13.0
+3.13.1

package/aidevops.sh

@@ -5,7 +5,7 @@
 # AI DevOps Framework CLI
 # Usage: aidevops <command> [options]
 #
-# Version: 3.13.0
+# Version: 3.13.1
 
 set -euo pipefail
 
@@ -557,6 +557,71 @@ _update_verify_signature() {
 	return 0
 }
 
+# One-shot, idempotent migration of supervisor.* → orchestration.* in settings.json (t2946).
+# Safe: reads value from supervisor.* only when orchestration.* key is absent.
+# Logs to ~/.aidevops/logs/settings-migration.log.
+_migrate_settings_supervisor_to_orchestration() {
+	local _settings_file="${HOME}/.config/aidevops/settings.json"
+	local _log_file="${HOME}/.aidevops/logs/settings-migration.log"
+
+	if ! command -v jq >/dev/null 2>&1; then
+		return 0
+	fi
+	if [[ ! -f "$_settings_file" ]]; then
+		return 0
+	fi
+	if ! jq . "$_settings_file" >/dev/null 2>&1; then
+		return 0
+	fi
+
+	# Check if supervisor.pulse_interval_seconds exists and orchestration.pulse_interval_seconds is absent.
+	local _has_sv _has_orch
+	_has_sv=$(jq -r 'if .supervisor.pulse_interval_seconds != null then "yes" else "no" end' "$_settings_file" 2>/dev/null)
+	_has_orch=$(jq -r 'if .orchestration.pulse_interval_seconds != null then "yes" else "no" end' "$_settings_file" 2>/dev/null)
+
+	if [[ "$_has_sv" != "yes" ]]; then
+		return 0
+	fi
+
+	local _ts
+	_ts=$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date +%Y-%m-%dT%H:%M:%SZ)
+	mkdir -p "$(dirname "$_log_file")" 2>/dev/null || true
+
+	local _tmp
+	_tmp=$(mktemp 2>/dev/null) || return 0
+
+	if [[ "$_has_orch" == "no" ]]; then
+		# Migrate: copy supervisor.pulse_interval_seconds to orchestration.pulse_interval_seconds,
+		# then remove supervisor.pulse_interval_seconds.
+		local _sv_val
+		_sv_val=$(jq -r '.supervisor.pulse_interval_seconds' "$_settings_file" 2>/dev/null)
+		if jq --argjson v "$_sv_val" \
+			'(.orchestration.pulse_interval_seconds) = $v | del(.supervisor.pulse_interval_seconds)' \
+			"$_settings_file" >"$_tmp" 2>/dev/null && [[ -s "$_tmp" ]]; then
+			mv "$_tmp" "$_settings_file"
+			printf '[%s] migrated supervisor.pulse_interval_seconds=%s → orchestration.pulse_interval_seconds\n' \
+				"$_ts" "$_sv_val" >>"$_log_file" 2>/dev/null || true
+			print_info "Settings migrated: supervisor.pulse_interval_seconds → orchestration.pulse_interval_seconds ($_sv_val)"
+		else
+			rm -f "$_tmp"
+		fi
+	else
+		# Both present: orchestration wins, remove the stale supervisor key.
+		local _orch_val
+		_orch_val=$(jq -r '.orchestration.pulse_interval_seconds' "$_settings_file" 2>/dev/null)
+		if jq 'del(.supervisor.pulse_interval_seconds)' \
+			"$_settings_file" >"$_tmp" 2>/dev/null && [[ -s "$_tmp" ]]; then
+			mv "$_tmp" "$_settings_file"
+			printf '[%s] removed stale supervisor.pulse_interval_seconds (orchestration.pulse_interval_seconds=%s wins)\n' \
+				"$_ts" "$_orch_val" >>"$_log_file" 2>/dev/null || true
+			print_info "Settings cleaned: removed stale supervisor.pulse_interval_seconds (orchestration value $_orch_val kept)"
+		else
+			rm -f "$_tmp"
+		fi
+	fi
+	return 0
+}
+
 # Update/upgrade command
 cmd_update() {
 	local skip_project_sync=false
@@ -693,6 +758,12 @@ cmd_update() {
 		_update_check_daemon_health
 	fi
 
+	# t2946: one-shot idempotent migration from legacy supervisor.* to canonical
+	# orchestration.* namespace in settings.json. Safe: no-op when orchestration.*
+	# is already set. Runs even on "already up to date" updates so users who
+	# install the fix without a new release still get migrated on next 'aidevops update'.
+	_migrate_settings_supervisor_to_orchestration
+
 	# t2914: ensure pulse is running after every update. The existing
 	# restart paths (setup.sh:1329, agent-deploy.sh:601) call
 	# pulse-lifecycle-helper.sh restart-if-running which is a silent no-op
@@ -708,7 +779,7 @@ cmd_update() {
 	# 'restart-if-running' do). Non-fatal: a pulse start failure should
 	# not fail the update.
 	if [[ "${AIDEVOPS_SKIP_PULSE_RESTART:-0}" != "1" ]]; then
-		local _pulse_helper="${HOME}/.aidevops/agents/scripts/pulse-lifecycle-helper.sh"
+		local _pulse_helper="${AGENTS_DIR}/scripts/pulse-lifecycle-helper.sh"
 		if [[ -x "$_pulse_helper" ]]; then
 			"$_pulse_helper" start >/dev/null 2>&1 || print_warning "Pulse start failed (non-fatal)"
 		fi
@@ -1496,6 +1567,7 @@ _help_commands() {
 	echo "  client-format      Client request format alignment (extract/check/canary/monitor)"
 	echo "  opencode-sandbox   Test OpenCode versions in isolation (install/run/check/clean)"
 	echo "  approve <cmd>      Cryptographic issue/PR approval (setup/issue/pr/verify/status)"
+	echo "  issue <cmd>        Interactive issue ownership (claim/release/status/scan-stale)"
 	echo "  security [cmd]     Full security assessment (posture + hygiene + supply chain)"
 	echo "  contributions      External contributions inbox (bare: status | seed/scan/stop/restart/install/uninstall)"
 	echo "  inbox [cmd]        Capture transit zone (bare: status | provision/add/find/digest/help)"
@@ -1505,6 +1577,7 @@ _help_commands() {
 	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)"
+	echo "  campaign <cmd>     Campaign plane P6: launch + promote results/learnings"
 	echo "  stats <cmd>        LLM usage analytics (summary/models/projects/costs/trend)"
 	echo "  tabby <cmd>        Manage Tabby terminal profiles (sync/status/zshrc/help)"
 	echo "  parent-status <N>  Show decomposition state of parent-task issue #N (alias: ps)"
@@ -1590,6 +1663,15 @@ _help_detailed_sections() {
 	echo "  aidevops knowledge init off            # Disable knowledge plane"
 	echo "  aidevops knowledge status              # Show provisioning state"
 	echo "  aidevops knowledge provision [path]    # Re-provision (idempotent)"
+	echo "  aidevops knowledge add <file|url>      # Ingest file or URL into sources/"
+	echo "  aidevops knowledge list [--state s] [--kind k]  # List all known sources"
+	echo "  aidevops knowledge search <query>      # Search sources (grep fallback)"
+	echo ""
+	echo "Campaign Plane (P6 — performance integration + learnings promotion):"
+	echo "  aidevops campaign launch <id>            # Move active/<id> → launched/, create result/learning templates"
+	echo "  aidevops campaign promote <id> --results # Push metrics to _performance/marketing/<id>.md"
+	echo "  aidevops campaign promote <id> --learnings # Promote insights to _knowledge/insights/marketing/"
+	echo "  aidevops campaign feedback [<id>]        # Surface _feedback/ insights for campaign research"
 	echo ""
 	echo "LLM Stats:"
 	echo "  aidevops stats               # Show usage summary (last 30 days)"
@@ -1935,6 +2017,75 @@ main() {
 	pulse) _dispatch_helper "pulse-session-helper.sh" "pulse-session-helper.sh" "$@" ;;
 	check-workflows | workflows) _dispatch_helper "check-workflows-helper.sh" "check-workflows-helper.sh" "$@" ;;
 	sync-workflows) _dispatch_helper "sync-workflows-helper.sh" "sync-workflows-helper.sh" "$@" ;;
+	badges)
+		# Badge management: render | check | sync | install (t2975)
+		# Bare 'aidevops badges' with no subcommand shows a usage summary.
+		# Subcommands:
+		#   render <slug>               — render canonical badge block for a repo
+		#   check  [--repo SLUG] [--json] [--verbose]  — cross-repo drift check
+		#   sync   [--repo SLUG] [--apply]              — inject badge block + install workflow
+		#   install [--repo SLUG] [--apply]             — install loc-badge caller workflow only
+		local _badges_sub="${1:-help}"
+		local _badges_check_h="badges-check-helper.sh"
+		local _badges_sync_h="badges-sync-helper.sh"
+		case "$_badges_sub" in
+		render)
+			shift
+			local _render_helper
+			_render_helper=$(bash -c '
+				d="$HOME/.aidevops/agents/scripts/readme-badges-helper.sh"
+				l="'"$AGENTS_DIR"'/scripts/readme-badges-helper.sh"
+				[[ -f "$d" ]] && echo "$d" || echo "$l"
+			')
+			if [[ -f "$_render_helper" ]]; then
+				bash "$_render_helper" render "$@"
+			else
+				print_error "readme-badges-helper.sh not found. Run: aidevops update"
+				exit 1
+			fi
+			;;
+		check)
+			shift
+			_dispatch_helper "$_badges_check_h" "$_badges_check_h" "$@"
+			;;
+		sync)
+			shift
+			_dispatch_helper "$_badges_sync_h" "$_badges_sync_h" "$@"
+			;;
+		install)
+			shift
+			_dispatch_helper "$_badges_sync_h" "$_badges_sync_h" --workflow-only "$@"
+			;;
+		help | --help | -h | "")
+			echo ""
+			echo "aidevops badges — README badge block and LOC workflow management (t2975)"
+			echo ""
+			echo "Subcommands:"
+			echo "  render  <slug>                 Print canonical badge block for a repo"
+			echo "  check   [--repo SLUG] [--json]  Detect badge drift across managed repos"
+			echo "  sync    [--repo SLUG] [--apply] Inject badge block + install LOC workflow"
+			echo "  install [--repo SLUG] [--apply] Install loc-badge caller workflow only"
+			echo ""
+			echo "Options (check/sync/install):"
+			echo "  --repo SLUG    Limit to a single repo"
+			echo "  --apply        Actually perform the sync (default: dry-run)"
+			echo "  --json         Machine-readable output"
+			echo "  --verbose      Show diff summaries (check only)"
+			echo ""
+			echo "Examples:"
+			echo "  aidevops badges check                       # scan all repos for badge drift"
+			echo "  aidevops badges check --json | jq '.[]'    # machine-readable output"
+			echo "  aidevops badges render owner/repo           # print badge block"
+			echo "  aidevops badges sync                        # dry-run sync across all repos"
+			echo "  aidevops badges sync --repo owner/r --apply # apply to a single repo"
+			echo ""
+			;;
+		*)
+			print_error "Unknown badges subcommand: $_badges_sub (try render|check|sync|install|help)"
+			exit 1
+			;;
+		esac
+		;;
 	security) _cmd_security "$@" ;;
 	doctor | doc) _dispatch_helper "doctor-helper.sh" "doctor-helper.sh" "$@" ;;
 	detect | scan) cmd_detect ;;
@@ -1945,6 +2096,7 @@ main() {
 	review-gate | review_gate) _dispatch_helper "review-gate-config-helper.sh" "review-gate-config-helper.sh" "$@" ;;
 	secret | secrets) _dispatch_helper "secret-helper.sh" "secret-helper.sh" "$@" ;;
 	approve) _dispatch_helper "approval-helper.sh" "approval-helper.sh" "$@" ;;
+	issue) _dispatch_helper "interactive-session-helper.sh" "interactive-session-helper.sh" "$@" ;;
 	signing) _dispatch_helper "signing-setup.sh" "signing-setup.sh" "$@" ;;
 	contributions | contrib)
 		# Bare `aidevops contributions` defaults to status (most common use).
@@ -1960,7 +2112,13 @@ main() {
 	case | cases)
 		# Bare `aidevops case` defaults to list (most common use).
 		[[ $# -eq 0 ]] && set -- list
-		_dispatch_helper "case-helper.sh" "case-helper.sh" "$@"
+		# alarm-test subcommand routes to case-alarm-helper.sh
+		if [[ "${1:-}" == "alarm-test" ]]; then
+			shift
+			_dispatch_helper "case-alarm-helper.sh" "case-alarm-helper.sh" alarm-test "$@"
+		else
+			_dispatch_helper "case-helper.sh" "case-helper.sh" "$@"
+		fi
 		;;
 	email) _cmd_email "$@" ;;
 	stats | observability) _dispatch_helper "observability-helper.sh" "observability-helper.sh" "$@" ;;
@@ -1968,6 +2126,7 @@ main() {
 	init-routines) _dispatch_helper "init-routines-helper.sh" "init-routines-helper.sh" "$@" ;;
 	parent-status | ps) _dispatch_helper "parent-status-helper.sh" "parent-status-helper.sh" "$@" ;;
 	knowledge) _dispatch_helper "knowledge-helper.sh" "knowledge-helper.sh" "$@" ;;
+	campaign | campaigns) _dispatch_helper "campaign-helper.sh" "campaign-helper.sh" "$@" ;;
 	config | configure) _dispatch_config "$@" ;;
 	uninstall | remove) cmd_uninstall ;;
 	version | v | -v | --version) cmd_version ;;

package/package.json

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

package/setup-modules/schedulers-linux.sh

@@ -0,0 +1,386 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: 2025-2026 Marcus Quinn
+# =============================================================================
+# Schedulers Linux Sub-Library -- systemd/cron scheduler installation and
+# uninstall functions for Linux (and macOS uninstall path).
+# =============================================================================
+# This sub-library is sourced by setup-modules/schedulers.sh (the orchestrator).
+# It covers:
+#   - systemd user service availability check
+#   - systemd value escaping
+#   - Building systemd Environment= and cron env prefix lines
+#   - Generic systemd timer installation
+#   - Generic cron entry installation
+#   - Linux dispatcher (systemd preferred, cron fallback)
+#   - Generic scheduler uninstall (launchd/systemd/cron)
+#   - Supervisor pulse uninstall
+#
+# Usage: source "${SCRIPT_DIR}/schedulers-linux.sh"
+#
+# Dependencies:
+#   - shared-constants.sh (print_info, print_warning)
+#
+# Part of aidevops framework: https://aidevops.sh
+
+# Apply strict mode only when executed directly (not when sourced)
+[[ "${BASH_SOURCE[0]}" == "${0}" ]] && set -euo pipefail
+
+# Include guard
+[[ -n "${_SCHEDULERS_LINUX_LIB_LOADED:-}" ]] && return 0
+_SCHEDULERS_LINUX_LIB_LOADED=1
+
+# SCRIPT_DIR fallback — needed when sourced from test harnesses that don't set it.
+if [[ -z "${SCRIPT_DIR:-}" ]]; then
+	_sched_linux_lib_path="${BASH_SOURCE[0]%/*}"
+	[[ "$_sched_linux_lib_path" == "${BASH_SOURCE[0]}" ]] && _sched_linux_lib_path="."
+	SCRIPT_DIR="$(cd "$_sched_linux_lib_path" && pwd)"
+	unset _sched_linux_lib_path
+fi
+
+# --- Functions ---
+
+# Check if systemd user services are available on this Linux system.
+# Returns 0 if systemd --user is functional, 1 otherwise.
+_systemd_user_available() {
+	command -v systemctl >/dev/null 2>&1 || return 1
+	systemctl --user status >/dev/null 2>&1 || return 1
+	return 0
+}
+
+# Escape a value for safe embedding in a systemd unit Environment= or ExecStart=
+# directive. systemd interprets % as specifiers (%h, %n, %t, etc.) and spaces
+# as key-value separators. This helper:
+#   1. Escapes \ → \\ (must be first to avoid double-escaping)
+#   2. Doubles % → %% (escape specifiers)
+#   3. Escapes embedded " → \"
+#   4. Wraps the result in "..." (handles spaces and other shell metacharacters)
+# Usage: escaped=$(_systemd_escape "$value")
+#
+# WARNING: Do NOT use for StandardOutput= or StandardError= directives.
+# systemd does not strip outer quotes from those values — "append:/path" is
+# treated as a literal filename with quote characters, failing silently.
+# Use bare values for StandardOutput=/StandardError=:
+#   StandardOutput=append:${log_file}  ← correct
+#   StandardOutput=$(_systemd_escape "append:${log_file}")  ← WRONG
+_systemd_escape() {
+	local _val="$1"
+	# Step 1: escape backslashes
+	_val="${_val//\\/\\\\}"
+	# Step 2: escape % specifiers
+	_val="${_val//%/%%}"
+	# Step 3: escape embedded double-quotes
+	_val="${_val//\"/\\\"}"
+	# Step 4: wrap in double-quotes
+	printf '"%s"' "$_val"
+	return 0
+}
+
+# Build systemd Environment= lines from newline-separated KEY=VALUE pairs.
+# Always appends HOME and PATH for parity with launchd and cron execution.
+_scheduler_systemd_env_lines() {
+	local env_vars="$1"
+	local _env_lines=""
+
+	if [[ -n "$env_vars" ]]; then
+		while IFS= read -r _kv; do
+			[[ -z "$_kv" ]] && continue
+			local _key="${_kv%%=*}"
+			local _raw_val="${_kv#*=}"
+			local _escaped_val
+			_escaped_val=$(_systemd_escape "$_raw_val")
+			_env_lines+="Environment=${_key}=${_escaped_val}"$'\n'
+		done <<<"$env_vars"
+	fi
+
+	_env_lines+="Environment=HOME=$(_systemd_escape "$HOME")"$'\n'
+	_env_lines+="Environment=PATH=$(_systemd_escape "$PATH")"$'\n'
+	printf '%s' "$_env_lines"
+	return 0
+}
+
+# Build inline cron environment assignments from newline-separated KEY=VALUE pairs.
+_scheduler_cron_env_prefix() {
+	local env_vars="$1"
+	local _env_prefix=""
+
+	if [[ -n "$env_vars" ]]; then
+		while IFS= read -r _kv; do
+			[[ -z "$_kv" ]] && continue
+			local _key="${_kv%%=*}"
+			local _raw_val="${_kv#*=}"
+			local _escaped_val
+			_escaped_val=$(_cron_escape "$_raw_val")
+			_env_prefix+="${_key}=${_escaped_val} "
+		done <<<"$env_vars"
+	fi
+
+	printf '%s' "$_env_prefix"
+	return 0
+}
+
+# Install a generic scheduler via systemd user timer (Linux with systemd).
+# Args:
+#   $1 = service_name    (e.g. "aidevops-stats-wrapper")
+#   $2 = exec_command    (shell command run via /bin/bash -lc)
+#   $3 = interval_sec    (OnUnitActiveSec interval in seconds; may be empty for calendar-only)
+#   $4 = log_file        (absolute path to log file)
+#   $5 = env_vars        (newline-separated KEY=VALUE pairs, may be empty)
+#   $6 = run_at_load     ("true" or "false")
+#   $7 = low_priority    ("true" or "false")
+#   $8 = on_calendar     (optional systemd OnCalendar spec)
+#   $9 = timeout_sec     (optional TimeoutStartSec; defaults to interval_sec)
+# Returns 0 on success, 1 if systemd enable fails (caller should fall back to cron).
+_install_scheduler_systemd() {
+	local service_name="$1"
+	local exec_command="$2"
+	local interval_sec="$3"
+	local log_file="$4"
+	local env_vars="$5"
+	local run_at_load="$6"
+	local low_priority="$7"
+	local on_calendar="$8"
+	local timeout_sec="$9"
+	local service_dir="$HOME/.config/systemd/user"
+	local service_file="${service_dir}/${service_name}.service"
+	local timer_file="${service_dir}/${service_name}.timer"
+
+	mkdir -p "$service_dir"
+
+	# GH#18439 Bug 1: command substitution strips trailing newlines, which
+	# would run the final Environment=PATH=... into the following
+	# StandardOutput=... directive on the same line. Use a sentinel ('x')
+	# to preserve the trailing newline that _scheduler_systemd_env_lines
+	# always emits.
+	local _env_lines
+	_env_lines=$(
+		_scheduler_systemd_env_lines "$env_vars"
+		printf 'x'
+	)
+	_env_lines="${_env_lines%x}"
+
+	if [[ -z "$timeout_sec" ]]; then
+		timeout_sec="$interval_sec"
+	fi
+	if [[ -z "$timeout_sec" ]]; then
+		timeout_sec="3600"
+	fi
+
+	local _service_extra=""
+	if [[ "$low_priority" == "true" ]]; then
+		_service_extra+="Nice=10"$'\n'
+		_service_extra+="IOSchedulingClass=idle"$'\n'
+	fi
+
+	printf '%s' "[Unit]
+Description=aidevops ${service_name}
+After=network.target
+
+[Service]
+Type=oneshot
+KillMode=process
+ExecStart=/bin/bash -lc $(_systemd_escape "$exec_command")
+TimeoutStartSec=${timeout_sec}
+${_service_extra}${_env_lines}StandardOutput=append:${log_file}
+StandardError=append:${log_file}
+" >"$service_file"
+
+	local _timer_lines=""
+	if [[ "$run_at_load" == "true" ]]; then
+		_timer_lines+="OnActiveSec=10s"$'\n'
+	fi
+	if [[ -n "$interval_sec" ]]; then
+		_timer_lines+="OnBootSec=${interval_sec}"$'\n'
+		_timer_lines+="OnUnitActiveSec=${interval_sec}"$'\n'
+	fi
+	if [[ -n "$on_calendar" ]]; then
+		_timer_lines+="OnCalendar=${on_calendar}"$'\n'
+	fi
+
+	printf '%s' "[Unit]
+Description=aidevops ${service_name} Timer
+
+[Timer]
+${_timer_lines}Persistent=true
+
+[Install]
+WantedBy=timers.target
+" >"$timer_file"
+
+	systemctl --user daemon-reload 2>/dev/null || true
+	if systemctl --user enable --now "${service_name}.timer" 2>/dev/null; then
+		return 0
+	fi
+	return 1
+}
+
+# Install a generic cron entry.
+# Args: $1=cron_tag, $2=cron_schedule, $3=exec_command, $4=log_file, $5=env_vars
+_install_scheduler_cron() {
+	local cron_tag="$1"
+	local cron_schedule="$2"
+	local exec_command="$3"
+	local log_file="$4"
+	local env_vars="$5"
+	local _cron_exec
+	local _cron_log
+	local _env_prefix
+
+	_env_prefix=$(_scheduler_cron_env_prefix "$env_vars")
+	_cron_exec=$(_cron_escape "$exec_command")
+	_cron_log=$(_cron_escape "$log_file")
+
+	(
+		crontab -l 2>/dev/null | grep -vF "${cron_tag}" || true
+		echo "${cron_schedule} ${_env_prefix}/bin/bash -lc ${_cron_exec} >> ${_cron_log} 2>&1 # ${cron_tag}"
+	) | crontab - 2>/dev/null || true
+	return 0
+}
+
+# Dispatcher: install a scheduler on Linux, preferring systemd over cron.
+# Args:
+#   $1 = service_name   (systemd service name, e.g. "aidevops-stats-wrapper")
+#   $2 = cron_tag       (comment tag for cron line, e.g. "aidevops: stats-wrapper")
+#   $3 = cron_schedule  (cron schedule expression, e.g. "*/15 * * * *")
+#   $4 = exec_command   (shell command run via /bin/bash -lc)
+#   $5 = interval_sec   (systemd OnUnitActiveSec in seconds; may be empty for calendar-only)
+#   $6 = log_file       (absolute path to log file)
+#   $7 = env_vars       (newline-separated KEY=VALUE pairs for systemd/cron, may be empty)
+#   $8 = success_msg    (message to print on success)
+#   $9 = fail_msg       (message to print on failure)
+#   $10 = run_at_load   ("true" or "false")
+#   $11 = low_priority  ("true" or "false")
+#   $12 = on_calendar   (optional systemd OnCalendar spec)
+#   $13 = timeout_sec   (optional TimeoutStartSec)
+# Returns 0 always (failures are warnings, not fatal).
+_install_scheduler_linux() {
+	local service_name="$1"
+	local cron_tag="$2"
+	local cron_schedule="$3"
+	local exec_command="$4"
+	local interval_sec="$5"
+	local log_file="$6"
+	local env_vars="$7"
+	local success_msg="$8"
+	local fail_msg="$9"
+	local run_at_load="${10}"
+	local low_priority="${11}"
+	local on_calendar="${12:-}"
+	local timeout_sec="${13:-}"
+
+	if _systemd_user_available; then
+		if _install_scheduler_systemd \
+			"$service_name" \
+			"$exec_command" \
+			"$interval_sec" \
+			"$log_file" \
+			"$env_vars" \
+			"$run_at_load" \
+			"$low_priority" \
+			"$on_calendar" \
+			"$timeout_sec"; then
+			print_info "${success_msg} (systemd user timer)"
+			# After systemd install succeeds, remove any pre-existing cron entry
+			# to prevent dual-execution (GH#17695 Finding A)
+			if command -v crontab >/dev/null 2>&1; then
+				local current_cron
+				current_cron=$(crontab -l 2>/dev/null) || current_cron=""
+				if [[ -n "$current_cron" ]] && echo "$current_cron" | grep -qF "$cron_tag"; then
+					echo "$current_cron" | grep -vF "$cron_tag" | crontab -
+					echo "[schedulers] Removed pre-existing cron entry for $cron_tag (migrated to systemd)"
+				fi
+			fi
+		else
+			print_warning "systemd enable failed for ${service_name} — falling back to cron"
+			_install_scheduler_cron "$cron_tag" "$cron_schedule" "$exec_command" "$log_file" "$env_vars"
+			if crontab -l 2>/dev/null | grep -qF "${cron_tag}" 2>/dev/null; then
+				print_info "${success_msg} (cron fallback)"
+			else
+				print_warning "${fail_msg}"
+			fi
+		fi
+	else
+		_install_scheduler_cron "$cron_tag" "$cron_schedule" "$exec_command" "$log_file" "$env_vars"
+		if crontab -l 2>/dev/null | grep -qF "${cron_tag}" 2>/dev/null; then
+			print_info "${success_msg} (cron)"
+		else
+			print_warning "${fail_msg}"
+		fi
+	fi
+	return 0
+}
+
+# Uninstall a scheduler across all backends (launchd/systemd/cron).
+# Args:
+#   $1 = os            (output of uname -s)
+#   $2 = launchd_label (e.g. "sh.aidevops.stats-wrapper")
+#   $3 = systemd_name  (e.g. "aidevops-stats-wrapper")
+#   $4 = cron_tag      (grep pattern for cron line, e.g. "aidevops: stats-wrapper")
+#   $5 = success_msg   (message to print on removal)
+# Returns 0 always.
+_uninstall_scheduler() {
+	local _os="$1"
+	local launchd_label="$2"
+	local systemd_name="$3"
+	local cron_tag="$4"
+	local success_msg="$5"
+
+	if [[ "$_os" == "Darwin" ]]; then
+		local _plist="$HOME/Library/LaunchAgents/${launchd_label}.plist"
+		if _launchd_has_agent "$launchd_label"; then
+			launchctl unload "$_plist" 2>/dev/null || true
+			rm -f "$_plist"
+			print_info "${success_msg} (launchd agent removed)"
+		fi
+	else
+		# Check and remove from ALL backends sequentially, not just the first
+		# match. Prevents orphan entries when migrating between systemd and cron
+		# (GH#17695 Finding A).
+		if _systemd_user_available && systemctl --user is-enabled "${systemd_name}.timer" >/dev/null 2>&1; then
+			systemctl --user disable --now "${systemd_name}.timer" 2>/dev/null || true
+			rm -f "$HOME/.config/systemd/user/${systemd_name}.service"
+			rm -f "$HOME/.config/systemd/user/${systemd_name}.timer"
+			systemctl --user daemon-reload 2>/dev/null || true
+			print_info "${success_msg} (systemd timer removed)"
+		fi
+		if command -v crontab >/dev/null 2>&1; then
+			local current_cron
+			current_cron=$(crontab -l 2>/dev/null) || current_cron=""
+			if [[ -n "$current_cron" ]] && echo "$current_cron" | grep -qF "${cron_tag}"; then
+				echo "$current_cron" | grep -vF "${cron_tag}" | crontab - 2>/dev/null || true
+				print_info "${success_msg} (cron entry removed)"
+			fi
+		fi
+	fi
+	return 0
+}
+
+# Uninstall supervisor pulse (user explicitly disabled)
+_uninstall_pulse() {
+	local _os="$1"
+	local pulse_label="$2"
+	if [[ "$_os" == "Darwin" ]]; then
+		local pulse_plist="$HOME/Library/LaunchAgents/${pulse_label}.plist"
+		if _launchd_has_agent "$pulse_label"; then
+			launchctl unload "$pulse_plist" || true
+			rm -f "$pulse_plist"
+			pkill -f 'Supervisor Pulse' 2>/dev/null || true
+			print_info "Supervisor pulse disabled (launchd agent removed per config)"
+		fi
+	elif _systemd_user_available; then
+		local service_name="aidevops-supervisor-pulse"
+		if systemctl --user is-enabled "${service_name}.timer" >/dev/null 2>&1; then
+			systemctl --user disable --now "${service_name}.timer" 2>/dev/null || true
+			rm -f "$HOME/.config/systemd/user/${service_name}.service"
+			rm -f "$HOME/.config/systemd/user/${service_name}.timer"
+			systemctl --user daemon-reload 2>/dev/null || true
+			print_info "Supervisor pulse disabled (systemd timer removed per config)"
+		fi
+	else
+		if crontab -l 2>/dev/null | grep -qF "pulse-wrapper"; then
+			crontab -l 2>/dev/null | grep -v 'aidevops: supervisor-pulse' | crontab - || true
+			print_info "Supervisor pulse disabled (cron entry removed per config)"
+		fi
+	fi
+	return 0
+}