Skip to content

sno-ai/sno-station-skills / skills/S-communication-and-handoff/rotate-agent/skill

rotate-agent

Verified

Quota-triggered failover from Claude Code, Codex, Cursor, Hermes or OpenClaw. When armed, it reads the sender quota and tries other-vendor models in place, then receiving agents in the configured order. Use when a long run must finish even if one vendor's quota runs out. Not a monitor for anything else.

FileKindSize
SKILL.mdskill md12.9 KB
scripts/rotate-agent-answer-providerexecutablescript3.9 KB
scripts/rotate-agent-preflightexecutablescript7.8 KB
scripts/rotate-agent-resumeexecutablescript12.9 KB
scripts/rotate-agent-resume.texecutablescript10.0 KB
scripts/rotate-agent-switchexecutablescript5.1 KB
scripts/rotate-agent-watchexecutablescript6.7 KB
scripts/selftest/fake-quotaexecutablescript267 B
scripts/selftest/run-selftest.shexecutablescript10.3 KB
scripts/selftest/switch-provider.texecutablescript15.7 KB

scripts/selftest/run-selftest.sh

View on GitHub
#!/usr/bin/env bash
# Self-test for the rotate-agent skill: exercises scripts/rotate-agent-watch against a fake quota
# command and checks the packaged SKILL.md. Touches nothing outside this skill.
set -Eeuo pipefail
HERE="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
SKILL="$(cd -- "$HERE/../.." && pwd)"
check_resume_text() {
  local text
  text="$(cat "$SKILL/SKILL.md")"
  if grep -Fq 'next_action=completed|unfinished|blocked' <<<"$text" &&
     grep -q 'Startup, readiness and release report the action unfinished' <<<"$text"; then
    printf 'PASS resume text separates recovery outcome from action completion\n'
  else
    printf 'FAIL resume text separates recovery outcome from action completion\n'
    return 1
  fi
}
if [[ "${1:-}" == resume-contract ]]; then check_resume_text; exit; fi
WATCH="$SKILL/scripts/rotate-agent-watch"
PREFLIGHT="$SKILL/scripts/rotate-agent-preflight"
FAKE="$HERE/fake-quota"
TMP="$(mktemp -d)"; trap 'rm -rf -- "$TMP"' EXIT
fail=0
# Recording stand-in for `sno observe` (the real tool uploads); FAKE_OBSERVE_EXIT makes it fail.
mkdir -p "$TMP/bin"
cat >"$TMP/bin/sno" <<'OBS'
#!/usr/bin/env bash
[[ "${1:-}" == observe ]] || exit 64
shift
printf '%s\n' "$*" >>"$OBSERVE_LOG"
exit "${FAKE_OBSERVE_EXIT:-0}"
OBS
chmod +x "$TMP/bin/sno"
export OBSERVE_LOG="$TMP/observe.log"; : >"$OBSERVE_LOG"
export PATH="$TMP/bin:$PATH"
REPO="$TMP/repo"; git init -q "$REPO"
git -C "$REPO" -c user.name=t -c user.email=t@t commit -q --allow-empty -m first
# In-place sed for GNU and BSD alike: <sed script> <file>
sed_i() { sed "$1" "$2" >"$2.new" && mv -- "$2.new" "$2"; }
check() { # name expected-prefix actual
  if [[ "$3" == "$2"* ]]; then printf 'PASS %s\n' "$1"; else printf 'FAIL %s: got %q\n' "$1" "$3"; fail=1; fi
}
for script in "$WATCH" "$PREFLIGHT"; do
  name="${script##*/}"
  if out=$("$script" --help 2>"$TMP/help.err"); then rc=0; else rc=$?; fi
  check "$name --help exits 0" "0" "$rc"
  check "$name --help prints usage on stdout" "usage: $name" "${out%%$'\n'*}"
  check "$name --help leaves stderr empty" "1" "$(test ! -s "$TMP/help.err" && printf 1 || printf 0)"
  if "$script" --bad-option >/dev/null 2>&1; then rc=0; else rc=$?; fi
  check "$name rejects an unknown option with exit 2" "1" "$((rc == 2))"
done
for option in --from --state --threshold-pct --quota-cmd; do
  if "$WATCH" "$option" >/dev/null 2>"$TMP/usage.err"; then rc=0; else rc=$?; fi
  check "watch $option without a value" '2 usage: rotate-agent-watch' "$rc $(head -n1 "$TMP/usage.err")"
done
for option in --from --to --model --provider --cwd --sender --quota-cmd; do
  if "$PREFLIGHT" "$option" >/dev/null 2>"$TMP/usage.err"; then rc=0; else rc=$?; fi
  check "preflight $option without a value" '2 usage: rotate-agent-preflight' "$rc $(head -n1 "$TMP/usage.err")"
