Skip to content

akiiwa-games/AgentCompass / skills/agent-compass

agent-compass

Unverified

Multi-agent task router and subscription quota scheduler. Choose owner, model and effort, outbound authorization, advisor use, and continuation for delegated work. Reads local usage and effective account policy, profiles the task with the configured System-One scorer, then allocates a compatible worker. Use for independent worker or advisor work; ordinary local execution needs no routing.

FileKindSize
SKILL.mdskill md5.6 KB
agents/openai.yamlconfig427 B
calibration/README.mdmarkdown55.2 KB
calibration/arena_capture.pyscript14.0 KB
calibration/community.pyscript25.2 KB
calibration/five_axis.pyscript196.4 KB
calibration/measurements.pyscript68.4 KB
calibration/refresh.pyscript48.6 KB
calibration/series.pyscript10.2 KB
calibration/sources.pyscript24.1 KB
calibration/tiers.pyscript14.6 KB
grok-bot/.gitignoreother47 B
grok-bot/dependency_patch.pyscript4.5 KB
grok-bot/install_cli.pyscript3.6 KB
grok-bot/test-recovery.mjsscript8.6 KB
grok-bot/test_install_cli.pyscript4.1 KB
grok-bot/upstream.jsonconfig3.4 KB
references/accounts.jsonconfig155.9 KB
references/classifier-cases.jsonconfig21.5 KB
references/dispatch-lifecycle.mdmarkdown37.7 KB
references/dispatch-rules.mdmarkdown11.3 KB
references/effort-matching.mdmarkdown5.1 KB
references/fast-modes.mdmarkdown3.5 KB
references/five-axis-scores.jsonconfig3.1 MB
references/gemini-decisions-api.mdmarkdown2.9 KB
references/grok-bot.mdmarkdown13.0 KB
references/herdr.mdmarkdown5.1 KB
references/jev-api.mdmarkdown1.6 KB
references/level-3-conversion.jsonconfig2.4 KB
references/model-capabilities.jsonconfig3.6 KB
references/model-capabilities.mdmarkdown14.6 KB
references/parent-address-gate.mdmarkdown10.1 KB
references/plan-templates.jsonconfig13.2 KB
references/provider-discovery.mdmarkdown11.5 KB
references/provider-usage.mdmarkdown4.1 KB
references/public-data.jsonconfig816 B
references/public-measurements.jsonconfig1.3 MB
references/roll-reference.mdmarkdown26.7 KB
references/router-internals.mdmarkdown94.5 KB
references/task-classifier.mdmarkdown6.1 KB
references/user-scores.jsonconfig6.8 KB
references/work-kinds.mdmarkdown4.7 KB
references/worker-communication.mdmarkdown2.1 KB
scripts/account_fleet.pyscript32.9 KB
scripts/account_state.pyscript22.2 KB
scripts/accounts_override.pyscript14.8 KB
scripts/allocator.pyscript19.8 KB
scripts/antigravity_plan.pyscript18.7 KB
scripts/antigravity_telemetry.pyscript5.1 KB
scripts/auto_bundles.pyscript31.3 KB
scripts/axis_scores.pyscript40.3 KB
scripts/caller_input.pyscript3.0 KB
scripts/candidate_eval.pyscript54.0 KB
scripts/candidate_ranking.pyscript9.5 KB
scripts/capability_catalog.pyscript8.0 KB
scripts/check_router_contract.pyscript2.8 KB
scripts/conftest.pyscript2.5 KB
scripts/cwd_policy.pyscript1.5 KB
scripts/data_age.pyscript1.5 KB
scripts/decision_ledger.pyscript18.9 KB
scripts/demo_plan.pyscript6.3 KB
scripts/dispatch_fallback.pyscript40.3 KB
scripts/dispatch_flow.pyscript63.1 KB
scripts/dispatch_ground_truth.pyscript43.5 KB
scripts/dispatch_registry.pyscript130.8 KB
scripts/entry.pyscript1.7 KB
scripts/env_vars.pyscript580 B
scripts/fast_modes.pyscript2.5 KB
scripts/fixtures/grok-api-responses.jsonconfig907 B
scripts/fixtures/reference-accounts.jsonconfig26.9 KB
scripts/grok_bot_paths.pyscript1005 B
scripts/host_herdr.pyscript16.8 KB
scripts/host_placement.pyscript9.4 KB
scripts/host_policy.pyscript10.1 KB
scripts/launch_failures.pyscript5.9 KB
scripts/launch_values.pyscript12.3 KB
scripts/ledger_snapshot.pyscript11.1 KB
scripts/live_models.pyscript21.1 KB
scripts/model_latch.pyscript7.6 KB
scripts/model_resolution.pyscript18.0 KB
scripts/override_store.pyscript2.2 KB
scripts/plan_state_residue.pyscript5.0 KB
scripts/provider_inventory.pyscript128.2 KB
scripts/provider_retry.pyscript34.6 KB
scripts/public_data.pyscript59.2 KB
scripts/quota_economy.pyscript38.0 KB
scripts/quota_exhaustion.pyscript5.9 KB
scripts/quota_overrides.pyscript25.6 KB
scripts/quota_pools.pyscript29.8 KB
scripts/reference_provenance.pyscript32.3 KB
scripts/released_names.pyscript3.8 KB
scripts/roll.pyscript106.3 KB
scripts/route_judge.pyscript83.5 KB
scripts/route_simulation.pyscript26.3 KB
scripts/router_test_support.pyscript6.7 KB
scripts/run_grok_bot.pyscript18.8 KB
scripts/scorer_client.pyscript55.2 KB
scripts/stage_help.pyscript5.8 KB
scripts/state_upgrade.pyscript24.0 KB
scripts/subscription_cli.pyscript3.6 KB
scripts/task_intake.pyscript33.6 KB
scripts/test_account_identity.pyscript7.1 KB
scripts/test_account_state.pyscript63.3 KB
scripts/test_accounts_override.pyscript30.1 KB
scripts/test_allocator.pyscript94.2 KB
scripts/test_antigravity_plan.pyscript13.2 KB
scripts/test_applicable_quota.pyscript9.1 KB
scripts/test_auto_bundles.pyscript10.8 KB
scripts/test_billing_routing_policy.pyscript9.9 KB
scripts/test_cadence_count.pyscript32.2 KB
scripts/test_calibration_units.pyscript27.0 KB
scripts/test_capability_catalog.pyscript5.0 KB
scripts/test_decision_ledger.pyscript8.5 KB
scripts/test_demo_plan.pyscript3.4 KB
scripts/test_derived_state.pyscript21.6 KB
scripts/test_dispatch.pyscript352.4 KB
scripts/test_dispatch_answers.pyscript14.8 KB
scripts/test_dispatch_fallback.pyscript53.2 KB
scripts/test_entry.pyscript1.6 KB
scripts/test_fast_modes.pyscript9.9 KB
scripts/test_five_axis.pyscript290.1 KB
scripts/test_five_axis_economy.pyscript105.0 KB
scripts/test_fleet_parity.pyscript15.6 KB
scripts/test_grok_bot.pyscript47.7 KB
scripts/test_ground_truth_recording.pyscript68.8 KB
scripts/test_herdr.pyscript14.1 KB
scripts/test_host_policy.pyscript24.6 KB
scripts/test_launch_values.pyscript8.0 KB
scripts/test_metered_usd.pyscript60.4 KB
scripts/test_model_resolution.pyscript9.2 KB
scripts/test_named_route_facts.pyscript28.6 KB
scripts/test_native_hosts.pyscript6.0 KB
scripts/test_new_user_fleet.pyscript3.3 KB
scripts/test_no_hardcode_classification.pyscript75.1 KB
scripts/test_no_legacy_scoring.pyscript6.5 KB
scripts/test_override_store.pyscript2.3 KB
scripts/test_plan_says_why.pyscript44.9 KB
scripts/test_provider_inventory.pyscript83.2 KB
scripts/test_provider_names.pyscript126.0 KB
scripts/test_provider_pools.pyscript14.2 KB
scripts/test_public_data.pyscript93.5 KB
scripts/test_quota_exhaustion.pyscript5.6 KB
scripts/test_rate_limit_windows.pyscript6.3 KB
scripts/test_record_says_why.pyscript26.5 KB
scripts/test_reference_provenance.pyscript16.7 KB
scripts/test_refresh_entry.pyscript110.7 KB
scripts/test_released_names.pyscript4.1 KB
scripts/test_reset_priority.pyscript4.8 KB
scripts/test_roll_answers.pyscript44.7 KB
scripts/test_roll_notifications.pyscript10.4 KB
scripts/test_route_judge.pyscript99.8 KB
scripts/test_route_simulation.pyscript7.0 KB
scripts/test_routing_parity.pyscript32.3 KB
scripts/test_routing_review.pyscript25.1 KB
scripts/test_setup_discovery_parity.pyscript9.5 KB
scripts/test_stage_help.pyscript2.0 KB
scripts/test_state_upgrade.pyscript13.8 KB
scripts/test_turn_refusal.pyscript16.7 KB
scripts/test_usage_cache.pyscript4.9 KB
scripts/test_usage_collector.pyscript21.4 KB
scripts/test_usage_core_claude_accounts.pyscript1.8 KB
scripts/test_usage_core_grok_cli_billing.pyscript15.6 KB
scripts/test_usage_core_magpie.pyscript5.4 KB
scripts/test_usage_core_magpie_pool.pyscript10.8 KB
scripts/test_usage_core_safety.pyscript24.4 KB
scripts/test_user_scores.pyscript102.3 KB
scripts/test_venice_usage.pyscript1.3 KB
scripts/test_window_scope.pyscript5.5 KB
scripts/turn_refusal.pyscript10.7 KB
scripts/usage_cache.pyscript4.7 KB
scripts/usage_collector.pyscript7.4 KB
scripts/usage_core.pyscript142.0 KB
scripts/usage_magpie.pyscript10.6 KB
scripts/usage_reading.pyscript17.1 KB
scripts/user_scores.pyscript72.8 KB
scripts/venice_usage.pyscript2.6 KB
scripts/window_scope.pyscript3.2 KB
scripts/worker_context.pyscript8.9 KB
scripts/worker_sessions.pyscript10.9 KB

references/router-internals.md

View on GitHub
# Router internals

Everything beyond the one-line `roll` path in SKILL.md: overview, when to self-execute, plan/record/close-out stages, allocator scoring, worker launch contract and the reference index. Read only what the task needs.

## Overview & Quickstart

