aidevops 3.5.892 → 3.8.2

package/setup-modules/schedulers.sh

@@ -1,9 +1,14 @@
 #!/usr/bin/env bash
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: 2025-2026 Marcus Quinn
 # Scheduler setup functions: supervisor pulse, stats wrapper, process guard,
 # memory pressure monitor, screen time snapshot, contribution watch,
 # profile README, OAuth token refresh.
 # Part of aidevops setup.sh modularization (GH#5793)
 
+# Keep pulse workers alive long enough for opus-tier dispatches.
+PULSE_STALE_THRESHOLD_SECONDS=1800
+
 # Shell safety baseline
 set -Eeuo pipefail
 IFS=$'\n\t'
@@ -105,27 +110,237 @@ _determine_pulse_install() {
 	return 0
 }
 
+# GH#17769: These functions are deprecated — model routing is now derived
+# from the OAuth pool + routing table at runtime. Kept as no-ops for one
+# release cycle in case external scripts call them.
 _resolve_headless_models_override() {
-	local configured="${AIDEVOPS_HEADLESS_MODELS:-}"
-	if [[ -z "$configured" ]] && type config_get &>/dev/null; then
-		configured=$(config_get "orchestration.headless_models" "")
-		if [[ "$configured" == "null" ]]; then
-			configured=""
+	printf '%s' ""
+	return 0
+}
+
+_resolve_pulse_model_override() {
+	printf '%s' ""
+	return 0
+}
+
+_is_pulse_installed() {
+	local pulse_label="$1"
+
+	if _scheduler_detect_installed \
+		"Supervisor pulse" \
+		"$pulse_label" \
+		"" \
+		"pulse-wrapper" \
+		"" \
+		"" \
+		"" \
+		"aidevops-supervisor-pulse"; then
+		return 0
+	fi
+
+	return 1
+}
+
+_resolve_pulse_runtime_binary() {
+	# GH#18439 Bug 2: Persist the resolved binary path across setup.sh
+	# invocations. aidevops-auto-update.timer runs setup.sh under systemd's
+	# minimal PATH, so re-resolving from live `$PATH` alone yields the
+	# legacy macOS-biased `/opt/homebrew/bin/opencode` fallback on Linux.
+	# Reading from persistence first (populated during an interactive
+	# setup.sh run with a rich `$PATH`) prevents the auto-update cycle
+	# from silently degrading the service file.
+	local _persisted_file="$HOME/.config/aidevops/scheduler-runtime-bin"
+	local opencode_bin=""
+
+	# 1. Prefer persisted path if it still points at an executable file.
+	if [[ -f "$_persisted_file" ]]; then
+		local _persisted
+		_persisted=$(head -n1 "$_persisted_file" 2>/dev/null || true)
+		if [[ -n "$_persisted" ]] && [[ -x "$_persisted" ]]; then
+			printf '%s' "$_persisted"
+			return 0
 		fi
 	fi
-	printf '%s' "$configured"
+
+	# 2. Try runtime-registry lookup via live PATH.
+	if type rt_list_headless &>/dev/null; then
+		local _sched_rt_id=""
+		local _sched_bin=""
+		while IFS= read -r _sched_rt_id; do
+			_sched_bin=$(rt_binary "$_sched_rt_id") || continue
+			if [[ -n "$_sched_bin" ]] && command -v "$_sched_bin" &>/dev/null; then
+				opencode_bin=$(command -v "$_sched_bin")
+				break
+			fi
+		done < <(rt_list_headless)
+	fi
+
+	# 3. Direct PATH lookup for the default runtime.
+	if [[ -z "$opencode_bin" ]]; then
+		opencode_bin=$(command -v opencode 2>/dev/null || true)
+	fi
+
+	# 4. OS-aware common-install-location sweep. Used when live `$PATH` is
+	# minimal (systemd-spawned setup.sh) and persistence hasn't been
+	# seeded yet. Covers Homebrew (macOS + Linuxbrew), /usr/local, npm
+	# global, Python/uv pipx-style `.local/bin`, and bun.
+	if [[ -z "$opencode_bin" ]]; then
+		local _candidate
+		for _candidate in \
+			/opt/homebrew/bin/opencode \
+			/usr/local/bin/opencode \
+			/home/linuxbrew/.linuxbrew/bin/opencode \
+			"$HOME/.npm-global/bin/opencode" \
+			"$HOME/.local/bin/opencode" \
+			"$HOME/.bun/bin/opencode" \
+			/opt/homebrew/bin/claude \
+			/usr/local/bin/claude \
+			"$HOME/.local/bin/claude"; do
+			if [[ -x "$_candidate" ]]; then
+				opencode_bin="$_candidate"
+				break
+			fi
+		done
+	fi
+
+	# 5. Last-resort legacy fallback (preserves pre-GH#18439 behaviour so
+	# setup.sh never exits the resolver empty-handed).
+	[[ -z "$opencode_bin" ]] && opencode_bin="/opt/homebrew/bin/opencode"
+
+	# Persist the resolved path for subsequent non-interactive invocations
+	# (auto-update timer, cron regeneration). Only write when we actually
+	# found a real executable — don't persist the legacy fallback.
+	if [[ -x "$opencode_bin" ]]; then
+		mkdir -p "$(dirname "$_persisted_file")" 2>/dev/null || true
+		printf '%s\n' "$opencode_bin" >"$_persisted_file" 2>/dev/null || true
+	fi
+
+	printf '%s' "$opencode_bin"
 	return 0
 }
 
-_resolve_pulse_model_override() {
-	local configured="${PULSE_MODEL:-}"
-	if [[ -z "$configured" ]] && type config_get &>/dev/null; then
-		configured=$(config_get "orchestration.pulse_model" "")
-		if [[ "$configured" == "null" ]]; then
-			configured=""
+_build_pulse_linux_env() {
+	# GH#17546/GH#17769: Model config is derived from pool + routing table at
+	# runtime. No model env vars embedded in cron/systemd.
+	local opencode_bin="${1:-}"
+	local _pulse_env="PULSE_DIR=${HOME}/.aidevops/.agent-workspace
+PULSE_STALE_THRESHOLD=${PULSE_STALE_THRESHOLD_SECONDS}"
+
+	# GH#18439 Bug 2: embed resolved runtime binary path so pulse-wrapper.sh
+	# and headless-runtime-helper.sh find the correct binary under systemd's
+	# minimal PATH (e.g. when aidevops-auto-update.timer regenerates the
+	# service file). Mirrors the macOS launchd <OPENCODE_BIN> key.
+	if [[ -n "$opencode_bin" ]]; then
+		_pulse_env+=$'\n'"OPENCODE_BIN=${opencode_bin}"
+	fi
+
+	printf '%s' "$_pulse_env"
+	return 0
+}
+
+# Read supervisor.pulse_interval_seconds from settings.json.
+# Falls back to 120 if the file is missing, the key is absent, or jq is unavailable.
+# Clamps to the validated range [30, 3600].
+# GH#18018: previously this was hardcoded as "120" in _install_supervisor_pulse.
+_read_pulse_interval_seconds() {
+	local _settings_file="$HOME/.config/aidevops/settings.json"
+	local _interval=120
+
+	if command -v jq >/dev/null 2>&1 && [[ -f "$_settings_file" ]]; then
+		local _raw
+		_raw=$(jq -r '.supervisor.pulse_interval_seconds // empty' "$_settings_file" 2>/dev/null) || _raw=""
+		if [[ -n "$_raw" ]] && [[ "$_raw" =~ ^[0-9]+$ ]]; then
+			_interval="$_raw"
 		fi
 	fi
-	printf '%s' "$configured"
+
+	# Clamp to validated range (mirrors settings-helper.sh validation: 30-3600)
+	if [[ "$_interval" -lt 30 ]]; then
+		_interval=30
+	elif [[ "$_interval" -gt 3600 ]]; then
+		_interval=3600
+	fi
+
+	printf '%d' "$_interval"
+	return 0
+}
+
+# Convert an interval in seconds to a cron schedule expression (e.g. "*/2 * * * *").
+# Minimum granularity is 1 minute. Intervals that don't divide evenly into minutes
+# are rounded down to whole minutes with a warning.
+# Args: $1 = interval_seconds
+_seconds_to_cron_schedule() {
+	local _interval_sec="$1"
+	local _minutes=$((_interval_sec / 60))
+	local _remainder=$((_interval_sec % 60))
+
+	# Clamp to at least 1 minute
+	if [[ "$_minutes" -lt 1 ]]; then
+		_minutes=1
+	fi
+
+	# Warn if interval doesn't divide evenly into minutes
+	if [[ "$_remainder" -ne 0 ]]; then
+		echo "[schedulers] Warning: pulse_interval_seconds=${_interval_sec} does not divide evenly into minutes; rounding down to ${_minutes}min for cron schedule (systemd uses exact seconds)" >&2
+	fi
+
+	# cron step values must be 1-59; */60 is invalid. Use @hourly for exactly 60 min,
+	# clamp anything above 59 to 59 (the _read_pulse_interval_seconds cap is 3600s=60min).
+	if [[ "$_minutes" -ge 60 ]]; then
+		printf '@hourly'
+	else
+		printf '*/%d * * * *' "$_minutes"
+	fi
+	return 0
+}
+
+_install_supervisor_pulse() {
+	local _os="$1"
+	local pulse_label="$2"
+	local wrapper_script="$3"
+	local opencode_bin="$4"
+	local _pulse_installed="$5"
+
+	mkdir -p "$HOME/.aidevops/logs"
+
+	if [[ "$_os" == "Darwin" ]]; then
+		_install_pulse_launchd "$pulse_label" "$wrapper_script" "$opencode_bin" "$_pulse_installed"
+		return 0
+	fi
+
+	# GH#18018: read user-configured interval instead of hardcoding 120s / */2 cron
+	local _pulse_interval_sec
+	_pulse_interval_sec=$(_read_pulse_interval_seconds)
+	local _pulse_cron_schedule
+	_pulse_cron_schedule=$(_seconds_to_cron_schedule "$_pulse_interval_sec")
+	# Build a human-readable interval label: show seconds when < 60s, minutes otherwise
+	local _pulse_interval_label
+	if [[ "$_pulse_interval_sec" -lt 60 ]]; then
+		_pulse_interval_label="${_pulse_interval_sec}s"
+	else
+		_pulse_interval_label="$((_pulse_interval_sec / 60))min"
+	fi
+
+	local _pulse_timeout_sec=$((PULSE_STALE_THRESHOLD_SECONDS + 60))
+	local _pulse_env=""
+	# GH#18439 Bug 2: thread resolved runtime binary path through to the
+	# Linux env builder so OPENCODE_BIN is embedded in the systemd service
+	# file (parity with the macOS launchd plist at line 415).
+	_pulse_env=$(_build_pulse_linux_env "$opencode_bin")
+	_install_scheduler_linux \
+		"aidevops-supervisor-pulse" \
+		"aidevops: supervisor-pulse" \
+		"${_pulse_cron_schedule}" \
+		"\"${wrapper_script}\"" \
+		"${_pulse_interval_sec}" \
+		"$HOME/.aidevops/logs/pulse-wrapper.log" \
+		"$_pulse_env" \
+		"Supervisor pulse enabled (every ${_pulse_interval_label})" \
+		"Failed to install supervisor pulse scheduler. See runners.md for manual setup." \
+		"true" \
+		"false" \
+		"" \
+		"${_pulse_timeout_sec}"
 	return 0
 }
 
@@ -162,44 +377,18 @@ setup_supervisor_pulse() {
 	_pulse_lower=$(echo "$_pulse_user_config" | tr '[:upper:]' '[:lower:]')
 
 	# Detect if pulse is already installed (for upgrade messaging)
-	# Uses shared helper to check both launchd and cron consistently
+	# Uses shared helper to check launchd, cron, and systemd (GH#17381)
 	local _pulse_installed=false
-	if _scheduler_detect_installed \
-		"Supervisor pulse" \
-		"$pulse_label" \
-		"" \
-		"pulse-wrapper" \
-		"" \
-		"" \
-		""; then
+	if _is_pulse_installed "$pulse_label"; then
 		_pulse_installed=true
 	fi
 
 	# Detect dispatch backend binary location (t1665.5 — registry-driven)
-	local opencode_bin
-	if type rt_list_headless &>/dev/null; then
-		local _sched_rt_id _sched_bin
-		while IFS= read -r _sched_rt_id; do
-			_sched_bin=$(rt_binary "$_sched_rt_id") || continue
-			if [[ -n "$_sched_bin" ]] && command -v "$_sched_bin" &>/dev/null; then
-				opencode_bin=$(command -v "$_sched_bin")
-				break
-			fi
-		done < <(rt_list_headless)
-	fi
-	# Fallback if registry not loaded or no runtime found
-	opencode_bin="${opencode_bin:-$(command -v opencode 2>/dev/null || echo "/opt/homebrew/bin/opencode")}"
+	local opencode_bin=""
+	opencode_bin=$(_resolve_pulse_runtime_binary)
 
 	if [[ "$_do_install" == "true" ]]; then
-		mkdir -p "$HOME/.aidevops/logs"
-
-		if [[ "$_os" == "Darwin" ]]; then
-			_install_pulse_launchd "$pulse_label" "$wrapper_script" "$opencode_bin" "$_pulse_installed"
-		elif _systemd_user_available; then
-			_install_pulse_systemd "aidevops-supervisor-pulse" "$wrapper_script"
-		else
-			_install_pulse_cron "$wrapper_script"
-		fi
+		_install_supervisor_pulse "$_os" "$pulse_label" "$wrapper_script" "$opencode_bin" "$_pulse_installed"
 	elif [[ "$_pulse_lower" == "false" && "$_pulse_installed" == "true" ]]; then
 		# User explicitly disabled but pulse is still installed — clean up
 		_uninstall_pulse "$_os" "$pulse_label"
@@ -239,40 +428,12 @@ _cleanup_old_pulse_plists() {
 }
 
 # Build XML environment variable fragment for headless model overrides.
-# Reads configured overrides and emits XML key/string pairs for plist embedding.
-# Prints the XML fragment to stdout (may be empty if no overrides configured).
+# GH#17546: Model config was removed from plist embedding.
+# GH#17769: Model routing is now derived from pool + routing table at runtime.
+# No env vars needed — pulse-wrapper.sh reads the routing table directly.
 _build_pulse_headless_env_xml() {
-	local _headless_xml_env=""
-	local _configured_headless_models _configured_pulse_model
-	_configured_headless_models=$(_resolve_headless_models_override)
-	_configured_pulse_model=$(_resolve_pulse_model_override)
-
-	if [[ -n "$_configured_headless_models" ]]; then
-		local _xml_headless_models
-		_xml_headless_models=$(_xml_escape "$_configured_headless_models")
-		_headless_xml_env+=$'\n'
-		_headless_xml_env+=$'\t\t<key>AIDEVOPS_HEADLESS_MODELS</key>'
-		_headless_xml_env+=$'\n'
-		_headless_xml_env+=$'\t\t'"<string>${_xml_headless_models}</string>"
-	fi
-	if [[ -n "$_configured_pulse_model" ]]; then
-		local _xml_pulse_model
-		_xml_pulse_model=$(_xml_escape "$_configured_pulse_model")
-		_headless_xml_env+=$'\n'
-		_headless_xml_env+=$'\t\t<key>PULSE_MODEL</key>'
-		_headless_xml_env+=$'\n'
-		_headless_xml_env+=$'\t\t'"<string>${_xml_pulse_model}</string>"
-	fi
-	if [[ -n "${AIDEVOPS_HEADLESS_PROVIDER_ALLOWLIST:-}" ]]; then
-		local _xml_headless_allowlist
-		_xml_headless_allowlist=$(_xml_escape "$AIDEVOPS_HEADLESS_PROVIDER_ALLOWLIST")
-		_headless_xml_env+=$'\n'
-		_headless_xml_env+=$'\t\t<key>AIDEVOPS_HEADLESS_PROVIDER_ALLOWLIST</key>'
-		_headless_xml_env+=$'\n'
-		_headless_xml_env+=$'\t\t'"<string>${_xml_headless_allowlist}</string>"
-	fi
-
-	printf '%s' "$_headless_xml_env"
+	# Intentionally empty — model config read from credentials.sh at runtime.
+	printf '%s' ""
 	return 0
 }
 
@@ -327,7 +488,7 @@ _generate_pulse_plist_content() {
 		<key>PULSE_DIR</key>
 		<string>${_xml_pulse_dir}</string>
 		<key>PULSE_STALE_THRESHOLD</key>
-		<string>1800</string>
+		<string>${PULSE_STALE_THRESHOLD_SECONDS}</string>
 		${_headless_xml_env}
 	</dict>
 	<key>RunAtLoad</key>
@@ -365,49 +526,6 @@ _install_pulse_launchd() {
 	return 0
 }
 
-# Install supervisor pulse via cron (Linux)
-_install_pulse_cron() {
-	local wrapper_script="$1"
-	# Shell-escape all interpolated paths to prevent command injection
-	# via $(…) or backticks if paths contain shell metacharacters
-	# PATH is managed globally by _ensure_cron_path() — do NOT set inline
-	# 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_pulse_dir _cron_wrapper_script _cron_headless_env=""
-	local _configured_headless_models _configured_pulse_model
-	_configured_headless_models=$(_resolve_headless_models_override)
-	_configured_pulse_model=$(_resolve_pulse_model_override)
-	# 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 "$_configured_headless_models" ]]; then
-		local _cron_headless_models
-		_cron_headless_models=$(_cron_escape "$_configured_headless_models")
-		_cron_headless_env+=" AIDEVOPS_HEADLESS_MODELS=${_cron_headless_models}"
-	fi
-	if [[ -n "$_configured_pulse_model" ]]; then
-		local _cron_pulse_model
-		_cron_pulse_model=$(_cron_escape "$_configured_pulse_model")
-		_cron_headless_env+=" PULSE_MODEL=${_cron_pulse_model}"
-	fi
-	if [[ -n "${AIDEVOPS_HEADLESS_PROVIDER_ALLOWLIST:-}" ]]; then
-		local _cron_headless_allowlist
-		_cron_headless_allowlist=$(_cron_escape "$AIDEVOPS_HEADLESS_PROVIDER_ALLOWLIST")
-		_cron_headless_env+=" AIDEVOPS_HEADLESS_PROVIDER_ALLOWLIST=${_cron_headless_allowlist}"
-	fi
-	(
-		crontab -l 2>/dev/null | grep -v 'aidevops: supervisor-pulse' || true
-		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"
-	else
-		print_warning "Failed to install supervisor pulse cron entry. See runners.md for manual setup."
-	fi
-	return 0
-}
-
 # Check if systemd user services are available on this Linux system.
 # Returns 0 if systemd --user is functional, 1 otherwise.
 _systemd_user_available() {
@@ -416,54 +534,153 @@ _systemd_user_available() {
 	return 0
 }
 
-# Install supervisor pulse via systemd user service (Linux with systemd)
-# Args: $1=service_name (e.g. "aidevops-supervisor-pulse"), $2=wrapper_script
-_install_pulse_systemd() {
+# Escape a value for safe embedding in a systemd unit Environment= 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")
+_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 wrapper_script="$2"
+	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"
 
-	# Build environment overrides for the service
-	local _env_lines=""
-	local _configured_headless_models _configured_pulse_model
-	_configured_headless_models=$(_resolve_headless_models_override)
-	_configured_pulse_model=$(_resolve_pulse_model_override)
-	if [[ -n "$_configured_headless_models" ]]; then
-		_env_lines+="Environment=AIDEVOPS_HEADLESS_MODELS=${_configured_headless_models}\n"
+	# 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 [[ -n "$_configured_pulse_model" ]]; then
-		_env_lines+="Environment=PULSE_MODEL=${_configured_pulse_model}\n"
+	if [[ -z "$timeout_sec" ]]; then
+		timeout_sec="3600"
 	fi
-	if [[ -n "${AIDEVOPS_HEADLESS_PROVIDER_ALLOWLIST:-}" ]]; then
-		_env_lines+="Environment=AIDEVOPS_HEADLESS_PROVIDER_ALLOWLIST=${AIDEVOPS_HEADLESS_PROVIDER_ALLOWLIST}\n"
+
+	local _service_extra=""
+	if [[ "$low_priority" == "true" ]]; then
+		_service_extra+="Nice=10"$'\n'
+		_service_extra+="IOSchedulingClass=idle"$'\n'
 	fi
-	_env_lines+="Environment=PULSE_DIR=${HOME}/.aidevops/.agent-workspace\n"
-	_env_lines+="Environment=HOME=${HOME}\n"
 
-	# Write the service unit
 	printf '%s' "[Unit]
-Description=aidevops Supervisor Pulse
+Description=aidevops ${service_name}
 After=network.target
 
 [Service]
 Type=oneshot
-ExecStart=/bin/bash ${wrapper_script}
-${_env_lines}StandardOutput=append:${HOME}/.aidevops/logs/pulse-wrapper.log
-StandardError=append:${HOME}/.aidevops/logs/pulse-wrapper.log
+KillMode=process
+ExecStart=/bin/bash -lc $(_systemd_escape "$exec_command")
+TimeoutStartSec=${timeout_sec}
+${_service_extra}${_env_lines}StandardOutput=$(_systemd_escape "append:${log_file}")
+StandardError=$(_systemd_escape "append:${log_file}")
 " >"$service_file"
 
-	# Write the timer unit (every 2 minutes)
+	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 Supervisor Pulse Timer
+Description=aidevops ${service_name} Timer
 
 [Timer]
-OnBootSec=2min
-OnUnitActiveSec=2min
-Persistent=true
+${_timer_lines}Persistent=true
 
 [Install]
 WantedBy=timers.target
@@ -471,11 +688,148 @@ WantedBy=timers.target
 
 	systemctl --user daemon-reload 2>/dev/null || true
 	if systemctl --user enable --now "${service_name}.timer" 2>/dev/null; then
-		print_info "Supervisor pulse enabled (systemd user timer, every 2 min)"
-		print_info "Disable: systemctl --user disable --now ${service_name}.timer"
+		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
-		print_warning "Failed to enable systemd timer — falling back to cron"
-		_install_pulse_cron "$wrapper_script"
+		# 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
 }
@@ -513,6 +867,7 @@ _uninstall_pulse() {
 # Setup stats-wrapper scheduler — runs quality sweep and health issue updates
 # separately from the pulse (t1429). Only installed when the supervisor
 # pulse is enabled (stats are useless without it).
+# macOS: launchd plist (every 15 min) | Linux: systemd timer or cron (every 15 min)
 setup_stats_wrapper() {
 	local _pulse_lower="$1"
 	# Use effective pulse state (PULSE_ENABLED) if available; fall back to consent string.
@@ -520,6 +875,8 @@ setup_stats_wrapper() {
 	local _pulse_effective="${PULSE_ENABLED:-$_pulse_lower}"
 	local stats_script="$HOME/.aidevops/agents/scripts/stats-wrapper.sh"
 	local stats_label="com.aidevops.aidevops-stats-wrapper"
+	local stats_systemd="aidevops-stats-wrapper"
+	local stats_log="$HOME/.aidevops/logs/stats.log"
 	if [[ -x "$stats_script" ]] && [[ "$_pulse_effective" == "true" ]]; then
 		# Always regenerate to pick up config/format changes (matches pulse behavior)
 		if [[ "$(uname -s)" == "Darwin" ]]; then
@@ -570,31 +927,27 @@ PLIST
 				print_warning "Failed to load stats wrapper LaunchAgent"
 			fi
 		else
-			local _cron_stats_script
-			_cron_stats_script=$(_cron_escape "$stats_script")
-			(
-				crontab -l 2>/dev/null | grep -v 'aidevops: stats-wrapper' || true
-				echo "*/15 * * * * /bin/bash ${_cron_stats_script} >> \"\$HOME/.aidevops/logs/stats.log\" 2>&1 # aidevops: stats-wrapper"
-			) | crontab - || true
-			if crontab -l 2>/dev/null | grep -qF "aidevops: stats-wrapper"; then
-				print_info "Stats wrapper enabled (cron, every 15 min)"
-			fi
+			_install_scheduler_linux \
+				"$stats_systemd" \
+				"aidevops: stats-wrapper" \
+				"*/15 * * * *" \
+				"\"${stats_script}\"" \
+				"900" \
+				"$stats_log" \
+				"" \
+				"Stats wrapper enabled (every 15 min)" \
+				"Failed to install stats wrapper scheduler" \
+				"true" \
+				"false"
 		fi
 	elif [[ "$_pulse_effective" == "false" ]]; then
 		# Remove stats scheduler if pulse is disabled
-		if [[ "$(uname -s)" == "Darwin" ]]; then
-			local stats_plist="$HOME/Library/LaunchAgents/${stats_label}.plist"
-			if _launchd_has_agent "$stats_label"; then
-				launchctl unload "$stats_plist" || true
-				rm -f "$stats_plist"
-				print_info "Stats wrapper disabled (launchd agent removed — pulse is off)"
-			fi
-		else
-			if crontab -l 2>/dev/null | grep -qF "aidevops: stats-wrapper"; then
-				crontab -l 2>/dev/null | grep -v 'aidevops: stats-wrapper' | crontab - || true
-				print_info "Stats wrapper disabled (cron entry removed — pulse is off)"
-			fi
-		fi
+		_uninstall_scheduler \
+			"$(uname -s)" \
+			"$stats_label" \
+			"$stats_systemd" \
+			"aidevops: stats-wrapper" \
+			"Stats wrapper disabled (pulse is off)"
 	fi
 	return 0
 }
@@ -602,27 +955,22 @@ PLIST
 # Setup failure miner — mines GitHub CI failure notifications for systemic patterns
 # and auto-files root-cause issues. Runs as a pure bash script (no LLM needed).
 # Installed when pulse is enabled and the helper script exists.
-# macOS: launchd plist (hourly at :15) | Linux: cron (hourly at :15)
+# macOS: launchd plist (hourly at :15) | Linux: systemd timer or cron (hourly at :15)
 setup_failure_miner() {
 	local _pulse_lower="$1"
 	local _pulse_effective="${PULSE_ENABLED:-$_pulse_lower}"
 	local miner_script="$HOME/.aidevops/agents/scripts/gh-failure-miner-helper.sh"
 	local miner_label="sh.aidevops.routine-gh-failure-miner"
+	local miner_systemd="aidevops-gh-failure-miner"
+	local miner_log="$HOME/.aidevops/logs/routine-gh-failure-miner.log"
 	if [[ ! -x "$miner_script" ]] || [[ "$_pulse_effective" != "true" ]]; then
 		# Remove scheduler if pulse is disabled or script missing
-		if [[ "$(uname -s)" == "Darwin" ]]; then
-			local miner_plist="$HOME/Library/LaunchAgents/${miner_label}.plist"
-			if _launchd_has_agent "$miner_label"; then
-				launchctl unload "$miner_plist" 2>/dev/null || true
-				rm -f "$miner_plist"
-				print_info "Failure miner disabled (pulse is off or script missing)"
-			fi
-		else
-			if crontab -l 2>/dev/null | grep -qF "aidevops: gh-failure-miner"; then
-				crontab -l 2>/dev/null | grep -v 'aidevops: gh-failure-miner' | crontab - || true
-				print_info "Failure miner disabled (cron entry removed)"
-			fi
-		fi
+		_uninstall_scheduler \
+			"$(uname -s)" \
+			"$miner_label" \
+			"$miner_systemd" \
+			"aidevops: gh-failure-miner" \
+			"Failure miner disabled (pulse is off or script missing)"
 		return 0
 	fi
 
@@ -635,7 +983,7 @@ setup_failure_miner() {
 		_xml_miner_script=$(_xml_escape "$miner_script")
 		_xml_miner_home=$(_xml_escape "$HOME")
 		_xml_miner_path=$(_xml_escape "/bin:/usr/bin:/usr/local/bin:/opt/homebrew/bin:${PATH}")
-		_xml_miner_log=$(_xml_escape "${HOME}/.aidevops/logs/routine-gh-failure-miner.log")
+		_xml_miner_log=$(_xml_escape "$miner_log")
 
 		local miner_plist_content
 		miner_plist_content=$(
@@ -692,15 +1040,19 @@ MINER_PLIST
 			print_warning "Failed to load failure miner LaunchAgent"
 		fi
 	else
-		local _cron_miner_script
-		_cron_miner_script=$(_cron_escape "$miner_script")
-		(
-			crontab -l 2>/dev/null | grep -v 'aidevops: gh-failure-miner' || true
-			echo "15 * * * * /bin/bash ${_cron_miner_script} create-issues --since-hours 24 --pulse-repos --systemic-threshold 2 --max-issues 3 --label auto-dispatch >> \"\$HOME/.aidevops/logs/routine-gh-failure-miner.log\" 2>&1 # aidevops: gh-failure-miner"
-		) | crontab - || true
-		if crontab -l 2>/dev/null | grep -qF "aidevops: gh-failure-miner"; then
-			print_info "Failure miner enabled (cron, hourly at :15)"
-		fi
+		_install_scheduler_linux \
+			"$miner_systemd" \
+			"aidevops: gh-failure-miner" \
+			"15 * * * *" \
+			"\"${miner_script}\" create-issues --since-hours 24 --pulse-repos --systemic-threshold 2 --max-issues 3 --label auto-dispatch" \
+			"3600" \
+			"$miner_log" \
+			"" \
+			"Failure miner enabled (hourly at :15)" \
+			"Failed to install failure miner scheduler" \
+			"false" \
+			"false" \
+			"*-*-* *:15:00"
 	fi
 	return 0
 }
@@ -708,10 +1060,12 @@ MINER_PLIST
 # Setup process guard — kills runaway AI processes (ShellCheck bloat, stuck workers)
 # before they exhaust memory and cause kernel panics. Always installed when the
 # script exists; no consent needed (safety net, not autonomous action).
-# macOS: launchd plist (30s interval, RunAtLoad=true) | Linux: cron (every minute)
+# macOS: launchd plist (30s interval, RunAtLoad=true) | Linux: systemd timer or cron (every minute)
 setup_process_guard() {
 	local guard_script="$HOME/.aidevops/agents/scripts/process-guard-helper.sh"
 	local guard_label="sh.aidevops.process-guard"
+	local guard_systemd="aidevops-process-guard"
+	local guard_log="$HOME/.aidevops/logs/process-guard.log"
 	if [[ ! -x "$guard_script" ]]; then
 		return 0
 	fi
@@ -779,20 +1133,22 @@ GUARD_PLIST
 			print_warning "Failed to load process guard LaunchAgent"
 		fi
 	else
-		# Linux: cron entry (every minute — cron minimum granularity)
-		# Always regenerate to pick up config changes (matches macOS behavior)
-		# Shell-escape path to prevent command injection via metacharacters
-		local _cron_guard_script
-		_cron_guard_script=$(_cron_escape "$guard_script")
-		(
-			crontab -l 2>/dev/null | grep -v 'aidevops: process-guard' || true
-			echo "* * * * * SHELLCHECK_RSS_LIMIT_KB=524288 SHELLCHECK_RUNTIME_LIMIT=120 CHILD_RSS_LIMIT_KB=8388608 CHILD_RUNTIME_LIMIT=7200 /bin/bash ${_cron_guard_script} kill-runaways >> \"\$HOME/.aidevops/logs/process-guard.log\" 2>&1 # aidevops: process-guard"
-		) | crontab - || true
-		if crontab -l 2>/dev/null | grep -qF "aidevops: process-guard"; then
-			print_info "Process guard enabled (cron, every minute)"
-		else
-			print_warning "Failed to install process guard cron entry"
-		fi
+		# Linux: systemd timer (30s) or cron fallback (every minute — cron minimum granularity)
+		_install_scheduler_linux \
+			"$guard_systemd" \
+			"aidevops: process-guard" \
+			"* * * * *" \
+			"\"${guard_script}\" kill-runaways" \
+			"30" \
+			"$guard_log" \
+			"SHELLCHECK_RSS_LIMIT_KB=524288
+SHELLCHECK_RUNTIME_LIMIT=120
+CHILD_RSS_LIMIT_KB=8388608
+CHILD_RUNTIME_LIMIT=7200" \
+			"Process guard enabled (every 30s)" \
+			"Failed to install process guard scheduler" \
+			"true" \
+			"false"
 	fi
 	return 0
 }
@@ -801,10 +1157,12 @@ GUARD_PLIST
 # Monitors individual process RSS, runtime, session count, and aggregate memory.
 # Auto-kills runaway ShellCheck (language server respawns them). Always installed
 # when the script exists; no consent needed (safety net, not autonomous action).
-# macOS: launchd plist (60s interval, RunAtLoad=true) | Linux: cron (every minute)
+# macOS: launchd plist (60s interval, RunAtLoad=true) | Linux: systemd timer or cron (every minute)
 setup_memory_pressure_monitor() {
 	local monitor_script="$HOME/.aidevops/agents/scripts/memory-pressure-monitor.sh"
 	local monitor_label="sh.aidevops.memory-pressure-monitor"
+	local monitor_systemd="aidevops-memory-pressure-monitor"
+	local monitor_log="$HOME/.aidevops/logs/memory-pressure-launchd.log"
 	if [[ ! -x "$monitor_script" ]]; then
 		return 0
 	fi
@@ -867,16 +1225,19 @@ MONITOR_PLIST
 			print_warning "Failed to load memory pressure monitor LaunchAgent"
 		fi
 	else
-		# Linux: cron entry (every minute — cron minimum granularity)
-		(
-			crontab -l 2>/dev/null | grep -v 'aidevops: memory-pressure-monitor' || true
-			echo "* * * * * /bin/bash \"${monitor_script}\" >> \"\$HOME/.aidevops/logs/memory-pressure-launchd.log\" 2>&1 # aidevops: memory-pressure-monitor"
-		) | crontab - 2>/dev/null || true
-		if crontab -l 2>/dev/null | grep -qF "aidevops: memory-pressure-monitor" 2>/dev/null; then
-			print_info "Memory pressure monitor enabled (cron, every minute)"
-		else
-			print_warning "Failed to install memory pressure monitor cron entry"
-		fi
+		# Linux: systemd timer (60s) or cron fallback (every minute — cron minimum granularity)
+		_install_scheduler_linux \
+			"$monitor_systemd" \
+			"aidevops: memory-pressure-monitor" \
+			"* * * * *" \
+			"\"${monitor_script}\"" \
+			"60" \
+			"$monitor_log" \
+			"" \
+			"Memory pressure monitor enabled (every 60s)" \
+			"Failed to install memory pressure monitor scheduler" \
+			"true" \
+			"true"
 	fi
 	return 0
 }
@@ -884,10 +1245,12 @@ MONITOR_PLIST
 # Setup screen time snapshot — captures daily screen time for contributor stats.
 # Accumulates data in screen-time.jsonl (macOS Knowledge DB retains only ~28 days).
 # Always installed when the script exists; no consent needed (data collection only).
-# macOS: launchd plist (every 6h, RunAtLoad=true) | Linux: cron (every 6h)
+# macOS: launchd plist (every 6h, RunAtLoad=true) | Linux: systemd timer or cron (every 6h)
 setup_screen_time_snapshot() {
 	local st_script="$HOME/.aidevops/agents/scripts/screen-time-helper.sh"
 	local st_label="sh.aidevops.screen-time-snapshot"
+	local st_systemd="aidevops-screen-time-snapshot"
+	local st_log="$HOME/.aidevops/.agent-workspace/logs/screen-time-snapshot.log"
 	if [[ ! -x "$st_script" ]]; then
 		return 0
 	fi
@@ -951,18 +1314,19 @@ ST_PLIST
 			print_warning "Failed to load screen time snapshot LaunchAgent"
 		fi
 	else
-		# Linux: cron entry (every 6 hours)
-		local _cron_st_script
-		_cron_st_script=$(_cron_escape "$st_script")
-		(
-			crontab -l 2>/dev/null | grep -v 'aidevops: screen-time-snapshot' || true
-			echo "0 */6 * * * /bin/bash ${_cron_st_script} snapshot >> \"\$HOME/.aidevops/.agent-workspace/logs/screen-time-snapshot.log\" 2>&1 # aidevops: screen-time-snapshot"
-		) | crontab - 2>/dev/null || true
-		if crontab -l 2>/dev/null | grep -qF "aidevops: screen-time-snapshot" 2>/dev/null; then
-			print_info "Screen time snapshot enabled (cron, every 6h)"
-		else
-			print_warning "Failed to install screen time snapshot cron entry"
-		fi
+		# Linux: systemd timer (every 6h) or cron fallback
+		_install_scheduler_linux \
+			"$st_systemd" \
+			"aidevops: screen-time-snapshot" \
+			"0 */6 * * *" \
+			"\"${st_script}\" snapshot" \
+			"21600" \
+			"$st_log" \
+			"" \
+			"Screen time snapshot enabled (every 6h)" \
+			"Failed to install screen time snapshot scheduler" \
+			"true" \
+			"true"
 	fi
 	return 0
 }
@@ -1057,29 +1421,30 @@ CW_PLIST
 	return 0
 }
 
-# Install contribution watch via cron (Linux).
+# Install contribution watch via systemd or cron (Linux).
 # Args: $1=script path, $2=log dir
-_install_cw_cron() {
+_install_cw_linux() {
 	local cw_script="$1"
 	local _cw_log_dir="$2"
-	local _cron_cw_script _cron_cw_log_dir
-	_cron_cw_script=$(_cron_escape "$cw_script")
-	_cron_cw_log_dir=$(_cron_escape "$_cw_log_dir")
-	(
-		crontab -l 2>/dev/null | grep -v 'aidevops: contribution-watch' || true
-		echo "0 * * * * /bin/bash ${_cron_cw_script} scan >> \"${_cron_cw_log_dir}/contribution-watch.log\" 2>&1 # aidevops: contribution-watch"
-	) | crontab - 2>/dev/null || true
-	if crontab -l 2>/dev/null | grep -qF "aidevops: contribution-watch" 2>/dev/null; then
-		print_info "Contribution watch enabled (cron, hourly scan)"
-	else
-		print_warning "Failed to install contribution watch cron entry"
-	fi
+	local cw_systemd="aidevops-contribution-watch"
+	_install_scheduler_linux \
+		"$cw_systemd" \
+		"aidevops: contribution-watch" \
+		"0 * * * *" \
+		"\"${cw_script}\" scan" \
+		"3600" \
+		"${_cw_log_dir}/contribution-watch.log" \
+		"" \
+		"Contribution watch enabled (hourly scan)" \
+		"Failed to install contribution watch scheduler" \
+		"false" \
+		"true"
 	return 0
 }
 
 # Setup contribution watch — monitors external issues/PRs for new activity (t1554).
 # Auto-seeds on first run (discovers authored/commented issues/PRs), then installs
-# a launchd/cron job to scan periodically. Requires gh CLI authenticated.
+# a launchd/systemd/cron job to scan periodically. Requires gh CLI authenticated.
 # No consent needed — this is passive monitoring (read-only notifications API),
 # not autonomous action. Comment bodies are never processed by LLM in automated context.
 # Respects config: aidevops config set orchestration.contribution_watch false
@@ -1110,7 +1475,7 @@ setup_contribution_watch() {
 	if [[ "$(uname -s)" == "Darwin" ]]; then
 		_install_cw_launchd "$cw_label" "$cw_script" "$_cw_log_dir"
 	else
-		_install_cw_cron "$cw_script" "$_cw_log_dir"
+		_install_cw_linux "$cw_script" "$_cw_log_dir"
 	fi
 	return 0
 }
@@ -1134,43 +1499,42 @@ setup_draft_responses() {
 # Setup profile README — auto-create repo and seed README if not already set up.
 # Requires gh CLI authenticated. Creates username/username repo, seeds README
 # with stat markers, registers in repos.json with priority: "profile".
-setup_profile_readme() {
-	local pr_script="$HOME/.aidevops/agents/scripts/profile-readme-helper.sh"
-	local pr_label="sh.aidevops.profile-readme-update"
-	if ! [[ -x "$pr_script" ]] || ! command -v gh &>/dev/null || ! gh auth status &>/dev/null; then
-		return 0
+_profile_readme_ready() {
+	local pr_script="$1"
+	if ! [[ -x "$pr_script" ]]; then
+		return 1
 	fi
+	if ! command -v gh &>/dev/null; then
+		return 1
+	fi
+	if ! gh auth status &>/dev/null; then
+		return 1
+	fi
+	return 0
+}
 
-	# Initialize profile repo if not already set up.
-	# Always run init — it's idempotent and handles:
-	#   - Fresh installs (no profile repo)
-	#   - Missing markers (injects them into existing README)
-	#   - Diverged history (repo deleted and recreated on GitHub)
-	#   - Already-initialized repos (returns early with no changes)
+_run_profile_readme_init() {
+	local pr_script="$1"
 	print_info "Checking GitHub profile README..."
 	if bash "$pr_script" init; then
 		print_info "Profile README ready."
 	else
 		print_warning "Profile README setup failed (non-fatal, skipping)"
 	fi
+	return 0
+}
 
-	# Profile README auto-update scheduled job.
-	# Installed whenever gh CLI is available — the update script self-heals
-	# (discovers/creates the profile repo on first run via _resolve_profile_repo).
-	# macOS: launchd plist (hourly) | Linux: cron (hourly)
-	mkdir -p "$HOME/.aidevops/.agent-workspace/logs"
-
-	if [[ "$(uname -s)" == "Darwin" ]]; then
-		local pr_plist="$HOME/Library/LaunchAgents/${pr_label}.plist"
-
-		# XML-escape paths for safe plist embedding
-		local _xml_pr_script _xml_pr_home
-		_xml_pr_script=$(_xml_escape "$pr_script")
-		_xml_pr_home=$(_xml_escape "$HOME")
-
-		local pr_plist_content
-		pr_plist_content=$(
-			cat <<PR_PLIST
+_install_profile_readme_launchd() {
+	local pr_label="$1"
+	local pr_script="$2"
+	local pr_plist="$HOME/Library/LaunchAgents/${pr_label}.plist"
+	local _xml_pr_script _xml_pr_home
+	_xml_pr_script=$(_xml_escape "$pr_script")
+	_xml_pr_home=$(_xml_escape "$HOME")
+
+	local pr_plist_content
+	pr_plist_content=$(
+		cat <<PR_PLIST
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -1209,27 +1573,66 @@ setup_profile_readme() {
 </dict>
 </plist>
 PR_PLIST
-		)
+	)
 
-		if _launchd_install_if_changed "$pr_label" "$pr_plist" "$pr_plist_content"; then
-			print_info "Profile README update enabled (launchd, hourly)"
-		else
-			print_warning "Failed to load profile README update LaunchAgent"
-		fi
+	if _launchd_install_if_changed "$pr_label" "$pr_plist" "$pr_plist_content"; then
+		print_info "Profile README update enabled (launchd, hourly)"
 	else
-		# Linux: cron entry (hourly)
-		local _cron_pr_script
-		_cron_pr_script=$(_cron_escape "$pr_script")
-		(
-			crontab -l 2>/dev/null | grep -v 'aidevops: profile-readme-update' || true
-			echo "0 * * * * /bin/bash ${_cron_pr_script} update >> \"\$HOME/.aidevops/.agent-workspace/logs/profile-readme-update.log\" 2>&1 # aidevops: profile-readme-update"
-		) | crontab - 2>/dev/null || true
-		if crontab -l 2>/dev/null | grep -qF "aidevops: profile-readme-update" 2>/dev/null; then
-			print_info "Profile README update enabled (cron, hourly)"
-		else
-			print_warning "Failed to install profile README update cron entry"
-		fi
+		print_warning "Failed to load profile README update LaunchAgent"
+	fi
+	return 0
+}
+
+_install_profile_readme_scheduler() {
+	local pr_label="$1"
+	local pr_systemd="$2"
+	local pr_script="$3"
+	local pr_log="$4"
+
+	if [[ "$(uname -s)" == "Darwin" ]]; then
+		_install_profile_readme_launchd "$pr_label" "$pr_script"
+		return 0
+	fi
+
+	_install_scheduler_linux \
+		"$pr_systemd" \
+		"aidevops: profile-readme-update" \
+		"0 * * * *" \
+		"\"${pr_script}\" update" \
+		"3600" \
+		"$pr_log" \
+		"" \
+		"Profile README update enabled (hourly)" \
+		"Failed to install profile README update scheduler" \
+		"false" \
+		"true"
+	return 0
+}
+
+setup_profile_readme() {
+	local pr_script="$HOME/.aidevops/agents/scripts/profile-readme-helper.sh"
+	local pr_label="sh.aidevops.profile-readme-update"
+	if ! _profile_readme_ready "$pr_script"; then
+		return 0
 	fi
+
+	# Initialize profile repo if not already set up.
+	# Always run init — it's idempotent and handles:
+	#   - Fresh installs (no profile repo)
+	#   - Missing markers (injects them into existing README)
+	#   - Diverged history (repo deleted and recreated on GitHub)
+	#   - Already-initialized repos (returns early with no changes)
+	_run_profile_readme_init "$pr_script"
+
+	# Profile README auto-update scheduled job.
+	# Installed whenever gh CLI is available — the update script self-heals
+	# (discovers/creates the profile repo on first run via _resolve_profile_repo).
+	# macOS: launchd plist (hourly) | Linux: systemd timer or cron (hourly)
+	local pr_systemd="aidevops-profile-readme-update"
+	local pr_log="$HOME/.aidevops/.agent-workspace/logs/profile-readme-update.log"
+	mkdir -p "$HOME/.aidevops/.agent-workspace/logs"
+
+	_install_profile_readme_scheduler "$pr_label" "$pr_systemd" "$pr_script" "$pr_log"
 	return 0
 }
 
@@ -1315,27 +1718,29 @@ _uninstall_token_refresh_schtasks() {
 # Refreshes expired/expiring tokens every 30 min so sessions never hit
 # "invalid x-api-key". Also runs at load to catch tokens that expired
 # while the machine was off.
-# macOS: launchd plist | Linux/WSL: cron | Windows Git Bash: schtasks
-setup_oauth_token_refresh() {
-	local tr_script="$HOME/.aidevops/agents/scripts/oauth-pool-helper.sh"
-	local tr_label="sh.aidevops.token-refresh"
-	if ! [[ -x "$tr_script" ]] || ! [[ -f "$HOME/.aidevops/oauth-pool.json" ]]; then
-		return 0
+# macOS: launchd plist | Linux/WSL: systemd timer or cron | Windows Git Bash: schtasks
+_oauth_token_refresh_ready() {
+	local tr_script="$1"
+	if ! [[ -x "$tr_script" ]]; then
+		return 1
 	fi
+	if ! [[ -f "$HOME/.aidevops/oauth-pool.json" ]]; then
+		return 1
+	fi
+	return 0
+}
 
-	local tr_log_dir="$HOME/.aidevops/.agent-workspace/logs"
-	mkdir -p "$tr_log_dir"
-
-	if [[ "$(uname -s)" == "Darwin" ]]; then
-		local tr_plist="$HOME/Library/LaunchAgents/${tr_label}.plist"
-
-		local _xml_tr_script _xml_tr_home
-		_xml_tr_script=$(_xml_escape "$tr_script")
-		_xml_tr_home=$(_xml_escape "$HOME")
-
-		local tr_plist_content
-		tr_plist_content=$(
-			cat <<TR_PLIST
+_install_token_refresh_launchd() {
+	local tr_label="$1"
+	local tr_script="$2"
+	local tr_plist="$HOME/Library/LaunchAgents/${tr_label}.plist"
+	local _xml_tr_script _xml_tr_home
+	_xml_tr_script=$(_xml_escape "$tr_script")
+	_xml_tr_home=$(_xml_escape "$HOME")
+
+	local tr_plist_content
+	tr_plist_content=$(
+		cat <<TR_PLIST
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -1374,29 +1779,45 @@ setup_oauth_token_refresh() {
 </dict>
 </plist>
 TR_PLIST
-		)
+	)
 
-		if _launchd_install_if_changed "$tr_label" "$tr_plist" "$tr_plist_content"; then
-			print_info "OAuth token refresh enabled (launchd, every 30 min)"
-		else
-			print_warning "Failed to load token refresh LaunchAgent"
-		fi
+	if _launchd_install_if_changed "$tr_label" "$tr_plist" "$tr_plist_content"; then
+		print_info "OAuth token refresh enabled (launchd, every 30 min)"
+	else
+		print_warning "Failed to load token refresh LaunchAgent"
+	fi
+	return 0
+}
+
+setup_oauth_token_refresh() {
+	local tr_script="$HOME/.aidevops/agents/scripts/oauth-pool-helper.sh"
+	local tr_label="sh.aidevops.token-refresh"
+	if ! _oauth_token_refresh_ready "$tr_script"; then
+		return 0
+	fi
+
+	local tr_log_dir="$HOME/.aidevops/.agent-workspace/logs"
+	mkdir -p "$tr_log_dir"
+
+	if [[ "$(uname -s)" == "Darwin" ]]; then
+		_install_token_refresh_launchd "$tr_label" "$tr_script"
 	elif _is_windows; then
 		# Windows Git Bash / MINGW64 / MSYS2: use Task Scheduler (schtasks)
 		_install_token_refresh_schtasks "$tr_script" "$tr_log_dir"
 	else
-		# Linux / WSL: cron entry (every 30 min)
-		local _cron_tr_script
-		_cron_tr_script=$(_cron_escape "$tr_script")
-		(
-			crontab -l 2>/dev/null | grep -v 'aidevops: token-refresh' || true
-			echo "*/30 * * * * /bin/bash ${_cron_tr_script} refresh anthropic >> \"\$HOME/.aidevops/.agent-workspace/logs/token-refresh.log\" 2>&1; /bin/bash ${_cron_tr_script} refresh openai >> \"\$HOME/.aidevops/.agent-workspace/logs/token-refresh.log\" 2>&1 # aidevops: token-refresh"
-		) | crontab - 2>/dev/null || true
-		if crontab -l 2>/dev/null | grep -qF "aidevops: token-refresh" 2>/dev/null; then
-			print_info "OAuth token refresh enabled (cron, every 30 min)"
-		else
-			print_warning "Failed to install token refresh cron entry"
-		fi
+		# Linux / WSL without systemd: systemd timer or cron fallback
+		_install_scheduler_linux \
+			"aidevops-token-refresh" \
+			"aidevops: token-refresh" \
+			"*/30 * * * *" \
+			"\"${tr_script}\" refresh anthropic; \"${tr_script}\" refresh openai" \
+			"1800" \
+			"${tr_log_dir}/token-refresh.log" \
+			"" \
+			"OAuth token refresh enabled (every 30 min)" \
+			"Failed to install token refresh scheduler" \
+			"true" \
+			"true"
 	fi
 	return 0
 }
@@ -1413,8 +1834,13 @@ setup_repo_sync() {
 	local _repo_sync_installed=false
 	if _launchd_has_agent "com.aidevops.aidevops-repo-sync"; then
 		_repo_sync_installed=true
+	elif _launchd_has_agent "sh.aidevops.repo-sync"; then
+		_repo_sync_installed=true
 	elif crontab -l 2>/dev/null | grep -qF "aidevops-repo-sync"; then
 		_repo_sync_installed=true
+	elif command -v systemctl >/dev/null 2>&1 &&
+		systemctl --user is-enabled "aidevops-repo-sync.timer" >/dev/null 2>&1; then
+		_repo_sync_installed=true
 	fi
 	if [[ "$_repo_sync_installed" == "false" ]]; then
 		if [[ "$NON_INTERACTIVE" == "true" ]]; then