← LeaderboardThe Skill Leaderboard

rotate-agent

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.

Published by sno-ai ↗sno-ai/sno-station-skills

Try your first task

A source-grounded starter task has not been verified for this skill yet.

SKILL.md

name: rotate-agentdescription: "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."requires:   programs:     - {name: subscription-quota-check, min_version: "1.0"}    - {name: heartbeat, min_version: "1.0"}    - {name: reach, min_version: "2.0"}  harness:     - {slot: 4.shell, need: required}    - {slot: 4.background-processes, need: required}    - {slot: 3.reader-to-agent-delivery, need: required}

rotate-agent

Needs: tmux, jq, GNU timeout, and sno with Reach, heartbeat and subscription-quota-check, plus the handoff skill. The provider-reading script also uses awk and OpenClaw's session exporter. Install programs through sno setup. A seat is a registered terminal address (see join-talk). The owner owns the work; the watchman reads ticks and acts on them, preferably from a seat other than the busy sender.

Rotation keeps one authorized long run working when its model's quota is low. Agent ids are claude-code, codex, cursor, hermes, openclaw. Selection belongs to sno subscription-quota-check --pick handoff: other-vendor models inside the sender first, then other agents in handoff_order. Never replace the returned order with your own. A Cursor quota reading belongs to one conversation, so --from cursor needs --sender <A-seat> on the preflight and --seat <A-seat> on the watch; without it the reading is unreadable and the watch holds. A Cursor receiver is always a new Cursor CLI seat on a tmux window (sno reach spawn cursor-agent --window). The trigger is the threshold read only; a quota error message from Cursor does not start a rotation.

Quota normally is read only on request or refusal. Asking to arm rotation authorizes these periodic sender reads. Only the sender is read on ordinary ticks; the full pick runs once at a crossing. No other process should poll quota.

Three seats

seatwhodoes
working agent (A)the agent executing the taskregisters; checkpoints after each task; hands off when ordered
watchmanan agent with background execution and delivery of its resultsarms, reads ticks, walks candidates
receiver (B)an agent chosen by the pickstarts on a tmux window; takes the same checkout and authority

Working agent: three lines added to its prompt

$join-talk
Keep the exact unfinished action and expected result in Next before undertaking it. At real task boundaries, before an orderly stop and before compaction run `sno handoff-checkpoint` (or the same explicit record path) and update Done, Next and the latest failed operation/target/error. Commit only if the owner authorized it.
When told to ROTATE, pause edits and run $handoff with the specified receiver kind, model and provider.

$join-talk and $handoff are the Codex form; in Claude Code and Cursor write /join-talk and /handoff.

Checkpoints limit lost progress when A cannot answer. Registration lets the watchman reach A. A seat marked stale is not proof that its agent is gone: check its terminal or process before treating it as dead.

Watchman: arm, read, act

The scripts ship under this skill's scripts/; use their full paths or put them on PATH. A next-agent candidate can be tested before arming:

rotate-agent-preflight --from codex --to claude-code --cwd <checkout> --sender <A-seat> --model <M> --provider <P>

It checks tools, checkout, sender registration, the two selected model quotas, and a trial receiver's fresh answer. The trial seat is removed. unread quota is available; actual start and answer decide whether it works. Do not arm on a FAIL: repair the named failure or try the next candidate. The preflight is not needed to read a tick.

Create a fresh empty log with mktemp "${TMPDIR:-/tmp}/heartbeat.XXXXXX" and a new state path under ${XDG_STATE_HOME:-$HOME/.local/state}/rotate-agent/<label>.state. Arming with Claude Code's tools (other harnesses use their own equivalents):

Bash({
  run_in_background: true,
  command: "sno heartbeat --interval 5 --max-hours 0 --label rotate-agent-<work> --log \"<LOG>\" \
    -- rotate-agent-watch --from <agent> --seat <A-seat> --threshold-pct 2 --state \"<STATE>\" --cwd \"<checkout>\""
})
Monitor({
  command: "tail --pid=<from the arm output> -F -n +1 \"<LOG>\"",
  persistent: true,
  description: "rotate-agent ticks"
})

Cursor has no Monitor: run the same sno heartbeat command from Cursor's shell and follow the reader instruction it prints for a Cursor conversation (the heartbeat skill says how ticks reach Cursor).

--max-hours 0 removes heartbeat's default 24-hour limit; use a finite value when requested. Hermes and OpenClaw instead run one background command per tick: sleep <interval-seconds>; sno heartbeat --label rotate-agent-<work> --max-ticks 1 -- rotate-agent-watch --from <agent> --seat <A-seat> --state <STATE> --cwd <checkout>. Re-arm after each native completion notice. Hermes delivers the notice at the next turn boundary; OpenClaw delivers during a turn. OpenClaw's command must run without an approval prompt for its completion notice to arrive. Prefer a separate watchman.

linemeaningwatchman does
HOLD from=… remaining=N% threshold=T%above thresholdkeep watching
HOLD unreadable …sender quota unknownkeep watching; report repeated failures
HOLD no-candidate …no available receiversender continues; keep watching
ROTATE … verdict=… candidates=[…]low remaining share, or wait/owner_actionwalk the candidates below
DONE rotated …a real handoff was recordedwait for COMPLETE
COMPLETE …new commit after the recorded handoffstop this heartbeat

Walk every candidate in order

Read candidates[], not just chosen. Keep the original model and raw provider from the triggering line's sender object (--pick's from). Log each failed operation, agent, model, seat and error; then take the next candidate. go, short_only and unread candidates are available.

For in_place:true, run:

rotate-agent-switch --agent <agent> --seat <A-seat> --model <M> --provider <P> --original-model <O> --original-provider <OP>

