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/rotate-agent-preflight

View on GitHub
#!/usr/bin/env bash
# rotate-agent-preflight — prove, before the heartbeat is armed, that a rotation from one
# agent vendor to the other can actually happen in this checkout: the tools exist, the
# receiver's command is installed, both quotas can be read, and a receiver seat of the
# `--to` vendor can be spawned here, answers a call, and is torn down again. Every check
# prints one line, `OK <check>` or `FAIL <check>: <what> -> <what to do>`; the first FAIL
# stops the run. Exit 0 ready, 1 not ready, 2 bad usage.
set -Eeuo pipefail

usage() {
  local status="${1:-2}"
  cat >&"$((status == 0 ? 1 : 2))" <<'USAGE'
usage: rotate-agent-preflight --from claude-code|codex|cursor|hermes|openclaw --to <agent> [--model <M>] [--provider <P>] --cwd <checkout>
                              [--sender <seat-address>] [--quota-cmd <cmd>]
prints one line per check: OK <check> | FAIL <check>: <what> -> <what to do>
USAGE
  exit "$status"
}

MODEL="" PROVIDER="" FROM="" TO="" CWD="" SENDER="" QUOTA_CMD=(sno subscription-quota-check)
while [[ $# -gt 0 ]]; do
  case "$1" in
    --from) [[ $# -ge 2 ]] || usage; FROM="$2"; shift 2 ;;
    --model) [[ $# -ge 2 ]] || usage; MODEL="$2"; shift 2 ;;
    --provider) [[ $# -ge 2 ]] || usage; PROVIDER="$2"; shift 2 ;;
    --to) [[ $# -ge 2 ]] || usage; TO="$2"; shift 2 ;;
    --cwd) [[ $# -ge 2 ]] || usage; CWD="$2"; shift 2 ;;
    --sender) [[ $# -ge 2 ]] || usage; SENDER="$2"; shift 2 ;;
    --quota-cmd) [[ $# -ge 2 ]] || usage; QUOTA_CMD=("$2"); shift 2 ;;
    -h|--help) usage 0 ;;
    *) printf 'rotate-agent-preflight: unknown option %s\n' "$1" >&2; usage ;;
  esac
done
[[ "$FROM" =~ ^(claude-code|codex|cursor|hermes|openclaw)$ && "$TO" =~ ^(claude-code|codex|cursor|hermes|openclaw)$ && "$FROM" != "$TO" && -n "$CWD" ]] || usage

KIND="$TO"
case "$TO" in claude-code) KIND=claude ;; cursor) KIND=cursor-agent ;; esac
[[ "$TO" != hermes && "$TO" != openclaw || ( -n "$MODEL" && -n "$PROVIDER" ) ]] || usage
HERE="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
DEADLINE=$((SECONDS + 285))
bounded() {
  local cap="$1" left=$((DEADLINE - SECONDS)); shift
  (( left > 0 )) || return 1
  (( left >= cap )) || cap="$left"
  timeout "$cap" "$@"
}
SEAT="preflight.rotate-agent@$(hostname -s | tr '[:upper:]' '[:lower:]')"
readonly SEAT
readonly ROOT="${SNO_REACH_STATE_ROOT:-${SNO_REACH_ROOT:-$HOME/.local/state/sno-reach}}"
readonly STARTUP_SECONDS=90

ok() { printf 'OK %s\n' "$1"; }
fail() { # check what what-to-do
  printf 'FAIL %s: %s -> %s\n' "$1" "$2" "$3"
  exit 1
}

# 1. Tools this skill and the handoff run on.
for tool in "${QUOTA_CMD[0]}" jq tmux sno timeout; do
  command -v "$tool" >/dev/null || fail tools "$tool is not on PATH" "install it (sno setup installs sno, with heartbeat and subscription-quota-check as sno subcommands)"
done
version="$(bounded 10 sno reach --version 2>/dev/null || true)"
[[ "$version" =~ ^([0-9]+)\. && ${BASH_REMATCH[1]} -ge 2 ]] || fail tools "sno reach --version printed '${version:-nothing}', need 2.0 or newer" "update Reach with sno setup"
ok tools

# 2. The receiver vendor's command, and the checkout it will work in.
command -v "$KIND" >/dev/null || fail receiver-command "$TO is not on PATH" "install the $TO CLI on this machine"
ok receiver-command
[[ -d "$CWD" ]] && git -C "$CWD" rev-parse --show-toplevel >/dev/null 2>&1 || fail checkout "$CWD is not a git work tree" "pass the checkout the working agent uses"
ok checkout

# 3. The sender must be reachable, or the order at ROTATE has nowhere to go.
if [[ -n "$SENDER" ]]; then
  bounded 10 sno reach seats --json 2>/dev/null | jq -e --arg a "$SENDER" 'select(.address == $a)' >/dev/null ||
    fail sender-seat "$SENDER is not in sno reach seats" "have the working agent run join-talk in $CWD, then rerun"
  ok sender-seat
fi

# 4. Both quotas readable now; the receiver must have headroom or there is nobody to rotate to.
read_verdict() {
  local agent="$1" out args=(--agent "$1" --json)
  if [[ "$agent" == "$FROM" && -n "$SENDER" ]]; then args+=(--seat "$SENDER"); fi
  if [[ "$agent" == "$TO" && -n "$MODEL" ]]; then args+=(--model "$MODEL"); fi
  out="$(bounded 60 "${QUOTA_CMD[@]}" "${args[@]}")" || printf 'rotate-agent-preflight: quota read failed agent=%s; inspecting verdict\n' "$agent" >&2
  jq -r '.vendor.verdict // "unknown"' <<<"$out" 2>/dev/null || printf 'unknown\n'
}
verdict="$(read_verdict "$FROM")"
[[ "$verdict" =~ ^(go|short_only|wait|owner_action|unread)$ ]] || fail quota-from "$FROM quota reads '$verdict'" "read the sender model before arming"
ok quota-from
verdict="$(read_verdict "$TO")"
[[ "$verdict" =~ ^(go|short_only|unread)$ ]] || fail quota-to "$TO quota reads '$verdict'" "try the next candidate"
ok quota-to

# 5. A live receiver of the --to vendor in this checkout: spawn on a tmux seat, wait for
#    its startup turn, make it answer a nonce, tear it down. A first run of a vendor in a
#    directory stops at its trust prompt; that is the user's key to press, not ours.
pane=""
cleanup() {
  local rc=$?
  trap - EXIT
  DEADLINE=$((DEADLINE + 10)) # Leave time to remove the trial seat.
  [[ -z "$pane" ]] || bounded 5 tmux kill-session -t "$pane" 2>/dev/null || true
  [[ ! -f "$ROOT/$SEAT/reachable.json" ]] || bounded 5 sno reach unregister --as "$SEAT" >/dev/null 2>&1 || true
  exit "$rc"
}
trap cleanup EXIT
[[ ! -f "$ROOT/$SEAT/reachable.json" ]] || fail receiver-seat "$SEAT is still registered from an earlier run" "run: sno reach unregister --as $SEAT"
bounded 10 sno reach init --as "$SEAT" --name preflight >/dev/null 2>&1 || fail receiver-seat "sno reach init --as $SEAT refused" "run it by hand and read its message"
spawn=(sno reach spawn "$KIND" --as "$SEAT" --cwd "$CWD" --window)
[[ -z "$MODEL" ]] || spawn+=(--model "$MODEL")
[[ -z "$PROVIDER" ]] || spawn+=(--provider "$PROVIDER")
spawned="$(bounded 150 "${spawn[@]}" 2>&1)" ||
  fail receiver-seat "sno reach spawn $TO --window refused: ${spawned##*$'\n'}" "fix what it names, then rerun"
pane="$(jq -r '.identity.value' "$ROOT/$SEAT/reachable.json")"
# The seat's startup turn is over when its terminal has been quiet for ten seconds.
bounded "$STARTUP_SECONDS" sno reach watch "$SEAT" --idle 10 --timeout "$STARTUP_SECONDS" >/dev/null 2>&1 ||
  fail receiver-start "$TO kept printing for ${STARTUP_SECONDS}s after spawn" "open $TO in $CWD by hand and see what it is doing"
if tmux capture-pane -p -t "$pane" | grep -qi 'trust'; then
  fail receiver-trust "$TO stopped at its trust prompt in $CWD" "open $TO once in $CWD by hand, accept the prompt, exit, then rerun"
fi
nonce="PREFLIGHT_$(od -An -N4 -tx1 /dev/urandom | tr -d ' \n')"
answer="$(bounded 120 sno reach call "$SEAT" "Reply with exactly $nonce and nothing else." --expect "$nonce" --timeout 120)" ||
  fail receiver-answer "$TO did not answer a call" "try the next candidate"
if [[ "$TO" == hermes || "$TO" == openclaw ]]; then
  receipt="$(jq -er 'select(.verified == true) | .deliveryReceipt | select(type == "string" and length > 0)' <<<"$answer")" || receipt=''
  actual=''
  if [[ -n "$receipt" ]]; then
    actual="$(bounded 20 "$HERE/rotate-agent-answer-provider" --agent "$TO" --seat "$SEAT" --receipt "$receipt")" || actual=''
  fi
  if [[ -z "$actual" || "$actual" != "$PROVIDER" ]]; then
    printf 'rotate-agent-preflight: operation=answer seat=%s command=call error=wrong-or-unknown-provider expected=%s actual=%s\n' "$SEAT" "$PROVIDER" "${actual:-unknown}" >&2
    fail receiver-answer "provider was ${actual:-unknown}, expected $PROVIDER" "try the next candidate"
  fi
elif [[ "$TO" == cursor ]]; then
  current="$(bounded 20 sno subscription-quota-check --agent cursor --seat "$SEAT" --json)" || current='{}'
  if [[ "$(jq -r '.model // empty' <<<"$current")" != "$MODEL" ||
        ( -n "$PROVIDER" && "$(jq -r '.provider // empty' <<<"$current")" != "$PROVIDER" ) ]]; then
    fail receiver-answer "Cursor did not answer on $MODEL/$PROVIDER" "try the next candidate"
  fi
fi
ok receiver-answer
printf 'READY from=%s to=%s cwd=%s\n' "$FROM" "$TO" "$CWD"
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 CodeCodexUnverifiedInstall
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