autoloop: Triage

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

Self-diagnostic for the autoloop fleet. Cross-references registry.json, heartbeat.json files, launchctl list output, plist files, and (lightly) ~/.claude/projects JSONL transcripts to surface zombies, orphans, label collisions, multi-cwd contamination, stale bindings, and missing heartbeats.

Arguments

--json — emit structured JSON output instead of human-readable terminal report
--fix — apply SAFE auto-remediations only (see "What gets fixed" below)

Severity model

🔴 RED — known-broken state requiring action (zombie launchctl entry, multi-cwd contamination, label collision, contract file missing, cwd_drift_detected)
🟡 YELLOW — probably-OK but worth attention (pending-bind >1h, dead pid + recent heartbeat)
🟢 GREEN — healthy

Run

PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/marketplaces/cc-skills/plugins/autoloop}"
# shellcheck source=/dev/null
source "$PLUGIN_ROOT/scripts/triage-lib.sh"

JSON=false
FIX=false
for arg in "$@"; do
  case "$arg" in
    --json) JSON=true ;;
    --fix)  FIX=true  ;;
  esac
done

if [ "$FIX" = true ]; then
  loop_triage_fix
else
  if [ "$JSON" = true ]; then
    loop_triage_report --json
  else
    loop_triage_report
  fi
fi

What gets fixed automatically (`--fix`)

Only operations that are reversible OR have no live side effects:

Unload zombie launchctl entries — labels matching com.user.claude.loop.* with no registry record. Calls launchctl bootout gui/$(id -u)/<label> and removes the orphan plist file.
Prune /var/folders/* test entries — registry entries whose contract_path starts with /var/folders/ (mktemp leftovers from tests).

What --fix will NEVER do (intentionally — operator decision required):

Spawn claude --resume for any reason.
Auto-reclaim a loop with a live owner (use /autoloop:reclaim <loop_id> instead).
Modify a loop's bound_cwd or clear cwd_drift_detected (these mean the session went somewhere it shouldn't — only the operator can authorize recovery).
Delete heartbeat files or state directories.

Companion: automatic self-healing

heal-self.sh runs automatically on every fresh SessionStart hook fire (gated by content-hash so it does no work when the registry is unchanged). It archives entries with owner_session_id ∈ {unknown, unknown-session, '', pending-bind} older than 1 hour to ~/.claude/loops/registry.archive.jsonl. The archive is append-only and forensics-friendly.

Refs

Library: plugins/autoloop/scripts/triage-lib.sh
Companion script: plugins/autoloop/scripts/heal-self.sh

Post-Execution Reflection

Locate yourself. — Confirm this SKILL.md is the canonical file before any edit.
What failed? — Fix the instruction that caused it (e.g., a detection that produced false positives, a --fix op that wasn't actually safe).
What drifted? — Update if the registry schema, heartbeat fields, or launchctl output format changed.
Log it. — Evolution-log entry with trigger, fix, evidence.