Claude Skill

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 mo

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download sno-ai-sno-station-skills-skills_S-communication-and-handoff_rotate-agent_skill-8ff231c.zip · 32 KB

Install

skills CLI npx skills add https://github.com/sno-ai/sno-station-skills/tree/main/skills/S-communication-and-handoff/rotate-agent/skill
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install sno-ai-sno-station-skills@llmmart
Git git clone https://github.com/sno-ai/sno-station-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole sno-ai/sno-station-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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

seat who does
working agent (A) the agent executing the task registers; checkpoints after each task; hands off when ordered
watchman an agent with background execution and delivery of its results arms, reads ticks, walks candidates
receiver (B) an agent chosen by the pick starts 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.

line meaning watchman does
HOLD from=… remaining=N% threshold=T% above threshold keep watching
HOLD unreadable … sender quota unknown keep watching; report repeated failures
HOLD no-candidate … no available receiver sender continues; keep watching
ROTATE … verdict=… candidates=[…] low remaining share, or wait/owner_action walk the candidates below
DONE rotated … a real handoff was recorded wait for COMPLETE
COMPLETE … new commit after the recorded handoff stop 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.

Files (sno-station-skills)
  • scripts
    • selftest
      • fake-quota 267 B · in bundle
      • run-selftest.sh 9.3 KB
        Loading…
      • switch-provider.t 15.7 KB · in bundle
    • rotate-agent-answer-provider 3.9 KB · in bundle
    • rotate-agent-preflight 7.6 KB · in bundle
    • rotate-agent-resume 12.9 KB · in bundle
    • rotate-agent-resume.t 10 KB · in bundle
    • rotate-agent-switch 5.1 KB · in bundle
    • rotate-agent-watch 6.6 KB · in bundle
  • SKILL.md 12.9 KB
    ---
    name: rotate-agent
    description: "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
    
    | seat | who | does |
    |---|---|---|
    | working agent (A) | the agent executing the task | registers; checkpoints after each task; hands off when ordered |
    | watchman | an agent with background execution and delivery of its results | arms, reads ticks, walks candidates |
    | receiver (B) | an agent chosen by the pick | starts 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.
    
    | line | meaning | watchman does |
    |---|---|---|
    | `HOLD from=… remaining=N% threshold=T%` | above threshold | keep watching |
    | `HOLD unreadable …` | sender quota unknown | keep watching; report repeated failures |
    | `HOLD no-candidate …` | no available receiver | sender continues; keep watching |
    | `ROTATE … verdict=… candidates=[…]` | low remaining share, or `wait`/`owner_action` | walk the candidates below |
    | `DONE rotated …` | a real handoff was recorded | wait for COMPLETE |
    | `COMPLETE …` | new commit after the recorded handoff | stop 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.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.