It polls the pane footer every three seconds. The entire first attempt has a 100-second deadline; recovery starts with a fresh 150-second deadline, shortened only if needed to keep the entire operation within 280 seconds. Timed-out commands are killed immediately. Each phase prints its elapsed seconds on stderr. Hermes is idle when the last 15 pane lines contain a line starting with ❯ and no msg=interrupt, including when the composer shows a rotating suggestion; OpenClaw must show connected | idle. It sends Hermes /model M --provider P, OpenClaw /model P/M, Cursor /model M through sno reach call <seat> <command> --raw, never as a queued model command. It waits for idle again and calls continue with at most 60 seconds. Confirmation requires exit status 0 and non-empty reply text; Reach does not return JSON here. Hermes and OpenClaw use rotate-agent-answer-provider --agent <agent> --seat <A-seat> --latest --with-model to read <provider> <model> from the last successful Hermes API call or the last OpenClaw assistant answer's runtime event. Unanswered background turns do not erase that result. Without --with-model, output remains the provider only. A switch needs a new assistant answer from P and the selected current model. A logged custom provider also matches a configured custom endpoint name when the answer model is M; it never substitutes for openai, openai-codex, codex, chatgpt, anthropic, claude, google, gemini, xai, grok, openrouter, deepseek, nvidia, zai, kimi or minimax. Only SWITCH OK counts. Then append switched <UTC-timestamp> model=<M> vendor=<V> to the state file. This does not stop the watch: the next tick reads the new model, and another crossing runs the pick again. Never write rotated for an in-place switch.

Failure restores O/OP with the same idle, raw command and confirmed-turn procedure. SWITCH FAIL restored=yes means try the next candidate with the sender still able to hand off. restored=no means all next-agent candidates use resume from disk.

For a next-agent candidate, map claude-code to launch kind claude, cursor to cursor-agent; the other launch kinds match their ids. Pass --model M and the raw --provider P to sno reach spawn, always with --window. Reach initializes an OpenClaw model while idle before sending its startup context.

When A can answer, send the order:

sno reach call <A-seat> "ROTATE: run the handoff skill now; receiver kind <kind>, model <M>, provider <P>, vendor <V>; spawn --window in the same checkout. Verify the receiver answer vendor before release. Report to <owner session>." --expect HANDOFF_RELEASED --timeout 280

The handoff skill verifies readiness without writes. Hermes/OpenClaw readiness must be attributed using rotate-agent-answer-provider --agent <agent> --seat <B-seat> --receipt <REACH-RECEIPT-id> with the call's deliveryReceipt. No provider or a wrong provider fails that candidate before A releases. Claude Code and Codex have fixed vendors. Cursor uses the integrated seat's concrete model/vendor reading. An uncertain release is not permission to start competing receivers: inspect the seat before proceeding. A known start or acknowledgement failure tries the next.

If the crossing was wait/owner_action, or restoring A failed, use:

sno rotate-agent-resume --to <agent> --cwd <checkout> --checkpoint <record> --work <work> --model <M> --provider <P> --report-to <owner session>

The record must belong to the same checkout. The command first uses its exact recorded vendor session identity with claude -p --resume <id> or codex exec resume <id> <prompt>; it never chooses an unrelated latest session. Missing identity skips only native resume. If native resume is unavailable, it rebuilds from the same readable brief, applicable Reach card and existing scoped memory retrieval in the original vendor when usable. Known exhausted quota skips both original-vendor entries and uses the selected other vendor. Unknown quota or authentication failure is not called exhausted quota. If no other vendor can execute, it retains the brief and says takeover was skipped and no recovery completed; a quota blocker does not mean task facts were lost.

MATCH/DRIFT are auxiliary checkout observations for reconciliation, not admission requirements. B reads the whole record and emits fresh HANDOFF_READY <nonce> without editing. The command checks the existing selected-provider information where applicable, then sends HANDOFF_RELEASE <nonce> and requires HANDOFF_RELEASED <nonce> from new receiver output before B writes. All calls use stored full-text call mail plus one short cue; no repeated Enter or second handshake. Call mail is transport-only and never an owned work card. Card-backed work preserves the original chain, actual receiver card recipient and Reply-To; direct owner work does not invent an original card. The recovery initiator uses its real authorization and never fabricates a response from an absent A. An uncertain release needs inspection of that receiver and Reach records: B may own the work, so never start another receiver. Reach's existing seat/receipt records suffice; there is no second per-work once file.

Output distinguishes resumed (the exact original conversation), rebuilt (new conversation; original conversation lost) and lost (essential next-step facts unrecoverable). Each is separate from next_action=completed|unfinished|blocked. Startup, readiness and release report the action unfinished; they never prove it completed. Completion requires the receiver's actual next-step result. B maintains the complete brief at its default <Sno profile>/station/handoff/<session-id>.md path for next-prompt and post-compaction injection, retaining the prior complete record.

B reports the actual next action result and earlier failure to the continuing destination in the brief (or --report-to). A missing optional observation or failed report delivery does not revoke B's ownership or let A resume competing task writes. After confirmed transfer append rotated <UTC-timestamp> from=<agent> to=<agent> remaining=<N>% commits=<count> with the count printed by the triggering tick. Only this real handoff ends rotation under that state path; another handoff uses a fresh label and state path.

If every candidate fails, report HOLD no-candidate; A continues when still able. Do not make a blind read or a changed model name into success. Hermes provider comes from the last successful API call in the receipt's turn span, not a subsequent background notice; OpenClaw comes from the runtime provider of that answer in its session export. Unknown attribution is failure, and independent work continues.