done
export QUOTA_LOG="$TMP/quota.log" QUOTA_FIXTURES="$TMP/fixtures"
mkdir -p "$QUOTA_FIXTURES"
printf '%s\n' '{"ok":true,"agent":"hermes","model":"gpt-test","provider":"openai-codex","model_vendor":"openai","vendor":{"verdict":"short_only","tightest_window":{"used_pct":99.0,"seconds_to_reset":123}}}' >"$QUOTA_FIXTURES/sender.json"
printf '%s\n' '{"ok":true,"from":{"agent":"hermes","model":"gpt-test","provider":"openai-codex","vendor":"openai","verdict":"short_only"},"candidates":[{"agent":"hermes","model":"qwen-test","provider":"local-reason","vendor":"local:local-reason","in_place":true,"verdict":"unread"},{"agent":"claude-code","model":"sonnet-test","provider":"anthropic","vendor":"anthropic","in_place":false,"verdict":"go"}]}' >"$QUOTA_FIXTURES/pick.json"
run() {
  "$WATCH" --from "${FROM_OVERRIDE:-hermes}" --seat sender@host --state "$TMP/watch.state" --cwd "$REPO" --quota-cmd "$FAKE"
}
out=$(run)
check "crossing includes ordered unread and next-agent candidates" 'ROTATE from=hermes seat=sender@host remaining=1%' "$out"
[[ "$out" == *'"model":"qwen-test"'* && "$out" == *'"verdict":"unread"'* && "$out" == *'"agent":"claude-code"'* ]] || fail=1
check "a trigger does not claim a successful handoff" "0" "$(test -e "$TMP/watch.state" && printf 1 || printf 0)"
check "the sender-only read uses its own seat" '--agent hermes --seat sender@host --json' "$(head -n1 "$QUOTA_LOG")"
check "the crossing asks for the ordered handoff pick" '--pick handoff --from hermes --seat sender@host --json' "$(tail -n1 "$QUOTA_LOG")"
printf '%s\n' 'switched 2026-10-09T00:00:00Z model=qwen-test vendor=local:local-reason' >"$TMP/watch.state"
out=$(run)
check "a switched record permits the second crossing" "ROTATE from=hermes" "$out"
sed_i 's/short_only/wait/g;s/99.0/null/g' "$QUOTA_FIXTURES/sender.json"
out=$(run)
check "a direct jump to wait triggers the pick" "ROTATE from=hermes" "$out"
[[ "$out" == *'verdict=wait'* ]] || fail=1
sed_i 's/wait/owner_action/g' "$QUOTA_FIXTURES/sender.json"
check "owner action also triggers" "ROTATE from=hermes" "$(run)"
printf '%s\n' '{"ok":true,"candidates":[],"chosen":null}' >"$QUOTA_FIXTURES/pick.json"
check "no candidate keeps watching" "HOLD no-candidate" "$(run)"
sed_i 's/owner_action/go/g;s/used_pct":null/used_pct":95/g' "$QUOTA_FIXTURES/sender.json"
: >"$QUOTA_LOG"
check "healthy sender holds" "HOLD from=hermes remaining=5%" "$(run)"
check "healthy tick reads no other agent" "1" "$(wc -l <"$QUOTA_LOG" | tr -d ' ')"
for sender in claude-code codex cursor hermes openclaw; do
  check "accepts $sender sender" "HOLD from=$sender" "$(FROM_OVERRIDE="$sender" run)"