- **Purpose**: task-level router for coding agents (Claude Code, Codex, Antigravity, Paseo). It classifies the task (kind, how much it needs of four categories, hours), then allocates the best-fit model and effort across your subscribed accounts using live quota windows.
- **Credential-free demo** (any directory; synthetic quotas, no network, no ledger writes, no worker launched): `agentcompass plan --demo --dry-run`
- **Dispatch**: `agentcompass roll --task "<what the worker should do>"` (`--task -` reads stdin, `--brief task.md` reads a file).
- **Command**: `agentcompass` is the only entry. Installed package: `agentcompass <command>`. Source checkout without an install: `python -X utf8 <checkout>/agentcompass <command>`, the same commands from any directory. `agentcompass -h` lists them, `agentcompass <command> -h` shows one. Do not run files under `scripts/` yourself.
- **Requirements & permissions**: Python 3.11+. Reads local quota telemetry (`~/.agent-compass/usage-cache.json`, written by the router's own collector `agentcompass usage`; the [usage-float](https://github.com/akiiwa-games/usage-float) display plugin is optional) and local policy configuration; writes a local routing ledger under `~/.agent-compass/`; launches locally installed provider CLIs (or Paseo) only when `roll` dispatches a worker.

> **System-Level Skill Loading Requirement (Host Rollout)**: `agent-compass` and its companion skills (`dot-subagent`, `chatgpt-pro-consult`, `gemini-web`) must be installed at the **system level** via `python -X utf8 setup/sync_host_globals.py` so every session loads them regardless of workspace:
> - `~/.codex/skills/<name>`, `~/.claude/skills/<name>` (`~/.claude-*/skills`), and `~/.pi/agent/skills/<name>` via directory junctions;
> - `~/.gemini/config/skills.json` (absolute paths) **plus** real top-level directories in `~/.gemini/skills/<name>` (real `SKILL.md` + live subdirectory junctions for `scripts/` and `references/`, required because Antigravity's `os.ReadDir` scanner skips top-level Windows `ReparsePoint` junctions).

For execution ownership and delegation criteria, see [SKILL.md](../SKILL.md#execution-ownership).

## 1. Standard Routing Workflow

### A2. Plan Only (Diagnosis)

Write a `task.json` file (in a scratch/temp path) describing **only the factual task and runtime constraints**, then run `plan`:

```bash
agentcompass plan --input <task.json>
```

Standard `task.json`:

```json
{
  "task": {
    "objective": "Fix race condition in token refresh lock and run unit tests",
    "expected_hours": 0.5,
    "needs": {
      "local_only": true,
      "local_only_reason": "Runs local unit tests against the workspace"
    }
  }
}
```

**Classifier Authority Rule (No Manual Classification by Parent Agents)**:
- **Do NOT manually fill `work_kind`, `difficulty`, or `profile` in `task.json`, and do NOT read classification examples or rubrics.**
- `plan` (and `roll`) automatically invoke the System-One classifier (inspect `agentcompass scorer --action show` for the effective scorer and available choices; configure it with `scorer --action set` or AgentCompass settings) to determine the atomic `work_kind` (`primary_level` `1..3`, plus optional composite `secondary_kind` / `secondary_level`) directly from `task.objective` and `task.context`, projecting `axis_demand` `0..3` over `creativity`, `coding`, `aesthetics`, and `tool_operation` deterministically in `task_intake`. If a parent agent supplies `work_kind` or `difficulty`, the classifier's judgment overrides them (`caller_classification_ignored`).
- When the caller leaves `needs.local_only` unset, a classifier profile with `local_only: true` is trusted: the router sets `needs.local_only: true`, copies the profile `reason` into `needs.local_only_reason`, and records `profile_local_only_applied`. `needs.local_only_by` names the input that set it (`--local-only` or `--workspace` from `roll`, `classifier`; a fixed set, `task_intake.LOCAL_ONLY_BY`), and the exclusion of a remote runner says it; unset, it reads as the caller's own `needs.local_only`. A value outside the set is refused as task input (`check_caller_task`), and a `plan --input` document that carries one reads as the caller's own mark: only the code that read the flag sets a token. The plan never reads the reason's text. This judgment is not rechecked by the caller-reason validator. Explicit caller values take precedence; `needs.local_only: false` in `plan` input keeps work Dot-eligible subject to route and modality constraints. `roll` has no separate negative flag.
- Factual `task` fields the parent agent may provide:
  - `objective` (required): Concrete description of what the worker must accomplish and how it will be verified.
  - `context` / `environment` (optional): Factual files, modules, or runtime context.
  - `expected_hours` (required): Estimated active worker-hours (positive number, or pass `--hours <n>`).
  - `needs` (optional): `{ "local_only": bool, "local_only_reason": "<concrete local dependency: ssh/vps/pytest/daemon/gui/credentials>", "outbound_ok": bool, "fast": bool }`.
  - `chain` (optional): `{ "id": "<chain-id>", "coupling": "low|medium|high", "total_hours": 4, "worker": { "agent_id": "<paseo-id>", "bundle": "sol_high" } }`. A quota window must cover the whole chain (`total_hours`, scaled by the bundle's duration) when `coupling` is `high`, only the step (`expected_hours`) otherwise; a window left short of that spend plus the safety margin excludes the bundle.
  - `can_wait_hours` (optional): Hours the task can wait for a short window reset before asking the user.
- Fields only AgentCompass sets (`task_intake.NOT_CALLER_INPUT`) are refused by name in a caller's task (`invalid_task_input: <field> is set by AgentCompass itself, never by the caller's task`), never dropped: `pinned_bundle`, `user_named_bundle`, `unclassified`, `force_fast` (also as `needs.force_fast`) are the route fields a recorded decision passes to its plan (`allocator.plan(route=...)`); `metered_fallback`, `worker` and `constraint_raw_model` are state the allocator and `task_intake.normalize_task` derive (a caller names its worker in `chain.worker`); `listed_rows` are kept on a record; `include_unverified` would lift the launch-evidence check. Lifting the two routing preferences for a bundle follows only from a `user_override` or explicit-resume decision naming it.

### B. Record an Explicit User Model/Effort Override

Only when the user explicitly names the target model or effort in the current request:

```bash
agentcompass record \
  --input <task.json> --constraint user_override --basis "<exact user quote>" \
  --provider <provider> --account <account> --model <model> --effort <effort>
```

`--effort` may be omitted (the account's row of that model keeps its level) or written as `--model <model>:<effort>` or `--model <model>-<effort>`. A level the account has no row for inherits the launch fields of its other rows of that model. The record is refused when a window that route draws is exhausted, or when the route is cooling down. A level the user unchecked, or a model with every level unchecked (also at a level with no row of its own), is out of automatic routing: a `user_override` record launches it with a warning, any other constraint is refused. A route the user names launches as long as the provider supports it; only facts refuse it, and the refusal states the fact:

- **An effort the launch contract does not list** (the table is the fact of what the harness accepts): `<effort> is not an effort <harness>/<model> accepts (<the efforts it does>)`.
- **A model with no row on the account** (the shipped data has none and discovery has not derived one): the account's live model list is read once (`provider_inventory.listed_rows`). When the provider lists the model, it launches on the row discovery would derive for it, with the data error `<account>/<model> has no row in the shipped data: unscored and unpriced until the public data has it` in the result and its ledger row. The provider's list outranks a family guessed from the name: neither an unknown API family nor the non-chat name pattern excludes it (automatic routing keeps both). When the provider does not list it, or its list cannot be read, the record is refused with `named_model_unavailable` and that fact. A family name is never folded to its target.
- **`--fast`**: whether the harness can launch the model fast is a fact (`fast_modes`): without a verified contract the record is refused with `<model> has no verified fast mode on <harness>; run it without --fast`. A missing fast-mode price is not: the named fast route launches with that data error, reserved at the plain mode's spend.
- **No classifier answer** (`--no-score` without a profile, or every scorer failed): with `--hours` the named route launches without a profile (no category demand), priced and reserved from those hours at the named effort, with the data error `unclassified (...)` in the result and its ledger row (`data_errors`). Without `--hours` it is refused, and the refusal says `--hours` lets it launch: no estimate is invented.

- **An account or provider the fleet does not have**, decided before any model list is read (`route_judge.named_pair_refusal`): `account <name> is not configured on this machine (its accounts: ...)`, or `account <a> does not launch through provider <p> (it launches through ...)` (`auto_bundles.launch_providers` and the providers of the account's bundles).
- **A `--basis` longer than 400 characters** (`decision_ledger.BASIS_LIMIT`): refused with the limit; a cut quote is not the user's quote.
- **`--trigger workflow` with a constraint the spawn gate does not accept for a Workflow**: refused with the constraint it needs (`route_judge.WORKFLOW_CONSTRAINT`). The rule has two holders: the gate decides (`check_workflow_record`) and `record` says it up front; a test drives the gate on the row `record` writes, over constraint x trigger, so the two cannot drift apart.

Said, not refused (in `warnings`): each quota window that binds the named model and was not read before the launch (`quota not observed: <account> window <ids> was not read ...`, with why: no usage snapshot, no fresh reading of the account, or a fresh reading that does not report that window). The windows are those `quota_pools.applicable_windows` finds for the bundle (`window_scope`): one that does not bind the model is not named, and a route with no quota windows (an unmetered channel such as Dot) gets no such note. Not read is not exhausted, and the launch goes ahead; with no usage snapshot at all the result also carries the alert `no_usage_data` with the same sentence and the account; `--effort` beside a `--model <m>:<effort>` that names another effort (`--effort` is used); a name read as another row (a moving name, a preview name, an alias or a family guess: `--model <name> was read as the row <row> (model resolution: <source>)`); a record with no task (no `--input`), whose route was therefore not compared with the router's own choice. A `hard_constraint` or `dot_closed_loop` record on an account outside `allowed_accounts` is written with `host_policy_violation` (the spawn gate reads the row and refuses a launch on it) and answers `status: blocked`, `next_action` with that reason, exit 2.

Every stage reads only the flags its row of `stage_help.STAGES` lists (`agentcompass <stage> -h` shows them); a flag given to a stage that does not read it is named in a note of the result's `warnings` (`<flags> is not read by <stage> and had no effect`), and the stage runs without it. The note is added in one place (`route_judge._run_stage`) after every stage, `score` and `scorer` included. A flag `roll` reads only for a route it records (`--trigger`, `--specialty`, `--reason-category`, `--accounts`; `route_judge.ROUTE_RECORD_FLAGS`) given to a roll that names no route, or to a `--resume` (which reads only `--accounts`), is named the same way, from the path the roll took; `--trigger workflow` there also says that no record authorizing a Workflow was written. A test runs each stage with a namespace that records which flags it reads and holds the rows to that.

Still refused, as the user's own boundaries or dispatch discipline: an account's `cwd_regex` (matched against the directory the worker runs in, `host_placement.worker_directory`, which `roll` puts in `task.cwd` and every launch surface places the worker in: the canonical `--workspace`; else, for `--resume`, the resumed worker's own directory as the registry knows it (`dispatch_registry.reusable_workers`: its Paseo record's `cwd`, else its latest dispatch's, else that request's, then its recorded workspace), the directory the plan, the re-plan in `dispatch_registry.prepare`, the refusal and the resumed dispatch's `cwd` name; else the parent's directory, `PASEO_AGENT_CWD` under a Paseo parent (`PASEO_AGENT_ID` set) or the process directory. When the registry knows no directory for a resumed worker and its account has a `cwd_regex`, the turn is refused (`resume_worker_directory_unknown`, exit 2), for a plain and a named `--resume` alike: neither a named route nor a named worker reaches past the user's boundary. On an account without one nothing is lifted: the turn is matched against no directory (`task.cwd_unread`), and `assumptions` says so. A worker `roll` resumes without being told to is one whose own directory its account's `cwd_regex` admits too (`roll._auto_resumable`), since the plan matched the directory a new worker would get. A `plan`/`record --input` task without `cwd` is matched against the process directory), and a brief the classifier reads as several tasks (`split`, unless `--keep-whole`). A model that is off only by default (a superseded generation) can be named.

### C. Dispatch lifecycle

`roll` prepares, launches and observes the dispatch; nothing is closed out by hand. To inspect or recover one, use `agentcompass dispatch --dispatch-action status|reconcile|release` ([dispatch lifecycle](dispatch-lifecycle.md)).

---

## 2. How the Allocator Scores Candidates

Provider availability is discovered automatically from native sign-ins, Paseo launchers,
local CC Switch and local Magpie. Account disablement, removed profiles and confirmed
credential rejection automatically pause new allocations; recovery takes effect on
the next allocation. Run `agentcompass providers` to refresh and inspect the inventory.
New bound Claude/Codex launchers inherit the existing model policy; saved profiles
without a launcher are listed without changing the user's active account. See
[provider discovery and quota sources](provider-usage.md).

The sole machine-readable public catalogue is [`accounts.json`](accounts.json).
Its model rows and `capability_policy` define model settings and route scopes.
[`model-capabilities.json`](model-capabilities.json) and
[`model-capabilities.md`](model-capabilities.md) are generated views; `agentcompass data refresh [--no-fetch] [--accept-panel-change]`
rebuilds them alongside the calibrated scores and manifest, or run
`python -X utf8 skills/agent-compass/scripts/capability_catalog.py` (`--check` verifies them).

The shipped template plus discovery is the whole fleet: accounts and second logins come
from discovery, plan capacity from the discovered plan through
[`plan-templates.json`](plan-templates.json), and the calibrated scoring weights, route
order and priority targets ship in `accounts.json`. Sparse `accounts-override.json`
preferences (disabled bundles and harnesses, sign-in vetoes, scoring tweaks) apply after
discovery; its `scoring` merges key by key, so defaults it does not set still apply.
There is no machine-local fleet document: a clean install reaches the same routing from
discovery plus public data alone. Keep explanations in `~/.agent-compass/host-rules/*.md`.

Account on/off preference lives only in host policy (`allowed_accounts`), shared by setup and the tray. It says which accounts take part in automatic routing: an account outside it is never chosen by a plan, a fallback, an automatic resume or as a scorer, but a route the user names still dispatches on it (see Pins) and a turn to an existing session on it is not a routing choice. `verified` is launch evidence: discovery may establish it from login or usage, and setup records `true` for an accepted CLI whose sign-in cannot be read. Legacy override `verified: false` is rejected by doctor and the loader; remove that field and choose the account in the tray.

The allocator first checks discovered availability, explicit disablement, host policy,
expiry, required modalities (`needs_visual`, `needs_gui`, or `tool_operation >= 3`), configured route restrictions and whether the model has data for every
category the task demands (`>= 1`). It then scores eligible candidates: the fit of the model's four category scores
(`creativity`, `coding`, `aesthetics`, `tool_operation`, in panel standard deviations at that effort, with each demanded
category's level-1 panel-weakest target as zero point) to the task's demand, continuity (`t3 - t2` on `coupling` `medium`/`high` when resuming),
and the quota economy's price for the spend. A category's term is `min(z, c) - t1`: at demand levels 1 and 2 the cap `c` is
the level's target, at level 3 it is the category's `ceiling` in `anchor.targets.<category>.levels.3` (per facet for
`aesthetics` and `tool_operation`), the highest measured or interpolated High value of any catalogued model, so a level-3 task can prefer a
model above the panel's best. Level 3 of a facet's scale (`t3`) is the panel maximum of the measured or interpolated High values, level 1 the minimum and
level 2 the median; the anchor is only the origin of `z` (definition: `docs/technical-reference.md` section 1). `five-axis-scores.json` carries
that meaning from schema `agent-compass.five-axis-scores/6` on (schema /7 adds a value at every effort and the `effort_steps`
table, /8 adds `minimal` and `size_steps`, /9 adds `ultra`, `effort_readings` and size steps per pair, /10 adds `none`,
/11 fills `none` from the fleet's own readings at none (`effort_steps.<facet>.lowest_reasoning.none`), /12, which this code
reads, holds facts with their dates only, so a rebuild on another day writes the same file (age and staleness are the reader's,
`scripts/data_age.py`); none changes a level), and `axis_scores.require_current_schema` refuses a file of another schema; the
levels of `user-scores.json` (schema 4; 3 had the same levels) are on this scale. Levels written on the earlier scale (3 = the anchor) keep their position: at or
below 2 unchanged, above 2 `2 + (L - 2) * (A - 2)` with `A` the anchor's level on the facet as of v0.7.0, declared in
`references/level-3-conversion.json` (`user_scores.convert_level`, applied once to the maintainer file and by `user_scores.LOCAL_UPGRADES`
to a local file); on `tool_operation.responsiveness`, whose earlier scale had `t2 = t3`, a level in (2, 3] becomes 2 and a level above 3 becomes
`2 + (L - 3) * s` with the declared slope `s = (t2 - t1) / (t3 - t2)` (`above_3_slopes`).
A hand-written level sets the facet at High (or at its declared effort); efforts the model has no reading at follow from it by
the published panel step `effort_steps.<facet>.high.<effort>` (`minimal`: Low plus `effort_steps.<facet>.low.minimal`; `none`: the lowest measured reasoning effort, else High, plus `effort_steps.<facet>.lowest_reasoning.none`; `ultra`:
Max plus `effort_steps.<facet>.max.ultra`), and the curve is bounded so it never inverts along effort (ability
never falls, responsiveness never rises as effort rises; `user_scores.bound_along_effort`, the rule the calibration applies,
`calibration/README.md`). A facet the calibration derived from a larger model follows that model's value after the hand-written
scores (`user_scores._follow_effective_sources`), never above it. A launch at `default`, and a bundle without an effort, read the
effort `effort_readings` declares (`axis_scores.reading_effort`).
For `aesthetics`, level 1 evaluates `design` (`lmarena.webdev`, `designarena.website`, `designarena.3d`, `designarena.svg`), and
levels 2 and 3 evaluate `min(design, image_recognition)` (sharing `tool_operation.image_recognition` so both visual creation and
fine-grained visual perception depend on visual grounding). For `tool_operation`, level 1 imposes no ability requirement; level 2
evaluates per-effort `responsiveness` (`aa.ttfa`, `-ln(seconds)` from Artificial Analysis `timeToFirstAnswerToken`); and level 3
evaluates `min(responsiveness, image_recognition)` (`aa.mmmu_pro`, `lmarena.vision`) and requires image-input support.
A dynamically discovered bundle starts checked unless public data lists
its model in `superseded` (`{old id: {by: newer id, basis}}`); efforts and harnesses of one
model share the entry, and a model unknown to the data starts checked. The user's
model-management checkbox (`disabled` in accounts-override.json) overrides that default. A checkbox is stored under
the bundle's id, which holds a model name; it applies to the bundle that name resolves to now, resolved where it is
read, or whose advertised name it is, so an alias a release or a published data set adds never strands it. Stored ids
that fold into one bundle and disagree leave it unchecked, and `agentcompass doctor` lists them once. The checkbox means
"takes part in automatic routing": an unchecked bundle is out of automatic routing, as an account outside host
policy's `allowed_accounts` is, and a route the user names still launches on it (Pins, below).
Checked metered bundles stay a last resort: explicit selection, `metered_ok`, or no eligible
subscription bundle. A dollar-balance account is one of those metered accounts; the rule is [Metered USD](../../../docs/technical-reference.md#metered-usd). A free pool (a free plan or a declared free allowance) is an ordinary quota pool priced by the quota economy like any other; a model with no data for a demanded category is out of automatic routing there too. Purpose-limited unmetered services (Dot, ChatGPT Web) have no quota to relieve.

A discovered plan supplies its window structure; its capacity comes only from community real-usage data per plan and window
(`five-axis-scores.json`). A plan or window without a cited capacity is unknown, and the bundles that draw it stay out of
automatic routing until the data has it (a named model still launches). A vendor plan multiplier sizes only the windows its
statement covers. A window that no public source measures takes a dated maintainer measurement when there is one (the
Claude / GPT track `3p-5h` and `3p-weekly` of Antigravity Ultra 20x); otherwise it is declared unmeasured
(`capacity_unmeasured` in `capacity_errors`; the same track on Ultra 5x, where only the Gemini bundles are routed
automatically). Antigravity and Grok have no default plan: when their subscription tier cannot be read or is
not in `plan-templates.json`, the account enters Mode B (`capacity_unknown` with `plan_unknown_reason`, surfaced in routing
notes and on the tray quota card). An unrecognized Claude or Codex plan is priced at that family's smallest paid plan with a
warning (`plan_unknown`, `plan_priced_as`). Unknown quota is distinct from unlimited access. Intrinsically unmetered services (OpenCode
free models, Dot, the ChatGPT Pro web bridge) are marked so in the template; observed
telemetry retains its source and freshness. An optional account `cadence` (`window_seconds`, `limit`) is a pace declared
for automatic routing: at most `limit` dispatches on the account per `window_seconds`, counted from this machine's
launches. It proves nothing about the vendor's remaining quota, and a route the user names reaches past it (**Pins**,
the switches of automatic routing). A dispatch counts once, from its launch until the window has passed over that moment, whoever chose the route and whether
or not it has ended (`quota_pools.cadence_dispatches`). The launches are the rows of `dispatch.sqlite3`
(`dispatch_registry.launch_record`: `launched_at`, unless the host refused the create; a reservation still holding its
lease counts from its creation). A CLI or Herdr claim holds the workspace before its worker starts and carries
`launched_at` only once the worker started (`dispatch_registry.host_claim_launched`; a Herdr send whose outcome is unknown
counts). A `--resume` turn is a row of its own and counts, as each turn is a request the vendor counts. A `record` row
stands for its launch only when the registry holds no dispatch of its decision (a named route launched outside `roll`). A
plan row is not a dispatch. ChatGPT Web's consultation is recorded as launched when `roll` hands over its `next_argv`, the
last step `roll` sees. Automatic routing on every account that declares a cadence is held to it, by the plan, the re-plan
in `dispatch_registry.prepare` (which reads the ledger as the plan does, without the decision it prepares) and the
ledger's `advisor_cadence` alert (at `limit` or more), all from this one count: with no seat free the account waits until
enough dispatches have left the window for one seat, deferred on the window `cadence` when that is within
`defer_if_reset_within_hours` and excluded otherwise (`over the dispatch cadence of automatic routing`, the count and the
wait in the candidate's notes). The cadence is a rolling limit (`quota_pools.cadence_window_state`): the seat a dispatch takes comes back one
window after its launch, so while a seat is free nothing of the allowance expires (the window is priced with a full
period to its reset), and what comes back after a wait is `limit` less the dispatches still inside the window then. It is
priced in the quota economy only on an unmetered account, where it is the whole quota; beside an account's quota windows
it is a gate, and those windows price the task. Known limits: a ChatGPT Web consult has no `prepare`, so two rolls that
both plan with one seat left before either hands over can both take it. A host claim whose `roll` died between the
claim and the start stops counting when its 300 s lease ends, and a late `host_claim_launched` on it revives the row.
A local `capability_policy.remote_reroute_guard.enabled` may retain a remote adapter's
reroute policy; the public catalogue does not enable a remote-first loop.

Historical uncompressed worker context is `compacted_tokens + context_tokens`, including
all pre-compaction context replaced over the session. At the configured context rotation
threshold (`rotate_after_carried_tokens`, default 4M, set in the tray), start a fresh
worker with a handoff. The parent can still steer its own running worker under the
communication contract below. The continuation verdict in a worker notification (`turn_refusal.py`) says `roll` with the reason for the conditions the gate
enforces on a parent's new turn to its own worker (leftover meter fields, confirmed quota exhaustion, a refusing quota window; not host policy or an unchecked model) and advises `roll` for
more: the worker's last turn ended in a provider failure (read from the watcher receipt, so before the hold is recorded), its
account is not ready, or its account, quota pool or model is held. The gate does not enforce the advisory ones. The verdict is
read-only and bounded in its own registry and quota reads, and loads the fleet through `load_accounts`, which may update host policy and holds as for any caller; an unresolvable worker or an unreadable registry is `unknown`.

---

### Model names, efforts and pins

The same rules hold in the other repositories that port this router.

**One resolver.** `model_resolution.resolve_model` is the only place a provider's spelling becomes a model. It returns `{key, source, effort, bare, provider}`.

**Which row a served name is** (`accounts.json` `provider_names`, read first). Some providers serve a name with other weights than the row the name resolves to elsewhere, and makers move a name to a newer dated snapshot. Two levels of cited declarations say which row a served name is:

1. `rows[<provider>][<name>]`, the serving provider's own: its listing names a different dated snapshot than the maker's default (`model: null`, `status: other_weights` when the catalog has no row for it), its listing spells the row another way (`canonical_id`), or the maker shut the name down there (`model: null`, `status: retired`). A declaration with no row leaves the pair with no scores: out of automatic routing with that reason, while a route the user names still launches.
2. `defaults[<name>]`, what a name whose maker moved it to a newer dated snapshot serves now: the maker's statement (kind `vendor`), or the owner's rule (2026-11-19: the name stayed, only the date behind it changed, so it reads as the new snapshot) applied by the maintainer to a name the maker's page describes (kind `maintainer`, citing that page). Read on any provider and with no provider known, when no serving provider declares the name. The name itself is a row of the catalog, the undated id the name repeats.

A provider's listing that gives the moved name's own undated id (or another name moved to the same snapshot) repeats the name and says nothing about the snapshot behind it: the default applies there and no declaration is needed. A provider's declaration beats the maker's default, and the default beats the name's own row; a name neither declares resolves as below. **Order with decorations**: the declarations (the provider's, then the default) and then the row are read for each spelling in turn, the name as given (its letter case ignored), then each vendor tag stripped (a date, `-latest`, `-preview`), then a dash effort dropped (`model_resolution.undecorated`): a decorated spelling reads the declarations of the name it reaches exactly where it would reach that name's row, so `deepseek-v4-pro-high` and `deepseek-v4-pro-latest` read `deepseek-v4-pro-0813`, while a spelling that is a row of its own (`deepseek-v4-pro-0813`) stays that row. A `-preview` name is the released row of that name (`model_resolution.without_preview`, owner 2026-11-20), read by the release check (`audit/gateway_coverage.py`) from the same owner in both directions (`hy3-preview` -> `hy3`; `qwen3.8-max` listed as `alibaba/qwen3.8-max-preview` -> `qwen3.8-max`); a provider that retired the preview endpoint declares `status: retired` (`google`'s `gemini-3.1-flash-lite-preview`), while dated snapshots (`-0731`) stay distinct weights. Provider ids, like names, are matched lowercase. **Full ids**: every lookup of a spelling—a serving provider's declaration (`rows[<provider>]`), a maker's default (`defaults`), an exact row (`models`), and an alias (`aliases`)—reads in one order (`model_resolution.slash_suffixes`): the full id, then what follows each `/` in turn, then the last segment. Thus `deepseek-ai/DeepSeek-V4-Pro` (and `siliconflow/deepseek-ai/DeepSeek-V4-Pro`) reads the undated `deepseek-v4-pro` on any provider while `deepseek/deepseek-v4-pro` reads the default of `deepseek-v4-pro`, and a multi-slash gateway id such as `google-vertex/openai/gpt-oss-120b-maas` reads the `<publisher>/<model>` alias (`openai/gpt-oss-120b-maas`) just as `(model, [preset])` does. No rule on owner parts exists in code: each full id is data. Serving providers that declare different rows give `conflict` (no row). The serving provider of a name is the endpoint the caller knows serves it, whose ids are in its own namespace (an OpenAI-compatible gateway account, `auto_bundles.ENDPOINT_TYPES`; a Magpie preset or the provider of a Magpie `account:<kind>`), else the provider part of a `provider/name` id (a launcher's list: a Paseo provider's models, Cindy's harness rows, a name with no account): `model_resolution.serving_providers`; Magpie preset ids whose own id differs from the models.dev catalog id(s) they serve (`provider_names.host_providers.magpie`, built from Magpie's `presets.go` by `audit/magpie_catalog.py`: e.g. `opencode-zen` -> `opencode`, `tencent-cloud` -> `tencent-tokenhub`) replace the preset id with those catalog ids only where a reader holds a Magpie preset id (`model_resolution.expand_host_providers(..., 'magpie')` in `auto_bundles.endpoint_providers` for `magpie_providers` and in `audit/gateway_coverage.py` `row_providers` on `magpie_preset`; a prefix in a name or a non-Magpie account never reads it, and disagreeing declarations across a multi-catalog Magpie preset's catalogs give `conflict` on that preset only). A bundle derived for a name with no row on its provider keeps the name qualified by that provider (`<provider>/<name>`) as its model, and so does a bundle whose provider declares a row whose own id reads as another row with no provider known (the undated row of a moved name); an alias of such a row keeps the alias's spelling. Either way every later resolution of the bundle's model reads the same declaration. Once a model name has been resolved to a row key (`canonical`, `row_key`, `stored_model`), functions that take a row key (`account_fleet.row_spec`, `quota_pools.applicable_windows` without a bundle, `tray/router_data.py` `decorate_model_rows`) read that row directly and never pass the row key back through name resolution. A score key is read with no provider (below). A model name stored for an account, a temporary priority's model or a quick reset-priority target, is read with the serving providers `derive` read the account's names with when it is a bare name (`account_fleet.stored_model`, `account_providers`: the endpoint providers recorded on each derived bundle as `_served`; none on a launcher account or for a manual bundle, where it reads as v0.7.1 read it, moved only by a maker's default) and by its own provider part otherwise, and a target is matched over the account's bundle pool (`account_fleet.pin_matching_bundles`, below), so a stored name reaches the account's bundle of that identity without crossing onto another provider's. **What the writers store** (`router-overrides.json`, from `agentcompass` quota overrides and the tray's priority writer): the stored form of the chosen name (`account_fleet.stored_form`): its row id, which for a moved name is the dated snapshot's id (`deepseek-v4-pro-0813`), `<provider>/<name>` for a name with no row on the account's provider, or the name as given when its row's own id reads another row (a repository id). v0.7.1 reads each of these forms as a row of its own or through its last segment. `account_fleet.canonical` of a name with no row on its serving provider is `<provider>/<name>`, as `row_key` gives it. The tray's model list reads an endpoint's advertised names with the serving providers `auto_bundles.endpoint_providers` gives, as `derive` does.

**The undated rows of moved names** (`deepseek-v4-pro`, `deepseek-v4-flash`, `deepseek-v4.1-flash` today) are reached only by the full ids declared to be them (DeepSeek's repository ids) and by a provider's own declaration: they stay rows, with their own readings, which the calibration also reads (`deepseek-v4-flash` is the series base other DeepSeek rows convert from, and the `^deepseek` family's target is `deepseek-v4-pro`, so a family guess shows it as its same-series row and carries no scores). Such a row takes a hand-written score under a declared name that reaches it (`user_scores.score_key_for_row`: the first such `defaults` name, e.g. `deepseek-ai/deepseek-v4-pro`); the tray writes that key, and refuses only for a row nothing reaches. The release check reads the same functions (`audit/gateway_coverage.py`).

| `source` | Meaning | Category scores |
|---|---|---|
| `provider` | the row the serving provider declares for the name | that row |
| `default` | the row the maker declares the name serves now | that row |
| `retired`, `other_weights` | the serving provider declares no row for the name | no scores |
| `conflict` | serving providers declare different rows | no scores |
| `exact` | the calibrated id itself | its own row |
| `alias` | another spelling of it: prefix, date, `-latest`, `-preview`, `[1m]`, letter case, a listed alias | its own row |
| `family` | a different model of a known family (`gemini-2.5-pro`, `claude-opus-4-20250514`) | no scores: a name without a row has none (`account_fleet.model_spec`); the calibration converts a same-series model only for a row of `accounts.json`, so a new family member is scored by adding its row |
| `unknown` | no match | no scores: a demanded category (`>= 1`, except `tool_operation = 1`) is a data error and the model leaves automatic routing |

The `family` patterns are data: `accounts.json` `families`, a dated maintainer declaration whose `rows` is an ordered list of `{pattern, models}` matched against the bare name (a catalog without it is a named error, never an empty table); the first matching pattern decides and the name resolves to the first of its models the catalogue has (none: `unknown`). A name no pattern matches falls back to the longest calibrated id it extends (`<id>-...`).

A trailing `:effort` or `-effort` is an effort, not a vendor tag (`:free` stays a tag). Local telemetry, quota window bindings, health and cooldown, worker continuity, harness factors, the rival for the margin and `superseded` all read the key and also accept the raw name, except that a family guess is never answered from its target's telemetry.

`account_fleet.row_key` says which model a row runs: the key for `exact`, `alias`, `provider` and `default`, the row's own name for `family` and `unknown`, and `<provider>/<name>` for a name with no row on its serving provider. A family guess never takes its target's scores. Wherever a row, a pin, a cooldown, a worker or a rival is matched, it is its own model, so naming the flagship never takes a family row. A cooldown recorded under any spelling of a model cools all its spellings. The rival behind `decision.margin` is the best row of a different model, never another effort, harness or account of the same model.

**Pins.** `constraints.model`, `constraints.effort`, `pinned_model` and `pinned_effort` hold in every mode and through `issue` and `prepare`:

- **Matching a bundle** (`account_fleet.pin_pool` -> `account_fleet.pin_matching_bundles`, read by `candidate_eval.pin_matched_ids` / `named_effort_bundles` / `model_pin_matches` / `evaluate_bundle`, `route_judge.match_bundle` / `record_constraint`, `dispatch_registry.resolve_bundle`, `roll.named_route_conflict`, `setup/router_gate_hook.py` `resolve_target` and `tray/router_priority.py` `targets`): which bundle a name names is decided over every bundle that exists on the accounts/providers the request addresses (`account` and `provider` when given, all accounts when none; `bundle_id` when pinned by id), built by `account_fleet.pin_pool` before any filter of preference (`host_policy`, `disabled`), availability (`unavailable`, `discovery_unavailable`, holds, quota), modality or effort, which then apply to the named bundles only so the best named bundle that can run launches and `named_model_unavailable` lists every named bundle with its reason (`allocator.named_pin_block`). Over that pool, if the user's text (`task_intake.normalize_task` keeps it as `constraint_raw_model` beside `constraint_model`) is an `auto:...` bundle id it names only that id, and `constraints.bundle` matches `bundle.id` only; otherwise, once an effort suffix is dropped: (1) a **bare name** (no `/`) names every bundle of the pool whose id is the pin or whose own `row_key` equals the pin's `row_key` as that bundle reads names (the bundle's `_served` endpoint providers when bare, else the default with no provider), whatever spelling or prefix that bundle advertises and whatever account it is on—the exact spelling excludes nothing; (2) a **prefixed name** `P/name` obeys `P` (`account_fleet._prefixed_bundle_matches`), naming only bundles of the pool whose id is the pin, that advertise the typed spelling (effort dropped, case-insensitive), or that are of the pin's row on an account, provider (`_same_provider`), endpoint serving provider (`bundle_providers`), or unexpanded Magpie preset (`bundle_presets`, `_presets` from `auto_bundles.endpoint_presets`, without changing which `provider_names` declarations are read) whose id is `P`, never substituting a same-row or same-leaf bundle `P` does not name when `P`'s cannot run; (3) **a prefix that names nothing in the pool** (owner, 2026-11-20: no bundle id, no advertised spelling, and no account, provider, serving provider or preset id of a pool bundle is `P`, the same test clause 2 makes) is dropped in one place (`account_fleet._unrecognized_prefix_matches` / `effective_pin`) and the rest is read as the pin from the start—if `rest` still has a `/`, its first segment is obeyed when it names something and dropped when it does not, and a bare `rest` names every bundle of its row across the addressed accounts (clause 1), while how a bundle's own advertised name resolves is untouched; `record` and `override` store the pin as read (without a dropped prefix `P/`), so gaining provider `P` later never re-targets a stored decision or priority. A model pin with an empty segment around `/` or `:` (`/gpt-5.5`, `openai/`, `openai//gpt-5.5`, `:high`) or an incomplete `auto:` id (`auto:acct:harness`) is refused at the caller boundary as `invalid_model_pin` (`model_resolution.check_model_pin`); an entry already stored in `router-overrides.json` with a malformed model is kept inert until its own `until` expiry without asking to delete the file, while new writes (`override`, tray `enable` / `add_boost`) are refused. A stored override or quick target on an account (`account_fleet.stored_form`) is bare when its row id or leaf reads back to itself (`gpt-6-astra`, `deepseek-v4-pro-0813`, `novel-unmeasured`—naming every bundle of that row on the account) and prefixed when the prefix carries the identity (`opencode/deepseek-v4-flash`, `deepseek-ai/DeepSeek-V4-Pro`, `vendor-a/novel-unmeasured`—naming only that identity's bundles on the account). Never compare a resolved row id against a raw spelling, and never compare leaf names across distinct rows or no-row declarations.
- Model only: the plan picks among that model's levels by score: every level the launch contract (`dispatch_efforts`, or the row's `efforts` when unlisted) offers competes as a candidate, so the answer does not depend on which rows are written. `prepare` accepts any level that is in the contract, is offered by the row and is not unchecked; it does not rank levels again, since the score needs the task.
- Model and effort: that level stays. A level the model has no row for is carried as `<carrier>@<effort>` when `dispatch_efforts` or the row's own `efforts` offer it. Each level goes to the first row of the model that offers it, so the answer does not depend on the order of the rows.
- A family name never launches the family target; unconfigured means blocked.
- A pin on an exact or alias name matches that model's rows only. A family row is another model: it never stands in for the name, healthy or not, and a named model that is down is blocked. An unnamed task can still run the family row when its flagship is down.
- A level the user unchecked belongs to that row's own model (`row_key`). Unchecking `claude-opus-9` at `high` leaves `claude-opus-5-5` at `high` reachable, and the other way round.
- `disabled_by_default` rows stay out of routing until named.
- Two switches say what automatic routing may choose on this host: host policy's `allowed_accounts` (accounts) and the model-management checkbox (models); an account's declared dispatch `cadence` says how often it chooses one account. No plan, fallback chain or automatic resume chooses past any of them. The scorer is checked against `allowed_accounts` only (`scorer_client.scorer_accounts`): its model is the configured scorer's, not a routed choice, and a scorer call is not a dispatch, so the cadence neither counts nor holds it. A route the user names (`roll --provider/--account/--model/--effort --basis`, `record --constraint user_override`) reaches past all three; a route named to `roll` is only that, and a `--constraint` other than `user_override` beside its route flags is refused (`roll.named_route_refusal`), since a project rule is recorded with `record`. A named route dispatches with one warning per switch (`route_judge.automatic_routing_texts`): `account <a> is out of automatic routing on this host (not in allowed_accounts of host-policy.json)`, `<a>/<model> is out of automatic routing on this host (unchecked in model management)`, or, at the cadence's limit, the `advisor_cadence` alert's sentence (`<a>: <count> of <limit> dispatches in the <h>h cadence window, ...; a seat frees in <x>h`), each ending `; launched because the user named it in this request`. That warning is what the caller passes on to the user; the cadence's fact also stays in `alerts` as the code `advisor_cadence` (severity `info`), which the ledger row and the audit read. Both are one sentence from one count: `record` reads the cadence once (`route_judge.cadence_reading`) and hands that reading to `decision_ledger.finalize`. This holds on every surface a named route takes: `record` alone, `roll` named to a ChatGPT Web consult, a named Paseo route through `prepare`, and a named `--resume`; the launch counts in the cadence like any other. Any other constraint (`hard_constraint`, `dot_closed_loop`) does not override this host's switches: on an account outside `allowed_accounts` it records `host_policy_violation`, is not launch authority and answers `status: blocked` (exit 2); on an unchecked model, and on an account at its cadence's limit, `record` refuses (exit 1) and writes nothing. The cadence refusal is the `advisor_cadence` sentence (count, limit, when a seat frees), that a project rule does not reach past a pace of automatic routing, and the two ways on: wait for the seat, or `--constraint user_override` with the user's words in `--basis` when the user named the route in this request. So a consult, which has no `prepare`, and a Paseo route give one answer. After a named route on an unchecked model fails, the fallback chain does not choose another unchecked model. An automatic plan names what each switch excludes in the reason a caller reads (`candidate_eval.said_exclusions`: the same two wordings, followed by `the user's own setting on this machine, so the router does not choose it`), and so does an account's `cwd_regex` (`cwd_policy.refusal`: the account, the pattern and the directory matched). Only the user's checkbox is the user's setting: a row off by default in the shipped data (`disabled_by_default`) says so and that naming the model uses it (`auto_bundles.off_by_default`), and a row discovery no longer sees is said by its discovery exclusion alone; neither counts as a local setting. `ranking[].excluded` keeps `excluded by host policy`, `unchecked in model management` (for all three kinds of a `disabled` row) and `over the dispatch cadence of automatic routing` (`candidate_eval.AUTOMATIC_ROUTING_EXCLUSIONS`), which `dispatch_registry.prepare` lifts by value for a named route and an explicit resume; it does not wait for the window `cadence` either (`AUTOMATIC_ROUTING_WAITS`, read from the candidate's `waits`, every window that holds it back with its hours). When these settings are all that keeps the closest candidates out, `decision.local_settings` lists them and says whether a named route reaches past them (`named_route_reaches`; not past a `cwd_regex`). A `host-policy.json` that could not be updated with newly discovered accounts is a plan warning (`host_policy.sync_failed`).
- `roll --resume <agent_id>` names a worker, not a route: its route is the worker's own bundle, not what an automatic plan of the task would choose. `route_judge.record_resume` records it (`constraint: explicit_resume`, the task classified as any roll); model flags that name the worker's own route add nothing, and flags that name another route are an error at the entry, before anything is recorded. On a switch it reaches past, the warning ends `; the turn goes to worker <id> because --resume named it`. Nothing is ever started in the named worker's place: whatever stops the worker from taking the turn gives `status: blocked` with its reason and creates nothing, on any account. The facts are: busy, at the rotation limit, a refusing quota window, leftover meter fields, a model its account no longer offers, a bundle gone from the configuration, a `--workspace` other than the worker's own directory (a worker does not move), or the host refusing the resume (the worker is gone, not idle, or differs from the request; the bridge names what differs). A turn the worker takes and then fails is not relaunched on another worker either (`dispatch_fallback` `worker_named`). An automatic resume (the router's choice) never picks a worker whose account is out of automatic routing or whose model is unchecked, and when the host refuses it, a fresh worker on the planned bundle carries the brief.
- The live model list of an account is read when a plan can choose it, or when a named route or an explicit resume names it even with every bundle of it out of automatic routing (`allocator.plan(named_accounts=...)`), at most once per live-list TTL per provider; a plan never polls an account it cannot choose.
- `decision_ledger.append_ledger` marks every row that carries a launch on a bundle (a `plan` or `record` row with a chosen bundle that its writer did not refuse) with `outside_automatic_routing`: what only automatic routing is held to that the launch reaches past, `account` and/or `model` (the switches in effect when the row is written) and `cadence` only on a row the user named (`constraint` `user_override` or `explicit_resume`) that launched at or over the limit, taken from the `advisor_cadence` alert `finalize` computed for that row, never from a second reading. An automatic row (a deferred plan included) is never marked `cadence`, nor is a row whose answer carried no cadence alert. Rows that launch nothing carry none, and no writer sets it. It is the field the audit filters on.
- A named route that is exhausted, cooling down or otherwise unusable gives `choice: none`, `decision.blocked: named_model_unavailable`, the reasons in `decision.warnings` and no substitute. Tell the user.
- A new pin breaks the hold of a coupled chain.

**Profile validation.** `multi_task` and `task_count` are required. `task_count` takes `1`, `2`, `3`, `>3` or a positive whole number (4 and above become `>3`); `multi_task: false` goes only with `1`. Zero, negatives, fractions, NaN, Infinity, words, null and contradictions are invalid and never repaired. A classifier's invalid answer counts as a failed attempt, ending in the next classifier or `scorer_unavailable`; a caller's invalid profile raises `invalid_caller_profile`. A cached profile is validated again on read, and a bad one is a miss. Validation is idempotent and never raises anything but `ValueError`, whatever the size of a number.

A ledger row with no saved snapshot and no split answer cannot be replayed: its recorded profile is not valid, reclassifying its text would invent a different task, and filling in an answer would invent what the classifier said. The tray marks such a row `旧记录缺字段,无法重放` in the ledger list and shows the same note instead of a replay. Rows with a saved snapshot are unaffected.

### No eligible bundle

When nothing clears the gate, `plan` returns `choice: none` with `decision.action: none`, `needs_user_decision: true` and a `reason`. If a bundle is held back only by its own account's quota windows (`quota_pools.quota_wait`), `decision.next_reset` gives that bundle, its account, the window that returns last and the hours until then (rounded up to a tenth, `allocator.advised_hours`), and the time. The plan's other waits, `decision.start_after_hours` of a deferral, `decision.wait_for.hours` and the `decision.wait_hours` of a user decision, are rounded up the same way (a chain owner that never resumes has `wait_hours: null`). The parent can wait or decide otherwise.

### Calibration data

`calibration/` builds panel standard scores and per-effort curves from LMArena, `arena.ai` Agent/Alignment, Design Arena and Artificial Analysis; `agentcompass data refresh [--no-fetch] [--accept-panel-change]` (`calibration/refresh.py`) rebuilds the calibrated files and generated capability views in topological order and validates them; the fetching refresh runs once per release ([Reference data](#5-reference-data-shipped-and-published)). See [`../calibration/README.md`](../calibration/README.md). Raw downloads stay outside git.

### Distribution simulation and ledger replay

`scripts/route_simulation.py` shows where work goes across usage states, and replays past decisions. Usage reaches `allocator.plan` the way `roll` feeds it: a collector cache document (`providers.<account>.windows[]` with `used_pct`, `resets_at`, `fetched_at`, `stale`) goes through `usage_reading.usage_snapshot`, which produces `remaining_pct_before_reset`, the reset time and freshness. A metered USD reading follows [Metered USD](../../../docs/technical-reference.md#metered-usd). Then `plan` merges discovery and quota sources itself. Synthetic states are written as cache documents, never as hand-made allocator input. A raw ledger or cache row passed straight to `plan` has no `remaining_pct_before_reset`, so every window reads as unknown and the result ignores usage. The pre-2026-11-04 ad-hoc replays made exactly this mistake.

```bash
python -X utf8 scripts/route_simulation.py grid [--mode machine|fresh|both] [--state NAME ...] [--json out.json]
python -X utf8 scripts/route_simulation.py grid --accounts "claude pro" --accounts "opencode free" [--state NAME ...]
python -X utf8 scripts/route_simulation.py explain [--creativity N] [--coding N] [--aesthetics N] [--tool-operation N] [--local] [--state "claude scarce"] [--bundle grok47_high]
python -X utf8 scripts/route_simulation.py replay [--last N] [--json out.json]
```

- `grid` plans every point of the category demand space (`quota_economy.FIVE_AXIS_DEMAND_GRID`) x local/remote under each usage state, then reports wins per bundle and per `model@account`. It also lists the enabled models that win nowhere, each with its median score gap to the winner and its most common exclusions.
- States:
  - `live`: the current collector cache.
  - `ample`: 10% used everywhere.
  - Scarcity by account family, using discovery's family: `claude`, `codex`, antigravity `gemini` / `3p` windows, `grok` (the Grok Bot mirrors it), and the pairs `claude+codex`, `claude+antigravity` and `claude+codex+antigravity`.
  - `5h-only` scarcity: windows under 24h.
  - `unknown/stale`: readings three days old.
  - `claude tight`, `codex tight` and `antigravity tight`: a fifth left with 60% of the window to run. A cheap model's burn still fits where a strong model's does not.
  - Scarce means 95% used with 70% of the window left; a short window means 98% used with 3h left.
- `--mode machine` routes as this machine does: `accounts-override.json` checkboxes and the host policy apply. `--mode fresh` routes as a fresh install would: public data plus discovered accounts, with no personal choices and every account allowed.
- `--accounts NAME` (repeatable) routes in fresh mode for a synthetic account set instead of the accounts discovered here. The sets are `claude pro`, `claude max5`, `codex plus`, `codex pro`, `antigravity pro`, `claude pro + codex plus`, `magpie pool (3x claude pro)` and `opencode free`. Each is a discovery snapshot carrying the models that product's CLI advertises, and only the set's accounts are allowed. The advertised models are the catalog's launch surface for that harness (`route_simulation.advertised`): the launch ids of the family account's bundles, the other models in `dispatch_efforts[<launcher>]`, and the `aliases` keys prefixed `<launcher>/` (OpenCode's `opencode/<id>` free models); a model the catalog does not declare for a harness is not simulated there. Use them to check that routing works for users unlike this machine.
- `explain` prints the top of one ranking with score components. Use it to answer "why does X never win".
- `replay` re-plans each ledger `plan` record with the usage that decision saw. The record's compact usage (`fetched_at`, `status`, per-window `used_pct`/`resets_at`) is rebuilt into a cache document and read at the record's own time. Since 2026-11-04 the record keeps a pooled window's `accounts` count (`decision_ledger.usage_digest`), so a Magpie pool replays as N accounts' worth. Older records lack it; replay fills it from the live cache's pool sizes (`route_simulation.pool_counts`), on the assumption that a pool's size rarely changes. Continuity, reservations and overrides are not replayed.
- Set `AGENTCOMPASS_PUBLIC_DATA=off` to evaluate the repository's data. Otherwise a newer published set fetched into the state dir wins.
- The CLI is read-only toward the real profile. It copies the small state files routing reads (top-level JSON, `public-data/`, `grok-bot/config.json`) into a throwaway state dir, so discovery bookkeeping lands there. It reads usage with an empty discovery inventory, so the Claude session-limit overlay is skipped. `test_route_simulation.py` pins the behavior: Claude scarcity must move work off Opus on `claude`, and Codex scarcity must move work off the Codex models.

## 3. Worker Launch, Communication & Permission Contract

**Settings hold state only; never write a reason.** Users choose settings themselves in the UI. Store `disabled` only as `true` or `false`; never attach justification, notes or dated user instructions to a setting. Router decision explanations belong in plan output and ledgers, not settings.

**Questions to the main session must be sent as real messages.** A worker needing clarification/decisions must directly message its parent, never call `request_user_input_async`, `AskUserQuestion`, `ask_user_question`, `request_user_input` or similar UI-only tools that cannot communicate with the parent. In Paseo use `send_agent_prompt` to the actual parent ID with `background: true, notifyOnFinish: false`, then end the turn rather than synchronously waiting on the parent. If messaging is unavailable or fails, return `BLOCKED / needs_input` through the existing result channel and end the turn; the caller must collect/relay it. See the [communication contract](worker-communication.md) injected by `roll`. This does not restrict the main session asking the real user or bypass required approvals. For native/manual launches, include this contract and the actual parent ID, host and message address too. Missing parent information prohibits launch; the result-channel fallback applies only to delivery failures after launch.

Which channel carries the report is decided per dispatch and written into the [worker communication contract](worker-communication.md). A watched dispatch puts the full report in the final reply; the completion watcher sends that reply in one notice. A dispatch with no watcher sends `[Worker final report]` itself.

`notifyOnFinish: false` applies to a worker's question to its parent. When the main session uses `send_agent_prompt` to add work, give clearance or resume its own worker, it keeps `notifyOnFinish` true (or omits it): that completion notification is the one end message, and the worker does not also send a report. `router_gate_hook` blocks an explicit `false` from a parent to its own worker.

An unchecked model starts only on a route the user named (the launch's decision is `user_override`); exhausting a model's drawn quota window blocks new launches; an exhausted window also blocks a parent's new turn to its own idle worker, while the parent can still control its own currently running worker (steer, scope cut, answering questions, wrap-up/handoff): blocking control messages saves no quota and only leaves a running worker without its wrap-up instruction. The same exception applies at the configured context rotation threshold (`rotate_after_carried_tokens`, set in the tray). Ownership must be proved by consistent locally persisted parent labels and running state by the local Paseo record; missing/unknown/idle state grants no exception, even for a prompt requesting only a commit or report. Collect existing output, cancel if necessary and roll a handoff to a fresh worker. A message to an agent the caller does not own is communication and passes unchecked. Completion-notification checks still apply. See the [gate contract and local-state limitation](parent-address-gate.md#disabled-target-quota-and-context-rotation-gate-contract).

Paseo SDK creation does not implement MCP's `notifyOnFinish`. The router therefore starts its own notifier before SDK creation, deduplicated by dispatch ID and stable message IDs. A send Paseo answers `agent_request_outcome_unknown` is resolved from the parent's timeline, by message id only, on a row Paseo did not reject (a rejected prompt has no `turnId` and Paseo's `[System Error]` row right after it; a timeline replayed from provider history has neither, and its row counts): found is delivered, not found is sent once under the next id derived from the same dispatch ID, never a random one, no sooner than 15 and then 60 minutes after the previous id, and a notice stops after three ids as `undelivered`, named in the same parent's next router answer (`undelivered_end_notices`). One brief gets one end notice, when its chain of attempts is final: a failed attempt whose fallback may still relaunch it waits ([dispatch lifecycle](dispatch-lifecycle.md#2-in-flight-quota-deduction)). The watcher's lock file holds its pid once. Permission notices leave observation active; final delivery, parent closure or the seven-day watch deadline ends the process. How that exit, a dead watcher, and a follow-up turn release the reservation is defined in [In-flight quota deduction](dispatch-lifecycle.md#2-in-flight-quota-deduction). A two-minute delivery grace follows the deadline; failures remain in the durable receipt. A stopped watcher can be recovered by observing the dispatch; recovery never creates another worker. No daemon settings or installed Paseo files are modified.

If notifier startup fails, the bridge does not create a worker whose result could be lost. Repair the local SDK dependencies or notification state directory and roll again. This startup check applies only to new creation; existing workers remain observable and their replies can be collected manually.

Always pass the explicit permission mode from `selected_bundle.modeId` (never rely on CLI defaults):

| Provider | Launch Surface | Required Permission Flag / Mode | Notes |
| :--- | :--- | :--- | :--- |
| **`codex`** | Paseo / Codex CLI | `--mode full-access` | Engineering & GUI (`cua_repl`) harness for `gpt-6-astra` and `gpt-6.1-sol`. |
| **`pi`** | Paseo (`provider: "pi"`) | No `modeId` (adapter has fixed tool access and advertises no modes) | Exploration & research-packet harness for GPT models (`launch_model: "openai-codex/<model>"`). Passing `full-access` is rejected by Paseo. |
| **`claude`** | Paseo / Claude CLI | `--mode bypassPermissions` | Use the discovered launcher and configured account policy. |
| **`antigravity-resilient`** | Paseo / `agy` CLI | `modeId: "full-access"` | Use a model and effort advertised by the adapter. |
| **`opencode`** | Paseo (`provider: "opencode"`) | `modeId: "build"` | OpenCode free worker (`deepseek-v4.1-flash-free`, `launch_model: "opencode/deepseek-v4.1-flash-free"`). |
| **`dot`** | [`dot-subagent`](../../dot-subagent/SKILL.md) | `run_dot_task.py` | Remote worker (`dot2api`); requires `needs.outbound_ok: true` if sending private material. |
| **`grok-bot`** | [Grok Bot adapter](grok-bot.md) | `run_grok_bot.py` | Automatic remote text candidate; no local file transfer, private material requires outbound authorization. |
| **`chatgpt-web`** | [`chatgpt-pro-consult`](../../chatgpt-pro-consult/SKILL.md) | Browser bridge | `gpt-6-pro` read-only advisor for `architecture_reasoning` and `creative_ideation`. |

**Gemini web is a local tool, not a worker:** [`gemini-web`](../../gemini-web/SKILL.md) drives AgentCompass's signed-in Gemini Web Chrome (`gemini-web`, CDP `127.0.0.1:17849`) for Gemini / AI Studio / Flow pages and Gemini Omni 1.1 video. The calling agent runs it directly, with no routing. A worker given such a task needs `needs.local_only: true` with `local_only_reason: "Gemini Web browser on this machine"`.

---

## 4. Reference Files (Internal Router Specs — Parent Agents Need Not Read)

- [`dispatch-rules.md`](dispatch-rules.md) — The rules a dispatching session follows (the global pointer sends sessions here).
- [`accounts.json`](accounts.json) — Public model catalogue, conservative priors, route scopes, account slots and bundle definitions.
- [`classifier-cases.json`](classifier-cases.json) — System-One classifier route definitions and calibration cases (loaded automatically by the router).
- [`model-capabilities.md`](model-capabilities.md) — Generated catalogue view and prior limitations.
- [`model-capabilities.json`](model-capabilities.json) — Generated policy/model view; runtime derives its policy from effective accounts.
- [`dispatch-lifecycle.md`](dispatch-lifecycle.md) — Reservation state machine (`planned` -> `started` -> `completed`) and in-flight quota deduction.
- [`task-classifier.md`](task-classifier.md) — the System-One classifier: `score` / `scorer`, the `TaskProfile` schema and how a profile is applied.
- [`jev-api.md`](jev-api.md) / [`gemini-decisions-api.md`](gemini-decisions-api.md) — The question-API task scorers (TypeSafe Jev, Google Gemini Decision 1): request, key, when each runs.
- [`effort-matching.md`](effort-matching.md) — Per-model effort curves and the ledger `decision_snapshot` the tray replays.
- [`provider-usage.md`](provider-usage.md) — Live usage snapshot precedence, `capacity.json` overlay, host policy, and temporary overrides.
- [`public-data.json`](public-data.json) — The manifest that publishes the reference set (sha256 per file, data schema, publication time); see Reference data below.
- [`scripts/route_judge.py`](../scripts/route_judge.py) (with [`scorer_client`](../scripts/scorer_client.py), [`decision_ledger`](../scripts/decision_ledger.py), [`subscription_cli`](../scripts/subscription_cli.py), [`usage_reading`](../scripts/usage_reading.py), [`env_vars`](../scripts/env_vars.py)) · [`scripts/allocator.py`](../scripts/allocator.py) (with [`account_fleet`](../scripts/account_fleet.py), [`task_intake`](../scripts/task_intake.py), [`axis_scores`](../scripts/axis_scores.py), [`quota_economy`](../scripts/quota_economy.py), [`quota_pools`](../scripts/quota_pools.py), [`quota_overrides`](../scripts/quota_overrides.py), [`candidate_eval`](../scripts/candidate_eval.py), [`candidate_ranking`](../scripts/candidate_ranking.py), [`ledger_snapshot`](../scripts/ledger_snapshot.py), [`worker_sessions`](../scripts/worker_sessions.py)) · [`scripts/host_policy.py`](../scripts/host_policy.py) · [`scripts/check_router_contract.py`](../scripts/check_router_contract.py)

### Antigravity plan tier

`agy -p /usage` reports only bucket fractions, so the tier that sizes them is read from Google the way agy learns it: `scripts/antigravity_plan.py` takes agy's own sign-in from the OS keyring (service `gemini`, user `antigravity`), calls `daily-cloudcode-pa.googleapis.com/v1internal:loadCodeAssist` with `ideType: "ANTIGRAVITY"` metadata, and caches `paidTier` (`tier_id` and `plan`) in `~/.agent-compass/antigravity-plan.json`. Google returns `paidTier.name` `"Google AI Ultra"` for both Ultra variants and distinguishes all three paid plans by `paidTier.id`, which discovery resolves through `plan-templates.json` `tiers` (`g1-pro-tier` -> `pro`, `g1-ultra-lite-tier` -> `ultra5`, `g1-ultra-tier` -> `ultra20`) and counts as a sign-in proof. `roll`, `plan` and `providers` refresh the cache in the background every 12 hours (30 minutes after a failure); an expired agy token or failed request keeps the last good tier until `PLAN_MAX_AGE_HOURS` (48h). There is no default Antigravity plan and no unsplit `ultra` alias: when the tier cannot be read or is not in `plan-templates.json`, the account enters Mode B (`capacity_unknown` with `plan_unknown_reason`, out of automatic routing and shown on the tray card). Off switch: `AGENTCOMPASS_ANTIGRAVITY_PLAN=off`.

## 5. Reference Data (Shipped and Published)

**Rule: no install, test, workflow or schedule reads the boards (arena, Artificial Analysis, vendor pages) at run time.** The fetching refresh (`agentcompass data refresh` without `--no-fetch`) runs once, when a release is prepared. Between releases the only data that moves is what the maintainer publishes on purpose: a new model (`data refresh --model <id>`), a corrected hand-written score, a corrected launch row. Every install (git checkout, pip or `uv tool` wheel, tray installer) ships the reference set under `references/` with its manifest [`public-data.json`](public-data.json), and reads a newer set the maintainer published for its data schema on the repository's `main` branch ([`scripts/public_data.py`](../scripts/public_data.py)).

- **The set**: what a run-time reader reads, through the one accessor `public_data.document`: `accounts.json` (`account_fleet.fleet_document`, `auto_bundles`, `worker_sessions.shipped_scoring`, the reference fleet's `families`, the tray's model table, tuning defaults, display names and prices), `plan-templates.json` (`provider_inventory.shipped_plan_templates`), `classifier-cases.json` (`scorer_client.load_classifier_cases`), `five-axis-scores.json` (`axis_scores.load_five_axis`) and `user-scores.json` (`user_scores.load_public`). Left out: `level-3-conversion.json` (the frozen conversion of the user-scores upgrade step, owned with that code), `public-measurements.json` (read only by the maintainer's refresh) and the generated `model-capabilities.{json,md}` (documentation views, no run-time reader).
- **One set per process**: a process takes the whole set (every file, read once into memory and verified against its manifest) the first time a reader asks, and keeps it (`public_data.held`); later changes on disk, a newer set fetched by another process or the removal of an old set cannot split it. A reader gets reference content only from `public_data.document`, so it cannot mix two sets; the hermetic test run fails any test in which a run-time module (scripts, tray, setup, `agentcompass/`) opens a file of the set other than through the accessor, whatever shape the read takes (`hermetic_run.reference_reader`, an `open` audit hook scoped to the set's paths). The allowance is the accessor (`document`) and the functions that build the held set (`held`, `retake`, `fall_back`, the check `refresh`), not any function of an owning module: the generators and checkers that read the set as files (`capability_catalog.markdown`, `write_default_files`, `check_files`, the provenance checks, `data publish`) are allowed only from their own commands (`data refresh`, `data publish`, the provenance and catalogue scripts), never from a run-time stage (`hermetic_run.REFERENCE_ENTRIES`). It covers every reader a test exercises; the static scan it replaced missed reads through a variable, a loop, a helper or a built name. The tray moves to a newer set only as a whole, when it rebuilds its accounts view (`router_data._cached_accounts`, `public_data.retake`). Every fall-back is to the shipped set as a whole.
- **Publication**: the published set of data schema N lives in `published/<N>/` at the repository root (the manifest and the five files): one push by the maintainer, a reviewable diff of exactly what installs receive, no second checkout or branch. Only `agentcompass data publish` (in a checkout) writes it: it accepts `references/` (below), copies the files with their manifest (sha256 and size of every file, the schema, `published_at`, moved only when the content changes and always later than the publication it replaces) to `published/<SCHEMA_VERSION>/`, and writes the same manifest to `references/public-data.json`, which a release ships. Editing `references/` on `main` publishes nothing, and release preparation under a new schema writes `published/<new>/`, which installs of the old schema never read. The `public-data` workflow runs `agentcompass data publish --check --since <base>` on every push and pull request that can change either side: the published set must match its manifest, be accepted by the code at that commit, be published later than the set it replaces (an install ignores a set not newer than what it has) and not in the future; `--check-released` runs the acceptance of every released version of the same schema (tags `v*`) against it, which is what those installs will run. The release workflow runs `--check --release` (a release ships `references/` as the latest published set of its schema, so a release publishes its own data first) and `--check-released`. `--since <rev>` with a revision that is not a commit of this repository fails the check, saying so (`public_data.manifest_at`): the comparison with the previous publication never passes by default. A commit id the checkout does not have (the workflow's base, `github.event.before`, after a force push to `main`, or a shallow checkout) is named as the missing base commit, not bad data, with what to run: fetch it, or run `agentcompass data publish --check --since <commit>` against the commit `main` had before the push. A published set of an older schema (`published/<old>/`) is frozen, since installs of that schema keep reading it: the check fails when it no longer matches its own manifest, and with `--since` when it changed since that revision (`public_data.check_frozen`). A wheel or the product ships `references/`, never `published/` (`packaging/check_payload.py`).
- **Acceptance**: a set is accepted only when this code can route with it: `public_data.accept` runs the provenance checks, then, with the candidate held, every run-time reader (`account_fleet.launch_problems` and `load_accounts`, the `scoring` rotation threshold, `load_five_axis`, `load_public`, the classifier cases into the scorer evidence, the plan templates), an offline plan on the reference fleet (what `plan --demo --dry-run` runs) and one on the set's own fleet priced with the reference fixture's plan tiers (`demo_plan.priced_fleet`) and a synthetic quota snapshot, which must have at least one selectable candidate; each plan is serialized as the CLI prints it (`route_judge.render`, strict JSON); no network, no classifier call. Every reference file is parsed strictly wherever it is read (`public_data.parse_document`: `NaN`, `Infinity` and a literal that overflows to infinity are a named `ReferenceDataError`); a fetched set holding one is rejected by version by the acceptance, like any other refusal, and not downloaded again. What the acceptance proves: this code's readers load the set, and both plans complete and serialize with it. What it does not prove: a reader path only the live fleet reaches (discovered accounts, the user's own settings, real quota), which is what the fall-back below is for. One function, used by `data publish`, the workflow and an install before it records a fetched set. It costs about 0.2 to 1 second; an install runs it once per newly published set (and once more after its own code changed), inside the background check, never on a caller's path. A refusal names the step and the cause.
- **What an install cannot run**: a reference row whose account family or bundle harness the launch code does not know (`account_fleet.LAUNCH_FAMILIES`, `LAUNCH_HARNESSES`), or whose effort is not in the set's own `dispatch_efforts` row for its harness, rejects the whole set: complete or absent, a model that needs new code needs a release. The effort table is data in the same set, so this check holds a bundle to its own set, not to what a CLI accepts. A field this code does not read is ignored, like any unknown field; data whose meaning needs newer code under the same schema is what the schema bump is for.
- **Launch values**: the declared patterns (`scripts/launch_values.py`: a model id `[A-Za-z0-9][A-Za-z0-9._:/@+\[\]-]*`, a bundle id the same plus `#`, every other name one word `[A-Za-z0-9][A-Za-z0-9._-]*`) apply to reference data only, where it enters (`account_fleet.launch_problems` on the source document of `load_accounts`): a reference row that does not match is a named `ReferenceDataError` that refuses the set. They accept every shipped value and every id this code generates (`auto:<account>:<harness>:<model>@<effort>`, its `#<sha8>` collision suffix). Values from the user's machine (account names, model ids a provider lists, the rows `provider_inventory.listed_rows` derives for a model the user named and the effort named with it, ids derived from them) are never dropped by a pattern; they are made safe where they are used: passed as their own argument (`launch_values.argument`, which refuses an empty value, a leading `-`, a line break or NUL), quoted for the syntax they land in (`launch_values.toml_string` for codex `-c model_reasoning_effort=`, `launch_values.shell_word` in the Orca command a parent runs) or reduced to a file-name part (`launch_values.path_part` for a CLI run directory). A value that cannot be expressed safely refuses that one launch with a named `LaunchValueError`, before anything is written for it; the account and its other bundles stay. "Its own argument" holds on Windows because no launch passes a value through cmd.exe (which reads `&`, `|`, `^`, `>` and `%NAME%` in an argument as commands, whatever the quoting): a batch launcher (`.cmd`/`.bat`: an npm shim, Paseo's `paseo.cmd`) is started as the program its launch line runs, read from the file by one rule for every CLI (`launch_values.program`: the last line that passes `%*`, its `%~dp0` and `set` variables expanded, the program an existing file, the variables the launcher sets carried along), never as itself. Every place that starts a program a caller, a provider listing or reference data reaches goes through it: `subscription_cli.cli_prefix` and `direct_prefix` (CLI workers in `roll.cli`, grok's configured path, the scorer, Herdr's `hc`), the tray's `owned_process.run` and `direct` (the model catalog's `paseo.cmd`, CLI updates, the Dot reconnect's node), `run` in `tray/updates.py` and the Paseo reload in `setup/sync_host_globals.py`. A launcher that cannot be read that way (its line goes on after `%*`, a variable that cannot be expanded, a program that does not exist, or a variable it sets that the caller cannot carry) refuses the launch with `launch_values.UnreadableLauncher`, naming the file and why, before anything starts; nothing falls back to cmd.exe, and `launch_values` holds no list of characters cmd.exe treats specially.
- **Never on the failure line**: if a reader fails on the fetched set at run time all the same (a shape the acceptance did not exercise, such as a field only the live fleet reaches), the read-only part of the run is repeated on the shipped set as a whole (`public_data.with_fallback`; the tray falls back the same way when it rebuilds). Three rules bound it:
  - *No effect is repeated.* An effect is what the call itself decided, and each is marked before or as it happens (`public_data.effect`): a ledger row (`decision_ledger.append_ledger`, also for a named record and `roll --resume`'s record; a data error of a fetched set while it marks the row's `outside_automatic_routing` comes before the row and re-runs the stage), a reservation or dispatch row (a committed change in `dispatch_registry.transaction`), an override it was asked to write (`quota_overrides.manage_overrides`, at the write), a launch (marked before anything starts: the CLI `Popen` in `roll.cli`, Dot in `roll.dot`, grok-bot in `roll.grok_bot`, Herdr in `host_herdr._launch` after its launch values are checked, and the Paseo bridge's `create` and `resume` in `dispatch_flow.host_call`). Bringing recorded state in step with what happened on its own is not an effect: a lease that ran out, a worker that ended, a side effect, ground truth or end notice an earlier dispatch owes (`dispatch_registry.transaction(upkeep=True)`; an end notice is sent once, `mark_end_notice_sent`). The classifier calls are not effects, since they come first and would end the fall-back for nearly every plan; their answer is carried instead (`public_data.carried`, keyed by the question, which does not depend on the set): a re-run never asks the scorer or `classify_structured` again. An error after the first effect is the run's answer and nothing is re-run. Per entry point: a `route_judge` stage (`plan`, `roll`, `providers`, `record`, ...) re-runs only when it failed before its first effect, from freshly parsed arguments and the caller's input as first read: stdin (`roll --task -`, `scorer set --api-key -`) and the files named by `--input` and `--brief` are read once, before the part that may run again (`caller_input`). Every failure, a data-class error included, is reported as the stage's named error (`error_type`), never as a traceback. The gate hook falls back around its reference reads only (the rotation threshold, `load_dispatch_accounts`, the accounts and window verdict of `check_account_quota_exhausted`), never around the end notices it delivers, and its allow-all degrade applies only when the shipped set fails too.
  - *A refusal is not a data error.* Only a data error re-runs: `public_data.ReferenceDataError` (a reader's explicit shape check) or `LookupError`, `TypeError`, `AttributeError`, `ArithmeticError` (`public_data.is_data_error`). Every other `ValueError` (a refusal such as `named_model_unavailable`, a quota refusal, a `dispatch_registry` refusal, an input error), `OSError` and `sqlite3` errors are answers, never re-run and never blamed on the set.
  - *A run-time blame is not permanent.* When the shipped set succeeds where the fetched one failed, the fetched set is set aside for `SET_ASIDE_HOURS` (24 hours) by this code (`set_aside_version`, `set_aside_by`, `set_aside_at`, `set_aside_until`, `set_aside_error`, `set_aside_note` in `state.json`); while it is in effect `doctor` names it with the error (`set_aside` in the status) and `plan` warns `reference_data_refused`. It is in effect only for the code that recorded it, from `set_aside_at` (a start in the future is a clock that ran ahead and is no set-aside, as for a check time in the future) until `set_aside_until`, and only for a period no longer than `SET_ASIDE_HOURS`. It is taken again when the period ends, at once when a newer set is accepted or this install's code changes; an ended set-aside is cleared where it is read, so nothing reports it afterwards (`public_data.set_aside`). A set that is truly bad costs one failed attempt and one re-run per process that tries it, once every 24 hours. Only the acceptance rejects a set for good (`rejected_version`); a failure the shipped set produces as well blames nothing, and costs one more run of the stage: that call runs twice, on the fetched set and on the shipped one, before it reports the error.
- **Data schema**: `public_data.SCHEMA_VERSION` (8 since v0.7.1: `agent-compass.five-axis-scores/12` and the effort, series and listing declarations of `accounts.json`, `user-scores.json` schema 4; 7 was v0.7.0's, `agent-compass.five-axis-scores/6`, frozen in `published/7/`) binds the shape of the reference files to the code that reads them: an install fetches only `published/<its schema>/`. Bump it with any change after which a released reader of the previous schema would misread data written for this code (a new required field, a renamed key, a changed meaning). What the check covers: `--check-released` fails a publication that a released reader of the same schema refuses. What stays discipline: a change of meaning an older reader cannot detect (it reads the field and draws a different conclusion); the procedure in [Publishing a model between releases](../calibration/README.md#publishing-a-model-between-releases) says when to bump.
- **When and at what cost**: `roll`, `plan` and `providers` start a background check at most once every 6 hours (30 minutes after a failed attempt), in its own short-lived process (`public_data.py --refresh --claimed`); the caller pays one state read and, when a check is due, one locked state write and the process start, never the network or the acceptance. The tray updater runs `agentcompass data --refresh` after every update, and `agentcompass data --refresh` checks now. A check reads `<PUBLIC_DATA_URL><schema>/public-data.json` (`agentcompass/origin.py`: `https://raw.githubusercontent.com/akiiwa-games/AgentCompass/main/published/`) over plain HTTPS, with no credentials and only a `User-Agent: AgentCompass-public-data` and `Cache-Control: no-cache` header (`HTTPS_PROXY` / `NO_PROXY` and the system proxy apply), then only the files whose sha256 differs from what the install already has. An unchanged manifest costs one request. Each request times out after 5 seconds (10 for `agentcompass data --refresh`, which a user waits for). A recorded check or attempt time in the future (a clock that ran ahead) counts as no check. A 404 (nothing published yet for this schema) is a completed check with status `unpublished`: no `last_error`, the normal interval. Offline or slow, routing runs on the last accepted set, else the shipped copy; `data --refresh` then exits 0 and reports the outcome, also when another process holds the state (`busy`); exit 1 only when the state directory cannot be written.
- **Cache**: `~/.agent-compass/public-data/` (under `ROUTER_STATE_DIR` when set): `state.json` (version, `published_at`, `accepted_by`, `fetched_at`, `checked_at`, last error, note, a version the acceptance rejected, a version set aside at run time and until when), written under the process-safe lock of `override_store`, and `sets/<version>/` (the manifest and files; the current and previous sets are kept). Both are derived state: a recorded set of a data schema this code does not read (the cache an earlier version's channel left, such as v0.6.8's schema 6 under the same names) is removed where it is read, its state fields and every cached set not of `SCHEMA_VERSION`; `doctor` then names the shipped set as in effect, and the next check is due at once (`public_data._drop_other_schema`).
- **Precedence**: shipped copy < fetched set < your own settings (`~/.agent-compass/user-scores.json`, `accounts-override.json`, host policy and every other file you own; the channel writes none of them and writes only under `public-data/`). Manual capability scores follow `local user > maintainer (references/user-scores.json, shipped or published) > measured > estimated/converted`, mapped from the facet's demand-level scale (level 1 = panel minimum, 2 = median, 3 = panel maximum, unclamped beyond) (`agentcompass score set <model> <category>[.<facet>] <level> [--public]`; `agentcompass score suggest` prints read-only review suggestions against measured public boards without altering manual scores). Shipped references that differ from their own manifest (a checkout being edited) are read as they are.
- **Score keys**: a key of either `user-scores.json` names a model, not a provider's offer, so no provider's declaration is read (`user_scores.resolve_model_key`). A name whose maker moved it to a newer dated snapshot means what the name means now: the maker's declaration (`provider_names` `defaults`) is read first, so a score keyed `deepseek-v4-pro` lands on `deepseek-v4-pro-0813`. Otherwise a key is a row, an alias, its last `/` segment as a row, that segment as an alias. Keys of one file that land on one row merge by target, and the key that is the row's own id wins for each target both hold, whatever their order in the file (`user_scores.score_layer`). The file keeps its keys; only where a key lands follows the declarations. A key with an owner part is read as a full id first (`model_resolution.default_for`), so `deepseek-ai/deepseek-v4-pro` lands on the undated `deepseek-v4-pro`. A row whose own id is a moved name takes a score under a declared name that reaches it (`user_scores.score_key_for_row`); `agentcompass score set` and the tray write one key per row whatever the spelling given (`user_scores.write_key`: `score_key_for_row` of the resolved row), and clearing a row's score through either removes every stored key that lands on that row, also one written in another spelling before or by hand; a row nothing reaches takes none.
- **Visibility**: `agentcompass doctor` prints `Reference data:` (source, version, publication, fetch and check time, note); `agentcompass providers` includes it as `public_data`; `agentcompass data` prints the full status.
- **Off switch**: `AGENTCOMPASS_PUBLIC_DATA=off` (`0`, `false`, `no` also work), or `{"enabled": false}` in `~/.agent-compass/public-data-config.json`; the environment wins. Off means no network call, no read of the channel's state, and only the shipped copy is read. The same file accepts `interval_hours` and `url` (a mirror of the `published/` root); `AGENTCOMPASS_PUBLIC_DATA_INTERVAL_HOURS` and `AGENTCOMPASS_PUBLIC_DATA_URL` override them.
- **What a publication cannot add**: data only. A model whose launch needs code cannot be published this way: a new harness or provider (`account_fleet.LAUNCH_FAMILIES`, the Paseo bridge), a new launch field, a new account family or sign-in that discovery must find, or a new schema of any file (that bumps `SCHEMA_VERSION` and ships with a release). A model on an existing harness (a model row, alias, family row, bundle, `dispatch_efforts` row, its five-axis scores and maintainer scores) can be published, as `gemini-4-hydrogen-high` was added.
- **Provenance checks**: [`scripts/reference_provenance.py`](../scripts/reference_provenance.py) holds the reference files to the data provenance rule: every declaration in `accounts.json` and `plan-templates.json` is a dated public citation or a dated `maintainer` declaration, and `user-scores.json` holds `kind: "maintainer"` scores only. The refresh runs them before it writes and after it rebuilds, `data publish` and every install run them before accepting a set, and the test suite runs them on the shipped files. A score file of another schema is refused by `axis_scores.require_current_schema` with a message naming what to run.
- **Your own state across updates**: what a released version wrote for you is read in the current shape through one table of steps per file, each naming the earlier shape it reads, applied by the file's single loader before strict validation; a read never writes, and the next save writes the current shape. `user_scores.LOCAL_UPGRADES` (earlier score schema; from schema 3, a score under a name v0.7.0 resolved through an alias this release removed or re-targeted, `released_names.V0_7_0`, moves to the row v0.7.0 resolved it to), `accounts_override.LOCAL_UPGRADES` (`disabled` reason strings, the `migration_ambiguous_enabled` record of the v0.2.0 to v0.5.0 tray, which those releases never applied, and `allowed_cwd`), `state_upgrade.HOST_RULE_UPGRADES` (renamed tokens in the `shared.md`, `codex.md` and `daemon-append.md` overlays, which stay as written; only the retired `@@ROUTE_JUDGE@@` placeholder is refused, never a name in the user's prose), `provider_inventory.LOCAL_UPGRADES` (the launcher removals kept in `provider-inventory.json`) and the `plugins.load` autostart marker. The checkbox of an auto bundle is read where discovery lists the advertised names (`auto_bundles.choice_for`, from `auto_bundles.derive` and `accounts_override.apply`): a choice stored under the id v0.7.0 gave the bundle is that advertised name's own (`derive` replays the id in catalog order: the row v0.7.0 resolved the name to, `released_names.as_v0_7_0`, and for a later name of that row on the account the `#` tag of its advertised spelling), and a stored model name applies to the bundle it resolves to now, except an id the replay gives another advertised name of the account: that id is read only by the bundles of the model that name is now, and a bundle of another model whose id it would be takes its tagged id, so the two checkboxes stay apart from the first load; stored choices that disagree leave the bundle disabled and `agentcompass doctor` lists them once. An `allowed_cwd` becomes a `cwd_regex` only for an entry the regex matches exactly as the v0.5.0 path-component matcher did (`accounts_override._entry_carries_over`); the others are refused with the edit that carries them. Callers read `accounts-override.json` through `accounts_override.load_override` (the tray edit and the usage collector included), never with their own `json.loads`. A shape whose meaning depends on something the file does not say is refused with the file named, not guessed. A local score under a name that resolves to no catalogue row is kept in the file, ignored for scoring (never made a row, `user_scores.apply_overlay`) and named once by `agentcompass doctor` (`state_upgrade.check_user_scores`). `host-policy.json` names accounts (and, when a release with the select and delegate stages wrote it, judges, kept as written and read by nothing), no model, so no name step applies to it. Caches, ledgers and the dispatch database are rebuilt or skipped, never migrated: `dispatch_registry.prepare` refuses a decision an earlier version recorded in a shape this one does not read (`dispatch_registry.earlier_version`: an older task profile, or a field only AgentCompass sets in its stored task) by itself, never the database, and `dispatch_fallback.Chain.run` ends such a dispatch's failure with `older_profile` instead of replanning it; the caller-task check (`task_intake.check_caller_task`) runs only where a caller's task enters, never on a stored one; an inventory that cannot be read, or of an unknown schema that holds removals, fails with its message (`provider_inventory.previous_inventory`) instead of being replaced. A refusal that remains prints a fix that works when followed and says what deleting the file discards.
- **Maintainers**: as a step of preparing a release, run `agentcompass data refresh` (or `agentcompass data refresh --no-fetch` from cached downloads; add `--accept-panel-change` to write a rebuild whose panel members changed, which is otherwise refused; [`calibration/refresh.py`](../calibration/refresh.py)) to rebuild `public-measurements.json`, `five-axis-scores.json`, `model-capabilities.json` and `model-capabilities.md` in topological order and validate the provenance checks and the `user-scores.json` schema, then `agentcompass data publish`. Adding a model is the catalogue edit plus `agentcompass data refresh --model <id>`, which keeps what it fetched as that model's own entry in the calibration cache (every later rebuild, `--no-fetch` too, takes the model's rows from it) and merges only that model's measurement entries, conflicts and checks into the shipped `public-measurements.json` (board z-scores on the shipped scale of each source, corrected by the board's panel-measured drift when the board moved since the release snapshot, the tier put on the release snapshot's tier scale, so with the panel scale unchanged the model's measurement row equals a full refresh's) and rebuilds the rest; fleet fits are frozen per release, so the model's rows are scored by the release's fits and no other row, fit or target moves (a panel model or the anchor is refused and needs the full refresh), then `agentcompass data publish`, commit and push: installs pick it up at their next check ([Publishing a model between releases](../calibration/README.md#publishing-a-model-between-releases)). After hand-editing `accounts.json`, `plan-templates.json`, `classifier-cases.json` or `user-scores.json` (`agentcompass score set ... --public`), run `agentcompass data refresh --no-fetch` and `agentcompass data publish`. A breaking data change bumps `SCHEMA_VERSION` in `public_data.py`: the next `data publish` writes `published/<new>/`, which only the release that carries the change reads, and installs of the older schema keep `published/<old>/`.
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 CodeCodexVerifiedInstall
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