Skip to content

Business operating system for Claude Code — 57 skills, 21 agents, smart daemon. Unified inbox (WhatsApp/Email/Slack/Telegram), autonomous PR merge, full-AWS monitoring, revenue (Stripe+RevenueCat), e-commerce (Shopify), marketing (Klaviyo/Meta/GA4), voice (Bland/ElevenLabs), APM (Datadog/NewRelic/OTEL), YOLO mode.

fix(ops): cross-platform gh-orphan-killer for curl/api.github.com poll loops + live installer (#558)

Aurora Capitalb48307e11f71
diff --git a/claude-ops/hooks/gh-watch-guard.sh b/claude-ops/hooks/gh-watch-guard.sh
index defaccef..04c5b804 100755
--- a/claude-ops/hooks/gh-watch-guard.sh
+++ b/claude-ops/hooks/gh-watch-guard.sh
@@ -30,9 +30,11 @@ CMD=$(printf '%s' "$raw" | jq -r '(.tool_input.command // .command // empty)' 2>
# Collapse newlines so --watch / tight-loop patterns cannot be evaded by splitting lines.
CMD_ONELINE=$(printf '%s' "$CMD" | tr '\n\r' ' ')
-# Fast path: not a gh command, exit immediately
+# Fast path: not a gh command AND not a direct api.github.com call, exit immediately.
+# (curl/wget poll loops hit api.github.com/graphql with no `gh` token — they must still
+# reach Patterns 2-3 below, so don't short-circuit them out.)
case "$CMD" in
- *gh\ *|*gh-*) ;;
+ *gh\ *|*gh-*|*api.github.com*) ;;
*) exit 0 ;;
esac
@@ -60,33 +62,86 @@ EOF
exit 0
fi
-# --- Pattern 2: gh polling loops with sleep < 25s ---
-# Catches ANY while/until/for loop calling `gh api|pr|run|issue|search` whose smallest
-# sleep interval is under 25s — including deploy-watch loops:
-# until [ -n "$(gh run list --workflow=… )" ]; do sleep 15; done
-# `gh run list|view` is the same REST drain as `gh pr …`; "waiting for my deploy" is NOT
-# an exemption. The minimum sleep is parsed numerically so two-digit evasions (sleep 15,
-# sleep 20, sleep 24) are caught — the old single-digit-only regex let these through.
-# (2026-05-30: a sleep-15 `gh run list` deploy-watch loop drove REST to 0/5000.)
-if echo "$CMD_ONELINE" | grep -qE '(^|[^[:alnum:]_])(while|until|for)([^[:alnum:]_]|$).*gh[[:space:]]+(api|pr|run|issue|search)'; then
- # Extract every `sleep N` interval and take the minimum; a loop with sleep 30 AND
- # sleep 15 is judged by its tightest phase (15).
- MIN_SLEEP=$(echo "$CMD_ONELINE" | grep -oE 'sleep[[:space:]]+[0-9]+' | grep -oE '[0-9]+' | sort -n | head -1)
- # No explicit sleep in a gh loop = unbounded hammer → treat as 0.
- [ -z "$MIN_SLEEP" ] && MIN_SLEEP=0
- if [ "$MIN_SLEEP" -lt 25 ]; then
- emit_pre_tool_deny <<EOF
-BLOCKED: gh polling loop with sleep ${MIN_SLEEP}s (< 25s) detected.
+# Shared exemption: a loop that ONLY ever touches `rate_limit` is quota-exempt
+# (the /rate_limit endpoint does not consume quota) and is the legitimate way a
+# release waiter blocks until the bucket recovers. If the loop's only GitHub touch
+# is rate_limit, allow it. We approximate "only rate_limit" as: the command mentions
+# rate_limit AND does NOT also contain a quota-spending gh/api verb
+# (pr/run/issue/search/graphql/repos/commits/...).
+loop_is_rate_limit_only() {
+ echo "$CMD_ONELINE" | grep -q 'rate_limit' || return 1
+ # If it ALSO spends quota (merge/list/view/graphql/etc), it is NOT exempt.
+ if echo "$CMD_ONELINE" | grep -qE 'gh[[:space:]]+(pr|run|issue|search)[[:space:]]|graphql|/(repos|commits|pulls|issues|actions|search)/|pullRequest|mergePullRequest'; then
+ return 1
+ fi
+ # `gh api` spends quota unless every invocation targets /rate_limit.
+ if echo "$CMD_ONELINE" | grep -qE 'gh[[:space:]]+api'; then
+ if echo "$CMD_ONELINE" | grep -oE 'gh[[:space:]]+api[^;|&)]+' | grep -qvE '(rate_limit|/rate_limit)'; then
+ return 1
+ fi
+ fi
+ return 0
+}
+
+# --- Pattern 2: gh polling loops at ANY sleep interval ---
+# Catches ANY while/until/for/seq loop calling `gh api|pr|run|issue|search` regardless
+# of sleep length. Previously only sleep < 25s was blocked, but on 2026-06-11 a
+# `for i in $(seq 1 20); do sleep 45; curl … ; gh pr merge … ; done` merge-watcher
+# evaded with sleep 45 (≥25) and pinned REST to 0 for hours. The interval doesn't
+# matter — a long-lived gh loop is a leak; use the Monitor tool or a single
+# run_in_background `until` instead. Only a rate_limit-only loop is exempt.
+if echo "$CMD_ONELINE" | grep -qE '(^|[^[:alnum:]_])(while|until|for|seq)([^[:alnum:]_]|$).*gh[[:space:]]+(api|pr|run|issue|search)'; then
+ if ! loop_is_rate_limit_only; then
+ emit_pre_tool_deny <<'EOF'
+BLOCKED: gh polling loop detected (for/while/until + gh api|pr|run|issue|search).
The 5000/hr REST quota is shared across this session, background daemons, the overnight
-sync cron, and every other gh process. A loop at sleep 15 burns ~240 calls/hr and stacks
-with siblings — one such loop drove REST to 0/5000 on 2026-05-30, blocking prod tooling.
+sync cron, and every other gh process. A long-lived gh loop — at ANY sleep interval —
+stacks with siblings and drains the bucket. On 2026-06-11 a `seq … sleep 45 … gh pr merge`
+merge-watcher ran for hours and pinned REST to 0, blocking releases. A bigger sleep does
+NOT make it safe; the loop itself is the leak.
+
+Fix:
+ • For ONE condition (PR merged / CI green): a single `until … ; do sleep 30; done` run
+ via run_in_background (NOT looped in the foreground), or the Monitor tool.
+ • For multiple PRs/runs: ONE GraphQL query (separate 5000/hr bucket) listing them all.
+ • To block until quota recovers: poll `/rate_limit` only (quota-exempt).
+
+Source: ~/Projects/claude-ops/claude-ops/hooks/gh-watch-guard.sh
+EOF
+ exit 0
+ fi
+fi
+
+# --- Pattern 3: curl/wget poll loops hitting api.github.com ---
+# The class the `gh`-only guard above can never see: a `for`/`while`/`until`/`seq`
+# loop with a `sleep` that calls api.github.com (REST or /graphql) directly via curl
+# or wget. On 2026-06-11 an `until s=$(curl -sS … api.github.com/graphql … pullRequest …);
+# … do sleep 60; done` merge-watcher evaded BOTH prior patterns (no `gh`, sleep 60)
+# and helped pin the shared quota to 0. Block any such loop at ANY sleep interval.
+# Exempt: a loop whose only api.github.com touch is /rate_limit (quota-exempt).
+if echo "$CMD_ONELINE" | grep -qE '(^|[^[:alnum:]_])(while|until|for|seq)([^[:alnum:]_]|$)' \
+ && echo "$CMD_ONELINE" | grep -q 'api.github.com' \
+ && echo "$CMD_ONELINE" | grep -qE '(^|[^[:alnum:]_])sleep([^[:alnum:]_]|$)'; then
+ # If every api.github.com reference is the rate_limit endpoint, allow it.
+ if echo "$CMD_ONELINE" | grep -qE 'api\.github\.com/rate_limit' \
+ && ! echo "$CMD_ONELINE" | grep -qE 'api\.github\.com/(graphql|repos|commits|pulls|issues|actions|search)|pullRequest|mergePullRequest'; then
+ : # rate_limit-only waiter — legitimate, allow.
+ else
+ emit_pre_tool_deny <<'EOF'
+BLOCKED: curl/wget poll loop hitting api.github.com detected.
-This covers deploy-watch loops too: \`until gh run list/view … ; do sleep <25; done\` is
-forbidden. Waiting on an Actions deploy is NOT an exemption.
+A `for`/`while`/`until` loop with `sleep` that calls api.github.com (REST or /graphql)
+directly is the same shared-quota drain as `gh` — and at ANY sleep interval. On 2026-06-11
+an `until s=$(curl … api.github.com/graphql … pullRequest …); … do sleep 60; done`
+merge-watcher evaded the gh-only guard (no `gh` token, sleep 60) and pinned the shared
+REST/GraphQL quota to 0 for hours, blocking releases.
-Fix: bump to \`sleep 30\`+ (run_in_background) or use the Monitor tool (handles ≥25s natively).
-For multi-PR/run state, prefer ONE GraphQL query (separate 5000/hr bucket).
+Fix:
+ • For ONE condition: a single `until … ; do sleep 30; done` via run_in_background, or
+ the Monitor tool — NOT a foreground loop left running for hours.
+ • For multiple PRs/runs: ONE GraphQL query (separate 5000/hr bucket) covering them all.
+ • To block until quota recovers: poll `api.github.com/rate_limit` only (quota-exempt).
Source: ~/Projects/claude-ops/claude-ops/hooks/gh-watch-guard.sh
EOF
diff --git a/claude-ops/scripts/gh-orphan-killer.sh b/claude-ops/scripts/gh-orphan-killer.sh
index 9d0e7ffe..64adde48 100755
--- a/claude-ops/scripts/gh-orphan-killer.sh
+++ b/claude-ops/scripts/gh-orphan-killer.sh
@@ -1,50 +1,181 @@
#!/bin/bash
-# Kills orphan `gh pr checks ... --watch` after 5 min; `gh run watch` only after
-# 2000s so deploy monitors (default watcher timeout 1800s in ops-deploy-monitor.sh)
-# are not SIGKILL'd mid-watch. Runs every 60s while active. Idempotent.
+# gh-orphan-killer — reaps GitHub-API rate-limit-burning orphan processes.
#
-# Triggered by: SessionStart hook (foreground guarded by pidfile to avoid duplicates).
+# Two classes of target:
+# (1) `gh pr checks ... --watch` orphans after 5 min, `gh run watch` after 2000s
+# (so deploy monitors with the default 1800s watcher timeout aren't SIGKILL'd
+# mid-watch).
+# (2) STALE / ORPHANED GitHub-API POLLING LOOPS — the curl/gh `for`/`while`/`until`
+# loops that the PreToolUse guard couldn't catch because they (a) hit
+# api.github.com/graphql directly via curl, or (b) used sleep >= 25s. Two such
+# merge-watcher loops pinned the shared REST quota to 0 for hours on 2026-06-11.
+# A real merge-watcher finishes fast; an orphaned (ppid==1) or long-running
+# (>10 min) one is a leak — reap it.
#
-# Source of truth: ~/Projects/claude-ops/claude-ops/scripts/gh-orphan-killer.sh
+# Run modes:
+# gh-orphan-killer.sh # legacy persistent daemon (while-true, sleep 60).
+# # Used by the macOS launchd job + SessionStart nohup.
+# gh-orphan-killer.sh --once # single sweep then exit. Used by the Linux
+# # systemd --user timer (oneshot every 3 min).
+#
+# Cross-platform: portable `ps` columns. On Linux we get `etimes` (elapsed seconds)
+# directly; on macOS (BSD ps) etimes is unavailable, so we parse `etime` (D-HH:MM:SS)
+# and convert to seconds.
+#
+# Source of truth: ~/Projects/claude-ops/claude-ops/claude-ops/scripts/gh-orphan-killer.sh
+
+set -uo pipefail
-set -euo pipefail
+MODE="loop"
+if [ "${1:-}" = "--once" ]; then
+ MODE="once"
+fi
PIDFILE="${TMPDIR:-/tmp}/gh-orphan-killer.pid"
LOG="${HOME}/.claude/logs/gh-orphan-killer.log"
mkdir -p "$(dirname "$LOG")"
-# Singleton: if another instance is running with a fresh pidfile, exit
-if [ -f "$PIDFILE" ]; then
- prev_pid=$(cat "$PIDFILE" 2>/dev/null || echo "")
- if [ -n "$prev_pid" ] && kill -0 "$prev_pid" 2>/dev/null; then
- exit 0
+# Singleton ONLY for the persistent loop mode. The --once sweep is short-lived and
+# self-terminating, so it must not be blocked by (or clobber) the daemon's pidfile —
+# the systemd timer and the legacy daemon can safely coexist.
+if [ "$MODE" = "loop" ]; then
+ if [ -f "$PIDFILE" ]; then
+ prev_pid=$(cat "$PIDFILE" 2>/dev/null || echo "")
+ if [ -n "$prev_pid" ] && kill -0 "$prev_pid" 2>/dev/null; then
+ exit 0
+ fi
fi
+ echo $$ > "$PIDFILE"
+ trap 'rm -f "$PIDFILE"' EXIT
fi
-echo $$ > "$PIDFILE"
-trap 'rm -f "$PIDFILE"' EXIT
PR_CHECKS_WATCH_MAX_AGE=300
# Above ops-deploy-monitor default watcher_timeout_seconds (1800) with headroom
GH_RUN_WATCH_MAX_AGE=2000
+# A genuine merge-watcher finishes in well under 10 min; beyond that it's a leak.
+POLL_LOOP_MAX_AGE=600
-while true; do
- # `ps -eo pid,etimes,command` — etimes = elapsed seconds since process start
- killed=0
+# Convert BSD `etime` ([[DD-]HH:]MM:SS) to seconds. Linux ps gives etimes directly so
+# this is only the macOS fallback path.
+etime_to_secs() {
+ local e="$1" days=0 hms
+ case "$e" in
+ *-*) days="${e%%-*}"; hms="${e#*-}" ;;
+ *) hms="$e" ;;
+ esac
+ local IFS=:; set -- $hms
+ local h=0 m=0 s=0
+ if [ "$#" -eq 3 ]; then h="$1"; m="$2"; s="$3"
+ elif [ "$#" -eq 2 ]; then m="$1"; s="$2"
+ elif [ "$#" -eq 1 ]; then s="$1"; fi
+ # strip leading zeros to avoid octal interpretation
+ echo $(( 10#${days:-0}*86400 + 10#${h:-0}*3600 + 10#${m:-0}*60 + 10#${s:-0} ))
+}
+
+# Emit "pid ppid etimes args" rows portably. Prefer Linux `etimes` (integer seconds);
+# fall back to BSD `etime` and convert.
+ps_rows() {
+ if ps -eo pid,ppid,etimes,args >/dev/null 2>&1; then
+ ps -eo pid=,ppid=,etimes=,args= 2>/dev/null
+ else
+ # macOS / BSD: no etimes column — emit etime and convert downstream.
+ ps -eo pid=,ppid=,etime=,args= 2>/dev/null | while read -r pid ppid etime rest; do
+ [ -z "$pid" ] && continue
+ secs=$(etime_to_secs "$etime")
+ printf '%s %s %s %s\n' "$pid" "$ppid" "$secs" "$rest"
+ done
+ fi
+}
+
+is_self() {
+ # Never target our own pid or that of the ps/awk/grep pipeline we spawn.
+ [ "$1" = "$$" ] || [ "$1" = "$PPID" ]
+}
+
+sweep() {
+ local killed=0
+
+ # ── Class 1: gh --watch orphans (unchanged behavior) ──────────────────────────
while read -r pid etimes max_age command; do
[ -z "$pid" ] && continue
[[ "$etimes" =~ ^[0-9]+$ ]] || continue
[[ "$max_age" =~ ^[0-9]+$ ]] || continue
+ is_self "$pid" && continue
if [ "$etimes" -gt "$max_age" ]; then
- echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) killing orphan pid=$pid age=${etimes}s max=${max_age}s: $command" >> "$LOG"
+ echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) killing orphan pid=$pid age=${etimes}s max=${max_age}s: ${command:0:200}" >> "$LOG"
kill -9 "$pid" 2>/dev/null || true
killed=$((killed + 1))
fi
- done < <(ps -eo pid,etimes,command 2>/dev/null | awk -v prmax="$PR_CHECKS_WATCH_MAX_AGE" -v runmax="$GH_RUN_WATCH_MAX_AGE" '
- /gh pr checks .*--watch/ && !/awk|grep/ { print $1, $2, prmax, substr($0, index($0,$3)) }
- /gh run watch/ && !/awk|grep/ { print $1, $2, runmax, substr($0, index($0,$3)) }
+ done < <(ps_rows | awk -v prmax="$PR_CHECKS_WATCH_MAX_AGE" -v runmax="$GH_RUN_WATCH_MAX_AGE" '
+ # cols: pid ppid etimes args...
+ {
+ pid=$1; etimes=$3;
+ # reconstruct cmdline from $4..$NF
+ cmd=""; for(i=4;i<=NF;i++){ cmd=cmd (i>4?" ":"") $i }
+ }
+ cmd ~ /awk|grep|gh-orphan-killer/ { next }
+ cmd ~ /gh pr checks .*--watch/ { print pid, etimes, prmax, cmd; next }
+ cmd ~ /gh run watch/ { print pid, etimes, runmax, cmd; next }
')
- [ "$killed" -gt 0 ] && echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) killed $killed orphan(s)" >> "$LOG"
+ # ── Class 2: stale/orphaned GitHub-API polling loops ──────────────────────────
+ # Kill when ALL hold:
+ # • cmdline hits api.github.com OR (gh + one of pr/run/api), AND
+ # • cmdline has a loop construct (for/while/until/seq) with a sleep, AND
+ # • it is orphaned (ppid==1) OR long-running (> POLL_LOOP_MAX_AGE).
+ # Hard EXCLUDE (never kill): self/guard/grep/ps; any 'rate_limit' poller
+ # (quota-exempt, legitimate release waiters); claude/node/MCP processes (only
+ # /bin/bash|/bin/sh shells running the loop); anything under a 'do-release' path.
+ while read -r pid ppid etimes command; do
+ [ -z "$pid" ] && continue
+ [[ "$pid" =~ ^[0-9]+$ ]] || continue
+ [[ "$etimes" =~ ^[0-9]+$ ]] || continue
+ is_self "$pid" && continue
+ if [ "$ppid" = "1" ] || [ "$etimes" -gt "$POLL_LOOP_MAX_AGE" ]; then
+ reason="orphan(ppid=1)"
+ [ "$ppid" != "1" ] && reason="stale(age=${etimes}s>${POLL_LOOP_MAX_AGE}s)"
+ echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) killing gh-api poll-loop pid=$pid ppid=$ppid $reason: ${command:0:200}" >> "$LOG"
+ kill -9 "$pid" 2>/dev/null || true
+ killed=$((killed + 1))
+ fi
+ done < <(ps_rows | awk '
+ {
+ pid=$1; ppid=$2; etimes=$3;
+ cmd=""; for(i=4;i<=NF;i++){ cmd=cmd (i>4?" ":"") $i }
+ }
+ # ── hard excludes ──
+ cmd ~ /gh-orphan-killer|gh-watch-guard/ { next } # the killer/guard itself
+ cmd ~ /[ \/]awk |[ \/]grep |[ \/]ps / || cmd ~ /awk$|grep$|ps$/ { next } # the pipeline
+ # rate_limit-only pollers are quota-exempt (mirrors gh-watch-guard); do not skip
+ # when the same cmdline also spends quota (graphql/gh api/etc).
+ cmd ~ /rate_limit/ \
+ && cmd !~ /api\.github\.com\/(graphql|repos|commits|pulls|issues|actions|search)/ \
+ && cmd !~ /pullRequest|mergePullRequest/ \
+ && cmd !~ /gh +(pr|run|issue|search)/ \
+ && (cmd !~ /gh +api/ || cmd ~ /gh +api[^;|&]*(rate_limit|\/rate_limit)/) \
+ { next }
+ cmd ~ /do-release/ { next } # release waiters
+ cmd ~ /(^|\/)(claude|node|python[0-9.]*|mcp)([ \/]|$)/ { next } # not shells
+ # only target real shells running the loop
+ cmd !~ /(^|\/)(bash|sh|dash|zsh)([ \/]|$)/ { next }
+ # ── github signal ──
+ github = (cmd ~ /api\.github\.com/) || (cmd ~ /gh +(api|pr|run|issue|search)/)
+ github != 1 { next }
+ # ── loop + sleep signal ──
+ hasloop = (cmd ~ /(^|[^[:alnum:]_])(for|while|until|seq)([^[:alnum:]_]|$)/)
+ hassleep = (cmd ~ /(^|[^[:alnum:]_])sleep[ ]+[0-9]/)
+ (hasloop && hassleep) { print pid, ppid, etimes, cmd }
+ ')
+
+ [ "$killed" -gt 0 ] && echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) killed $killed target(s) [$MODE]" >> "$LOG"
+}
+if [ "$MODE" = "once" ]; then
+ sweep
+ exit 0
+fi
+
+while true; do
+ sweep
sleep 60
done
diff --git a/claude-ops/scripts/install-gh-orphan-killer.sh b/claude-ops/scripts/install-gh-orphan-killer.sh
new file mode 100755
index 00000000..6234cc43
--- /dev/null
+++ b/claude-ops/scripts/install-gh-orphan-killer.sh
@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# install-gh-orphan-killer.sh — install the GitHub-API orphan-killer sweeper.
+#
+# Cross-platform, runs UNPRIVILEGED (no sudo):
+# • Linux → systemd --user timer (oneshot every 3 min) in ~/.config/systemd/user/
+# • macOS → launchd LaunchAgent (StartInterval 180s) in ~/Library/LaunchAgents/
+#
+# The unit invokes `gh-orphan-killer.sh --once` (single sweep then exit). This is the
+# periodic reaper for stale/orphaned `gh`/`curl api.github.com` poll loops that the
+# PreToolUse guard (hooks/gh-watch-guard.sh) couldn't block in time. Idempotent —
+# safe to re-run after a plugin upgrade.
+#
+# Usage:
+# bash scripts/install-gh-orphan-killer.sh
+# KILLER_PATH=/abs/path/to/gh-orphan-killer.sh bash scripts/install-gh-orphan-killer.sh
+#
+# By default the killer path is resolved to THIS script's sibling
+# (scripts/gh-orphan-killer.sh) via its real, committed location — so the unit points
+# at the repo checkout, not a transient symlink that can drop on reinstall.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+KILLER_PATH="${KILLER_PATH:-$SCRIPT_DIR/gh-orphan-killer.sh}"
+
+if [[ ! -f "$KILLER_PATH" ]]; then
+ echo "ERROR: killer script not found at $KILLER_PATH" >&2
+ echo " Pass KILLER_PATH=<abs path to gh-orphan-killer.sh> explicitly." >&2
+ exit 1
+fi
+chmod +x "$KILLER_PATH" 2>/dev/null || true
+
+OS="$(uname -s)"
+
+case "$OS" in
+ Linux)
+ UNIT_DIR="$HOME/.config/systemd/user"
+ mkdir -p "$UNIT_DIR"
+
+ # Substitute the killer path into the committed service template.
+ sed "s|__KILLER_PATH__|$KILLER_PATH|g" \
+ "$SCRIPT_DIR/systemd/gh-orphan-killer.service" > "$UNIT_DIR/gh-orphan-killer.service"
+ cp "$SCRIPT_DIR/systemd/gh-orphan-killer.timer" "$UNIT_DIR/gh-orphan-killer.timer"
+
+ echo "Installed:"
+ echo " $UNIT_DIR/gh-orphan-killer.service (ExecStart=/bin/bash $KILLER_PATH --once)"
+ echo " $UNIT_DIR/gh-orphan-killer.timer (every 3 min, Persistent=true)"
+
+ systemctl --user daemon-reload
+ systemctl --user enable --now gh-orphan-killer.timer
+
+ echo ""
+ echo "Armed. Verify with:"
+ echo " systemctl --user list-timers | grep gh-orphan"
+ echo " systemctl --user status gh-orphan-killer.service"
+ ;;
+
+ Darwin)
+ AGENT_DIR="$HOME/Library/LaunchAgents"
+ LABEL="com.claude-ops.gh-orphan-killer"
+ PLIST="$AGENT_DIR/$LABEL.plist"
+ mkdir -p "$AGENT_DIR"
+ mkdir -p "$HOME/.claude/logs"
+
+ cat > "$PLIST" <<PLIST_EOF
+<?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">
+<dict>
+ <key>Label</key><string>$LABEL</string>
+ <key>ProgramArguments</key>
+ <array>
+ <string>/bin/bash</string>
+ <string>$KILLER_PATH</string>
+ <string>--once</string>
+ </array>
+ <key>StartInterval</key><integer>180</integer>
+ <key>RunAtLoad</key><true/>
+ <key>Nice</key><integer>10</integer>
+ <key>StandardErrorPath</key><string>$HOME/.claude/logs/gh-orphan-killer.launchd.err</string>
+</dict>
+</plist>
+PLIST_EOF
+
+ echo "Installed: $PLIST (StartInterval 180s → /bin/bash $KILLER_PATH --once)"
+ # Reload idempotently.
+ launchctl unload "$PLIST" 2>/dev/null || true
+ launchctl load "$PLIST"
+ echo ""
+ echo "Armed. Verify with:"
+ echo " launchctl list | grep gh-orphan-killer"
+ ;;
+
+ *)
+ echo "ERROR: unsupported OS '$OS' — only Linux (systemd) and macOS (launchd) are supported." >&2
+ exit 1
+ ;;
+esac
diff --git a/claude-ops/scripts/systemd/gh-orphan-killer.service b/claude-ops/scripts/systemd/gh-orphan-killer.service
new file mode 100644
index 00000000..285752bd
--- /dev/null
+++ b/claude-ops/scripts/systemd/gh-orphan-killer.service
@@ -0,0 +1,10 @@
+[Unit]
+Description=gh-orphan-killer — single sweep reaping stale/orphaned GitHub-API poll loops
+Documentation=https://github.com/Lifecycle-Innovations-Limited/claude-ops
+
+[Service]
+Type=oneshot
+# __KILLER_PATH__ is substituted by install-gh-orphan-killer.sh to the committed
+# repo path (e.g. ~/Projects/claude-ops/claude-ops/claude-ops/scripts/gh-orphan-killer.sh).
+ExecStart=/bin/bash __KILLER_PATH__ --once
+Nice=10
diff --git a/claude-ops/scripts/systemd/gh-orphan-killer.timer b/claude-ops/scripts/systemd/gh-orphan-killer.timer
new file mode 100644
index 00000000..98810696
--- /dev/null
+++ b/claude-ops/scripts/systemd/gh-orphan-killer.timer
@@ -0,0 +1,12 @@
+[Unit]
+Description=Sweep for stale/orphaned GitHub-API poll loops every 3 minutes
+
+[Timer]
+OnBootSec=1min
+OnUnitActiveSec=3min
+Unit=gh-orphan-killer.service
+AccuracySec=15s
+Persistent=true
+
+[Install]
+WantedBy=timers.target