done
if "$WATCH" --from codex --to claude-code-code --seat sender@host --state "$TMP/x" --cwd "$REPO" --quota-cmd "$FAKE" >/dev/null 2>&1; then rc=0; else rc=$?; fi
check "removed --to is rejected" "2" "$rc"
printf 'rotated %s from=hermes to=claude-code remaining=1%% commits=1\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >"$TMP/watch.state"
check "real handoff is done until the receiver commits" 'DONE rotated' "$(run)"
git -C "$REPO" -c user.name=t -c user.email=t@t commit -q --allow-empty -m receiver
check "receiver progress completes recorded handoff" 'COMPLETE from=hermes to=claude-code' "$(run)"
check "completion event uses the real receiver agent id" '1' "$(grep -c 'handoff.complete --agent=claude-code ' "$OBSERVE_LOG")"
# Cursor uses the sender seat and the same ordered candidate mechanism as every agent.
rm -f "$TMP/watch.state"
printf '%s\n' '{"ok":true,"agent":"cursor","model":"gpt-test","provider":"openai-codex","vendor":{"verdict":"short_only","tightest_window":{"used_pct":99,"seconds_to_reset":123}}}' >"$QUOTA_FIXTURES/sender.json"
printf '%s\n' '{"ok":true,"from":{"agent":"cursor","model":"gpt-test","provider":"openai-codex","vendor":"openai","verdict":"short_only"},"candidates":[{"agent":"codex","model":"gpt-test","provider":"openai-codex","vendor":"openai","in_place":false,"verdict":"go"}]}' >"$QUOTA_FIXTURES/pick.json"
: >"$QUOTA_LOG"
out=$(FROM_OVERRIDE=cursor run)
check "a Cursor sender below the threshold requests rotation" 'ROTATE from=cursor seat=sender@host remaining=1%' "$out"
check "Cursor reads its own seat and then requests candidates" '--agent cursor --seat sender@host --json|--pick handoff --from cursor --seat sender@host --json' "$(paste -sd'|' "$QUOTA_LOG")"
check "Cursor retains the selected Codex receiver" 'codex' "$(sed 's/.*candidates=//' <<<"$out" | jq -r '.[0].agent')"
printf '%s\n' '{"ok":true,"from":{"agent":"claude-code","vendor":"anthropic"},"candidates":[{"agent":"cursor","model":"gpt-test","provider":"openai-codex","vendor":"openai","in_place":false,"verdict":"go"}]}' >"$QUOTA_FIXTURES/pick.json"
out=$(FROM_OVERRIDE=claude-code run)
check "Claude can choose a Cursor receiver" 'cursor' "$(sed 's/.*candidates=//' <<<"$out" | jq -r '.[0].agent')"
sed_i 's/used_pct":99/used_pct":98.5/' "$QUOTA_FIXTURES/sender.json"
out=$(FROM_OVERRIDE=cursor run)
check "Cursor fractional quota is compared by its whole part" 'ROTATE from=cursor seat=sender@host remaining=2%' "$out"
# Preflight requires cursor-agent, rather than the IDE launcher.
PF="$TMP/pfbin"; mkdir -p "$PF"
cat >"$PF/sno" <<'SNO'
#!/usr/bin/env bash
case "$*" in "reach --version") echo 2.1.0 ;; "reach seats --json") echo '{"address":"hand.repo@host"}' ;; *) exit 1 ;; esac
SNO
for c in tmux cursor codex; do printf '#!/usr/bin/env bash\nexit 0\n' >"$PF/$c"; done
chmod +x "$PF"/*
out=$(PATH="$PF:/usr/bin:/bin" "$PREFLIGHT" --from claude-code --to cursor --cwd "$REPO" --quota-cmd "$FAKE" || true)
check "preflight rejects an IDE launcher without the Cursor CLI" 'FAIL receiver-command: cursor is not on PATH' "$(grep -m1 FAIL <<<"$out")"
: >"$QUOTA_LOG"
out=$(PATH="$PF:/usr/bin:/bin" "$PREFLIGHT" --from cursor --to codex --cwd "$REPO" --sender hand.repo@host --quota-cmd "$FAKE" || true)
check "preflight reads Cursor quota for the sender seat" 'OK quota-to|--agent cursor --json --seat hand.repo@host' "$(grep -m1 quota-to <<<"$out")|$(head -n1 "$QUOTA_LOG")"
front="$(sed -n '1,/^---$/!d;p' "$SKILL/SKILL.md" | sed -n '2,$p')"
ok=1; grep -q '^name: rotate-agent$' <<<"$front" || ok=0
for p in subscription-quota-check heartbeat reach; do grep -q "name: $p" <<<"$front" || ok=0; done
check "9 SKILL.md frontmatter names unit and programs" "1" "$ok"
body="$(sed '1,/^---$/d' "$SKILL/SKILL.md")"
ok=1; grep -q 'rotate-agent-resume --to <agent> --cwd <checkout> --checkpoint <record> --work <work>' <<<"$body" && grep -q 'spawn --window' <<<"$body" || ok=0
check "10 fallback receiver is started by one command on a tmux window" "1" "$ok"
check_resume_text || fail=1
ok=1; grep -q 'A seat marked `stale`.*is not proof that its agent is gone' <<<"$body" || ok=0
check "12 stale seat is not death" "1" "$ok"
if "$PREFLIGHT" --from codex --to codex --cwd "$TMP" >/dev/null 2>&1; then rc=0; else rc=$?; fi
check "13 preflight rejects identical fixed agents" "2" "$rc"
out=$("$PREFLIGHT" --from codex --to claude-code --cwd "$TMP" --quota-cmd "$TMP/no-such-quota-cmd" || true)
check "14 preflight fails first on a missing tool" "FAIL tools: $TMP/no-such-quota-cmd is not on PATH" "$out"
ok=1; grep -q 'rotate-agent-preflight --from codex --to claude-code --cwd <checkout>' <<<"$body" && grep -q 'Do not arm on a `FAIL`' <<<"$body" || ok=0
check "15 skill runs the preflight before arming" "1" "$ok"
bash "$HERE/switch-provider.t" >"$TMP/switch.out" 2>&1 && printf 'PASS switch and provider behaviour\n' || { cat "$TMP/switch.out"; fail=1; }
bash "$SKILL/scripts/rotate-agent-resume.t" >"$TMP/resume.out" 2>&1 && printf 'PASS 16 rotate-agent-resume behaviour test\n' || { printf 'FAIL 16 rotate-agent-resume behaviour test\n'; sed 's/^/# /' "$TMP/resume.out"; fail=1; }
exit "$fail"
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall