Module routing 

hq-core router: roles, presets, seats and a limit-aware fallback.

Config (<data_dir>/routing.json, owner-edited, hot-reloaded on each call):

{
  "seats": [{ "id": "box-claude", "node": "hatchery-box", "provider": "claude" }],
  "roles": {
    "dev":     { "preset": ["claude/opus:high", "codex/gpt-5:high"], "auto": true },
    "advisor": { "preset": ["codex/gpt-5:medium"], "auto": false }
  },
  "limit_cooldown_secs": 3600,
  "advisor": { "min_interval_secs": 300, "dedup_secs": 3600 }
}

A preset entry is provider/model[:effort]. A seat is one place a provider can run (a node + provider, optionally a named account). The router walks the role’s preset in order and, for each entry, the seats of that provider; a seat with a recent limit signal is skipped until a ready signal, a parsed reset time, or the cooldown passes. Signals are hints (screen heuristics): they only reorder and never delete a seat, and when every seat is limited the router still answers with the soonest-free one. The router recommends; it picks on its own only in roles with "auto": true.

Structs

AdviceGate

Advisor anti-noise gate: one advice per min_interval per advisor, and the same topic not again within dedup. Memory only (a restart forgets; that is acceptable noise).

AdvisorPolicy

Candidate

InventoryModel

One model a node’s provider CLI exposes (as reported by the node).

ModelRef

provider/model[:effort]

NodeInventory

Stored inventory row: one provider on one node.

ProviderInventory

What a node reports for one provider.

Recommendation

Role

RoutingConfig

Seat

SeatState

Latest limit knowledge per (node, provider), built from session signals.

Functions

clean_report

Validate a node’s report (bounded, plain identifiers). A bad provider, model or effort entry is dropped on its own; the rest of the report is kept.

fold_signals

Fold signals (oldest first) into per-(node, provider) state.

offered

A role preset entry is valid only if some node reports that provider/model (and effort).

ok_model_id

Model ids may carry a vendor path or tag (kimi-code/k3, name:tag, x@v).

parse_model_ref

parse_reset

“try again in 2 hours”, “in 45 minutes”: relative reset, capped at 8 days.

recommend

recommend_in

Like recommend, but only seats whose node reports the model count (when inventory is given).