Repository navigation
Summary
SuperDispatch v0.0.1 is the first release. The changelog's main item is a production deploy: pushing a vX.Y.Z tag deploys it to the production host. The deploy script copies the store, builds the image, recreates the service and checks health, a token from Accounts, the hub and the loop's first sweep. A release that fails a check is replaced by the previous one, with the store's copy restored if the schema moved. smoke.sh repeats the checks at any time, and rollback.sh returns to the release before the deployed one. Releases also check that forge CI passed for the tag's commit and publish notes on GitHub.
The service itself places cards. For each ready card on an opted-in board, it filters agents, scores the rest and asks SuperPipeline to hold the card for the winner for 60 seconds. If the hold lapses, it holds the card for each runner-up in turn for 30 seconds each, up to three holds in all, and then leaves it to any matching agent. Every decision is recorded with all its candidates. Boards are served in fair rounds so a busy board does not take every free agent, and an agent has only one live hold at a time. Sweeps run every 30 seconds, and a card.ready event from the relay places that card at once. Other additions are station filters on AgentPod's capability registry, the stage's history from SuperWitness in the score, roster suggestions and supply proposals (advice only, since SuperDispatch changes no roster or station), and a labelled dataset with a learned model. Lint and architecture checks were also tightened, with no change to what the service does.
For operators, the deploy opts in no board, so nothing is placed until you opt boards in through /v1/boards. The wider candidate set (SUPERDISPATCH_CANDIDATES=all), the dispatch policy (SUPERDISPATCH_POLICY=on) and learned routing (SUPERDISPATCH_LEARNED) all stay off until you set them. Learned routing needs data first, so start it in shadow. The on setting acts only past a gate of 500 rows, 100 shadow decisions and a 5 percent margin, and otherwise places by the formula and logs why.
Users on opted-in boards will see cards held for one agent at a time and passed down the runner-up list if the hold lapses. A card whose agents are all busy now waits for the
Highlights
- A production deploy: a
vX.Y.Ztag deploys the tag to the production host through its
forced-command key (deploy/production/release.sh). It takes an online copy of the store,
builds the tag's image, recreates the service, and checks/healthz, a token from Accounts with
the service's own credential, the hub, and the loop's first sweep; a release that fails a check
is replaced by the one that ran before, with the store's copy when the schema moved.
deploy/production/smoke.shrepeats the checks at any time, androllback.shputs back the
release before the deployed one. No board is opted in by the deploy, and the wider candidate
set, the dispatch policy and learned routing stay off until the operator sets them. - The start line names the candidate set and the dispatch policy beside learned routing, and the
loop logs its first sweep once (loop: first sweep, <n> boards opted in, <n> unread), so a
deploy can see it running with no board opted in. - Supply proposals: advice for a person when a lane goes unplaced for want of supply, kept with
the roster suggestions and listed by kind (GET /v1/suggestions?kind=).change-model(an
agent turned away only for its model),move-to-host(another station in AgentPod's registry
has what the lane's stations lack),add-station(nobody has it) andraise-capacity(every
capable agent at its board's concurrency). Each names its evidence, its target, its estimated
effect and the verb a person would use. SuperDispatch changes no station and files no request. - Learned routing, off by default. Every settled decision is now exported as labelled rows, one
per candidate (GET /v1/dataset, schema 1: filter results, score terms, stage history, tier,
board, stage, capability, hour, pool load, and a label fromwon-claimed,won-expired,
won-claimed-by-other,lost-claimed,lost,void).POST /v1/models/trainfits a small
logistic regression on it (no dependency, deterministic) and stores it as a version with its
holdout AUC, accuracy, log loss and calibration (GET /v1/models).
SUPERDISPATCH_LEARNED=shadowrecords what the latest model would have chosen beside each
decision without changing it, andGET /v1/models/:id/shadow-reportcompares the two against
outcomes.onholds the model's choice only past a gate (SUPERDISPATCH_LEARNED_MIN_ROWS, 500;
SUPERDISPATCH_LEARNED_MIN_SHADOW, 100;SUPERDISPATCH_LEARNED_MARGIN_PCT, 5), and otherwise
places by the formula and logs why. It needs data first: run it in shadow. - Station filters: a stage's
placement(isolation, models, tools, credentials) filters
candidates on AgentPod's capability registry, rejecting withisolation-too-weak,
model-mismatch,tool-missingorcredential-missingand recording what the station lacks.
Off for a stage that states nothing; unchecked when the registry cannot be read. Settings
SUPERDISPATCH_STATION_FILTERS(on/off) andSUPERDISPATCH_MIN_PROOF. - Code-quality ratchets (
docs/code-quality.md): lint is type-aware oxlint (with
oxlint-tsgolint) whose per-rule counts may fall but never rise, and the architecture test also
refuses a run-time import cycle and a source file over 1,000 lines. No change to what the
service does. - The service skeleton: it starts, checks its settings, opens its store and answers a health
check. - Placement: for each ready card on an opted-in board it filters every agent (on AgentPod's
roster, SuperPipeline's own eligibility, a ready station, idle on every board, not a recent
no-show), scores the rest (load, then success rate on the board, then least recently used),
asks SuperPipeline to hold the card for the winner for 60 seconds, and records the decision with
every candidate. What became of the card (claimed, claimed by another, expired, superseded) is
settled on the next pass. - Tiered holds: a card is held for the winner (60 seconds), then, if the hold lapses, for each
runner-up in turn (30 seconds each, up to three holds in all), then left to any matching agent.
Every step is a decision labelled with its tier. Settings:SUPERDISPATCH_RUNNER_UP_SECONDS,
SUPERDISPATCH_TOP_K. - Fairness across boards: a sweep places one card from each opted-in board in turn, longest
waiting first, so a busy board does not take every free agent (SUPERDISPATCH_FAIRNESS). - One live hold per agent (
holding-another): a second hold for an agent that can claim one card
at a time could only lapse and count against it as a no-show. Load leaves the score; the policy
is nowidle-success-lru@2. - Roster suggestions, advice only: after each sweep, the decisions of the last day flag a lane
with one agent on the roster for its capability, one whose agents keep being unhealthy or
no-shows, or one where a card waited 30 minutes with nobody eligible. Each is
add-agent-to-board(with the workspace's agents that have the capability and are not on the
board) orlane-single-point(nobody to add), with the decisions that bear it out. Read them on
GET /v1/suggestions, dismiss one withPOST /v1/suggestions/:id/dismiss. SuperDispatch never
edits a roster: a person makes the change. Settings:SUPERDISPATCH_SUGGEST_EVERY_SECONDS,
SUPERDISPATCH_SUGGEST_WINDOW_HOURS,SUPERDISPATCH_STALL_MINUTES. Each decision now records
the capability its stage asked for, and whether each agent off the roster has it. - A card whose candidates are all busy waits for the next pass instead of being recorded
none-eligibleand left alone for five minutes (waiting-on-load). Before, on a board where
every agent had work in hand, a freed agent pulled the next card before SuperDispatch looked
again, so nothing on a loaded board was ever placed. - History in the score: with
SUPERWITNESS_URLset, each candidate's record at the card's stage
(SuperWitness's finished runs there: outcome rate and verdict pass rate, recency-weighted,
neutral below a minimum sample) ranks first, and is recorded on each candidate. SuperWitness
absent or failing leaves the score as before. Settings:SUPERWITNESS_AUDIENCE,
SUPERDISPATCH_HISTORY_DAYS,SUPERDISPATCH_HISTORY_MIN_SAMPLE,
SUPERDISPATCH_HISTORY_HALF_LIFE_DAYS. The policy is nowidle-stage-success-lru@3. - A wider candidate set, off until the operator turns it on: with
SUPERDISPATCH_CANDIDATES=all,
agents that claim with their own token (no bridge row on the board) become candidates once
SuperPipeline reports their load and health (GET /v1/agents/load), judged by the same filters.
The roster and SuperPipeline both give one shape,{agentId, inFlight, capacity, healthy, lastSeenAt, source}; health and idle (inFlight < capacity) are read from it, and every
candidate record carries itssource(rosterordirect).roster, the default, places
exactly as before. - The dispatch policy, off until the operator turns it on: with
SUPERDISPATCH_POLICY=on, each
candidate the card's grant does not already refuse is checked against the workspace's dispatch
policy in Accounts (POST /api/policy/decide, scopepolicy:decide), once a pass per agent and
board stage. A deny rejects it aspolicy-denied, with Accounts' reasons on the record. A policy
limit counts the holds SuperDispatch made for the agent in the window (limit:<id>). When
Accounts cannot answer, it fails closed unless Accounts last said the workspace has no policy
(policy-unread).off, the default, places exactly as before. - A sweep of every opted-in board every 30 seconds, and a look at a board as soon as the event
relay delivers one of its events. - The operator API: opt a board in or out (
/v1/boards), and read the decisions
(/v1/decisions). - A container image, and a staging deploy that stays off until the host is ready.
- The placement window: opting a board in sets its window on SuperPipeline
(SUPERDISPATCH_PLACEMENT_WINDOW_SECONDS, 10 by default) and opting out sets none; a
card.readyfrom the relay places that card at once with the board's cached roster, which every
sweep refreshes. An agent SuperPipeline reports at its board's concurrency is waited for
(waiting-on-load) even while its station reads idle. - Releases run on the suite's shared release workflow: a
vX.Y.Ztag checks that forge CI passed
for the tag's commit, deploys it to production and publishes release notes on GitHub.
Changes
Docs
- What SuperDispatch is, the rulings it implements, and the rules for working here (fd4476c)
- What the first slice places, what it needs of the others, the operator API (e4bbfd6)
- Tiers, fairness and the one-hold rule (7e324b1)
- Roster suggestions are advice only (756996f)
- The candidate set and the load shape (8f1b10a)
- The dispatch policy filter (7cf3fbc)
- The code-quality ratchets (d590742)
- Supply proposals, and the AgentPod verb a hand-off would need (9bda820)
- Learned routing (8937b49)
Tests
- Characterize the composition root and the store's open error (13fd475)
- No client can change a station or file a supply request (e7c8622)
Chores
- Forge runs the checks and the advisory review (4b1b011)
Other
- Initial README and licence
Co-Authored-By: Claude Opus 5.5 noreply@anthropic.com (49d8193)
- The service skeleton (4093e02)
- An image, and a staging deploy that stays off until the host is ready (56abd8e)
- Adopt the suite's shared release workflow (5d1b80e)
- Sync the shared kit (a first release's notes) (b1a9edd)
- Re-sync the shared release workflow (17da911)
- Re-sync the shared release workflow (scripts from the workflow's commit) (004f9ac)
- Re-sync (deploy_from_release, estate #139) (dd8f40e)
- Re-sync (no private names in the synced files) (e922974)
- Re-sync the shared release workflow (4e3cf68)
- AgentPod's audience, the sweep and the reservation window (4cfafda)
- Opted-in boards, and what a decision needs to become a labelled example (faf82cb)
- SuperPipeline, AgentPod and Accounts (6f32c00)
- Filter, score and decide (ed96c2a)
- Settle, place, reserve and record, on a sweep (f795612)
- The relay's nudge and the operator API; main wires the loop (586617f)
- The runner-up window, top k and the fairness rule (ebd3c48)
- A decision's tier and step, and a card's ladder (a36e77b)
- Tiered holds, one live hold per agent, fairness across boards (a80ca0d)
- Climb each card's ladder, and place every board's cards in fair rounds (a1eb267)
- Roster suggestions, one per kind, board and stage, and the capability a decision's stage asked for (5110cb1)
- Suggest roster changes for lanes with one candidate, unreliable candidates or a stalled card (b8c897f)
- Compute the roster suggestions after a sweep, from the store alone; no client can edit a roster (1fe2f01)
- List, read and dismiss roster suggestions (cd7ac26)
- A card whose candidates are all busy waits, unrecorded (21d269d)
- SuperWitness's finished runs at a board stage (783a437)
- History at the stage ranks first in the score (8b1b90f)
- SUPERDISPATCH_CANDIDATES, roster or all, roster by default (040ab28)
- One shape for an agent's load and health, from either source (0552d19)
- A wider candidate set, behind the setting (701efe6)
- Station filters on AgentPod's capability registry (e05eec2)
- SUPERDISPATCH_POLICY, off or on, off by default (44ddc4f)
- Accounts' dispatch policy decision, read strictly (f0cad4b)
- The holds made for an agent since a time, what a policy limit counts (03d7b80)
- A policy filter, policy-denied, on the verdict it is given (b3faaa1)
- Ask the dispatch policy per candidate, cached per pass (a72dc9a)
- Type-aware oxlint with a per-rule ratchet (ed03ba6)
- No run-time import cycle, no source file over 1,000 lines (f3ec758)
- Clear the two findings in shipped source that change nothing (79005b7)
- Recount the baseline on main after the station and policy filters (b74d042)
- A registry row keeps its occupant, harness and runtime (ee55fc2)
- Supply proposals, advice when a lane lacks supply (6878d19)
- Roster suggestions and supply proposals in one sync, in their own module (a6955e2)
- Store, routes: list suggestions by kind
Co-Authored-By: Claude Opus 5.5 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_017y1PuoCFjP31uXyhLB6Hnr (d65a8f2)
- Models, shadow entries, and settled decisions oldest first (ff31553)
- The labelled dataset, one row per settled decision and candidate (1271790)
- A learned scorer fitted offline, the shadow report and the gate (2224990)
- SUPERDISPATCH_LEARNED, off, shadow or on, and its gate (551d7ca)
- Loop, routes: learned routing in shadow and behind the gate, and its operator API
Co-Authored-By: Claude Opus 5.5 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_017y1PuoCFjP31uXyhLB6Hnr (5e3dcea)
- An agent at its board's concurrency is load, even with an idle station (3f50ae6)
- Placement window: set it on opt-in, place a card.ready at once
Opting a board in sets its placement window on SuperPipeline
(SUPERDISPATCH_PLACEMENT_WINDOW_SECONDS, 10 by default), opting out
sets none, and every pass brings a board's window in line once a
process (retried after a wait when refused). A card.ready delivered by
the relay places that card alone and at once, with the board's roster
from a cache the sweep refreshes (in the background for a board with
nothing to place), so the placement does not wait on AgentPod's
station probes. The runner moves to loop/runner.ts.
Co-Authored-By: Claude Opus 5.5 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_017y1PuoCFjP31uXyhLB6Hnr (8106841)
- Sync the kit, hooks at fixed paths (9488423)
- Log the first sweep, and name the candidate set and policy at start (67b7f0c)
- Deploy a tag to the production host, v0.0.1 (2ebe204)
Checked at the tag: main's CI result could not be read.