@kontextmind/kxm
Version:
KXM local-first multi-agent orchestration and operator dashboard
200 lines (144 loc) • 14.6 kB
Markdown
# Harness routing internals
This page records how the KXM repository applies [harness routing](../reference/harness-routing.md) to its own work: the routes this checkout admits, its writer roster, its price catalog, and the developer roster policy that `just assign` and the dev helper enforce. It is maintainer material. The route and roster transcripts below were regenerated on 2026-09-28 from this checkout, where `node scripts/kxm.mjs` is the same program as `kxm`. Readiness notes that name a capture machine are from 2026-09-23 and were not re-probed. The transcripts change whenever an admission changes.
> [!IMPORTANT]
> The files are the authority, not this page: `.kxm/routes.yaml`, `.kxm/roles/*.yaml`, `.kxm/models/*.yaml`, and `.kxm/prices.yaml`. Product routing decisions are recorded under Tracking → Decided in `plans/implementation-plan.md`.
## Current ids (2026-09-27)
The files use one id shape per kind. A route id is `<harness>-<model-slug>[-<provider>]`, with `.` written as `-`. An agent id equals its role. A workflow id is `default`, `land`, or `<role>-only`. An agent step id equals that role.
This checkout's routes are `grok-grok-4-7`, `pi-qwen3-coder-plus-openrouter`, `agy-gemini-3-8-flash-high`, `agy-gemini-3-8-flash-medium`, `claude-fable`, `codex-gpt-5-6-sol`, `pi-qwen3-8-flash-openrouter`, and `pi-glm-5-3-flash-openrouter`. Agents are `planner`, `writer`, `reviewer-arch`, and `reviewer-cli`. `opus-claude` was removed because `opus` is not an admitted selector. `qwen-token-plan/*` and `zai-coding-cn/*` left the admitted list because those harnesses are not allowlisted; their `prices.yaml` rows stay. Old ids resolve as aliases. Every roster entry names an effort. `reviewer-arch` dispatches `claude-fable`. #343's architecture critic ran on opus because the justfile recipe review-arch hardcoded that model; the role file on that commit listed only `fable-claude`. The helper now refuses `opus`.
## This checkout's routes and roster
`node scripts/kxm.mjs role get writer`:
```text
schema: kxm.role.v2
id: writer
purpose: writer
permission: edit
description: Primary implementation agent.
skills: []
roster:
- route: grok-grok-4-7
effort: medium
- route: pi-qwen3-coder-plus-openrouter
effort: medium
- route: agy-gemini-3-8-flash-high
effort: medium
- route: agy-gemini-3-8-flash-medium
effort: medium
```
The writer role lists route ids, in order: `grok-grok-4-7`, then `pi-qwen3-coder-plus-openrouter`, then `agy-gemini-3-8-flash-high` and `agy-gemini-3-8-flash-medium`. `grok-grok-4-7` is harness `grok`, model `grok-4.7`, vendor `xai`. An agent file does not declare `harness:`.
`node scripts/kxm.mjs routes list`:
```text
admitted anthropic/fable
admitted google/gemini-3.8-flash-high
admitted google/gemini-3.8-flash-medium
admitted openai/gpt-5.6-sol
admitted openrouter/qwen/qwen3-coder-plus
admitted openrouter/qwen/qwen3.8-flash
admitted openrouter/z-ai/glm-5.3-flash
admitted xai/grok-4.7
planner claude-fable
planner pi-qwen3-8-flash-openrouter
reviewer-arch claude-fable
reviewer-arch pi-glm-5-3-flash-openrouter
reviewer-cli codex-gpt-5-6-sol
reviewer-cli pi-qwen3-8-flash-openrouter
writer grok-grok-4-7
writer pi-qwen3-coder-plus-openrouter
writer agy-gemini-3-8-flash-high
writer agy-gemini-3-8-flash-medium
```
`routes admit --model openrouter/qwen/qwen3-coder-plus --dry-run` exits 2 with `select a model from the refreshed inventory` even though that selector is already admitted, because the inventory never carries `openrouter/…` selectors. Selectors like these are admitted by a Git-reviewed edit of `.kxm/routes.yaml`.
On the capture machine, `kxm harness list` showed `claude` detected but logged out (`dispatch no (not_authenticated)`), `deepseek` not installed, and `grok`, `codex`, `kimi` and `agy` ready.
### Price catalog and inventory
`.kxm/prices.yaml` is dated `2026-09-28`. A run on that date can record a list estimate. Any other day records `providerMetadata.priceCatalogStale: true` and no list estimate. The list prices below come from `.kxm/models/inventory.yaml`. OpenRouter and Nous were fetched at `2026-09-28T14:02:09.052Z`. `pi`, `grok`, and `agy` were not installed for that refresh, so models that exist only in those CLIs are still the 2026-09-16 rows. Prices are USD per 1M tokens. The checkout has no routing records yet, so none of the examples has recorded latency; for latency, run a bounded side-by-side experiment and compare p50 and p95 in `kxm routing report`.
## The developer roster
The issue-127 runner (`kxm assign`, see the [assignment runner](assignment-runner.md)) reads `.kxm/roles/*.yaml` and `.kxm/models/*.yaml` at `refs/remotes/origin/main`. See [Developer assignment policy](../reference/config-reference.md#developer-assignment-policy). Routes there name the harness, the model and the vendor explicitly:
```yaml
grok-grok-4-7:
harness: grok
model: grok-4.7
vendor: xai
pi-qwen3-coder-plus-openrouter:
harness: pi
model: openrouter/qwen/qwen3-coder-plus
vendor: alibaba
```
The developer roster policy (`scripts/roster-policy.mjs`) applies these rules:
- A native route uses a bare model id.
- A Pi route needs an allowlisted prefix: `openrouter`, `nous-portal` or `antigravity` (`scripts/harness-run.mjs`).
- An aggregator id needs at least three segments.
- The vendor segment of an aggregator id must not be a native vendor. `x-ai` counts as `xai` and `moonshotai` counts as `moonshot`.
- `antigravity` ids must be exactly `antigravity/gemini-…`.
- The writer and both critics must be three different vendors.
Vendor independence has a consequence for Anthropic: the architecture critic is an Anthropic model, so no Anthropic route can be the writer through any harness, and `claude-bridge` stays experiment-only.
### What the developer tools refuse
The product layers are in [What the brake refuses](../reference/harness-routing.md#what-the-brake-refuses). The developer tools add two more:
| Layer | Where | What it refuses | What you see |
|---|---|---|---|
| Dev helper | `scripts/harness-run.mjs` | A braked Pi provider, a Pi provider outside the allowlist, a Pi writer other than `openrouter/qwen/qwen3-coder-plus`, or an aggregator id whose vendor segment is a native vendor | `pi brake: xai has a native harness; refusing Pi impersonation`, or `… refusing to bill it through openrouter` |
| Developer roster | `scripts/roster-policy.mjs` | An aggregator route whose vendor segment is a native vendor | `Roster policy refused: native vendor cannot use Pi` |
The dev helper's allowlist (`openrouter`, `nous-portal`, `antigravity`) is a different list from `PI_ALLOWED_PROVIDERS` in `plugins/kxm/src/harness.ts`, which gates nothing. Which of the two should govern is an open decision (Tracking → Still open). Edit permission exists only in the dev helper, and only for admitted writer or experiment routes. The helper accepts only a ChatGPT login for codex, not an API key.
The product brake, the dev helper and the roster policy now agree on the vendor segment: all three refuse `openrouter/x-ai/…` and `openrouter/anthropic/…`. They refuse the other native-vendor ids for different reasons. The product brake names `openai-codex/…`, `kimi-coding/…`, `claude-bridge/…` and `antigravity/claude-…` as a native vendor's own Pi provider; the helper and `validateRosterDocument` refuse them as unsupported Pi routes, because the provider is off the helper allowlist or `antigravity` is given a non-Gemini id (`unsupported Pi provider/model` in the roster policy). The product brake accepts `qwen-token-plan/…` and `zai-coding-cn/…`, which the developer tools do not allowlist.
## Worked examples on this checkout
These extend the generic examples on the reference page with this checkout's admissions, developer policy routes, readiness on the capture machine, and inventory prices.
### Grok 4.7
| | Native `grok` | Pi + OpenRouter |
|---|---|---|
| Selector | `xai/grok-4.7`: admitted, and first in the writer roster | `openrouter/x-ai/grok-4.7`: not admitted |
| Developer roster | `grok-grok-4-7`, the writer route with `edit` | Refused: `native vendor cannot use Pi` |
| Readiness | `grok` showed auth `yes` on the 2026-09-23 capture machine | `pi auth check --provider openrouter` returned `not_ready` on that capture |
| Billing | grok.com subscription (OAuth) | $1.60 input, $4.80 output, $0.40 cached input |
| Context | 500,000 (`x-ai/grok-4.7` in the refreshed inventory) | 500,000 |
Pi's own `xai` provider reported `ready` (OAuth) on the capture machine. When the grok quota runs out, the next writer in the lineup is `pi-qwen3-coder-plus-openrouter`, a different vendor.
### GPT-5.6 Sol
| | Native `codex` | Pi + OpenRouter |
|---|---|---|
| Selector | `openai/gpt-5.6-sol`: admitted, the CLI critic | `openrouter/openai/gpt-5.6-sol`: not admitted |
| Developer roster | `codex-gpt-5-6-sol`: `reviewer-cli`, `read-only` | Refused |
| Billing | ChatGPT subscription | $2.00 input, $10.00 output, $0.20 cached input |
| Context | Pi's `openai-codex` row, the same ChatGPT backend, lists 272K | 1,050,000 |
In the inventory, `openai/gpt-5.6-sol` has sources `openrouter+nous` and carries OpenRouter prices. `pi auth check --provider openai-codex` reported `ready` on the capture machine.
### Claude Fable
| | Native `claude` | Pi + OpenRouter |
|---|---|---|
| Selector | `anthropic/fable`: admitted, planner and architecture critic | `openrouter/anthropic/claude-fable-5.1`: not admitted |
| Developer roster | `claude-fable`: `planner` and `reviewer-arch`, `read-only` | Refused |
| Readiness | Detected `yes`, auth `no`, dispatch `no (not_authenticated)` | `not_ready` |
| Billing | claude.ai subscription | $10.00 input, $50.00 output, $0.25 cached input |
| Context | 1M (Pi's `anthropic` row) | 1,000,000 |
`claude` was logged out on the capture machine, so the native route failed closed. Pi's `anthropic` provider reported `ready` (OAuth). The `anthropic/fable` row in `prices.yaml` gives a list estimate only when the catalog is dated today.
### Gemini 3.8 Flash
| | Native `agy` | `antigravity` Pi provider | Pi + OpenRouter |
|---|---|---|---|
| Selector | `google/gemini-3.8-flash-high` and `google/gemini-3.8-flash-medium`: admitted, the last two writer routes | `antigravity/gemini-3.8-flash`: not admitted | `openrouter/google/gemini-3.8-flash`: not admitted |
| Billing | Google subscription | Google subscription | $0.75 input, $3.75 output, $0.075 cached input |
| Context | `agy` does not print it; the vendored catalog lists 1,048,576 | 1,048,576 | 1,048,576 |
The admitted runtime route today is the `agy` selector.
## Routing decisions for this repository
### Google through `antigravity`
The decision is that Google models run through the `antigravity` Pi provider, never through a shell-out to the `agy` CLI; `agy` stays a harness catalog and helper entry, not the admission path. Pi's `google/*` provider stays braked, and an `antigravity` route needs a signed-in `/login antigravity` inside Pi before it can be admitted. The dev helper and the roster policy accept only `antigravity/gemini-…`.
The code differs from that decision: `.kxm/routes.yaml` admits `google/gemini-3.8-flash-*`, which can run only through `agy`, and the Runtime's Pi one-shot runs with `--no-extensions`, so it cannot reach `antigravity/…`. Until an antigravity route is admitted, do not add one on your own.
### Vendors with no native harness
| Model | Vendor-plan route | OpenRouter route | Notes |
|---|---|---|---|
| Qwen3.8 Flash | `qwen-token-plan/qwen3.8-flash`: removed from the admitted list on 2026-09-27; `qwen-token-plan` is not allowlisted | `openrouter/qwen/qwen3.8-flash`: admitted, route `pi-qwen3-8-flash-openrouter`, read-only fallback for planner and reviewer-cli | `prices.yaml` keeps both rows. |
| Qwen3 Coder Plus | none | `openrouter/qwen/qwen3-coder-plus`: route `pi-qwen3-coder-plus-openrouter` | The only admitted Pi writer: exact model, `edit` permission. |
| GLM 5.3 and 5.3 Flash | `zai-coding-cn/glm-5.3` and `…/glm-5.3-flash`: removed from the admitted list on 2026-09-27; `zai-coding-cn` is not allowlisted | `openrouter/z-ai/glm-5.3-flash`: admitted, route `pi-glm-5-3-flash-openrouter`, read-only fallback for reviewer-arch | Z.ai has no native harness. |
| DeepSeek V4.1 Flash | `qwen-token-plan/deepseek-v4.1-flash`: removed from the admitted list on 2026-09-27 | `deepseek/deepseek-v4.1-flash` in the OpenRouter feed | Bills a DeepSeek model through Alibaba's plan. `deepseek` is a native-vendor Pi brake, so this is not a route. |
The developer runner is stricter. Its only Pi writer is `openrouter/qwen/qwen3-coder-plus`, and it does not allowlist `qwen-token-plan` or `zai-coding-cn`. Today OpenRouter is the right answer here for Qwen3 Coder Plus, Qwen3.8 Flash and GLM 5.3 Flash.
### Nous
`nous-portal/tencent/hy4-preview` is the reviewed experiment example, and it is not a writer. Pi on the capture machine listed `nous-portal/tencent/hy3-preview`, not `hy4-preview`, so check live ids before you use them. The dev helper does not allowlist `nous/…` or `nous-proxy/…`, and the roster policy refuses Portal routes to native vendors, just as it refuses the OpenRouter copies.
## Troubleshooting the developer tools
| Symptom | Cause | Fix |
|---|---|---|
| `pi brake: xai has a native harness; refusing Pi impersonation` | A dev-helper request routed a native vendor through Pi. | Use the native harness through `kxm lane run <unit> --brief <file> --workflow review-arch-only`. |
| `Roster policy refused: native vendor cannot use Pi` | A Pi route in `.kxm/models/*.yaml` names a native vendor, as in `openrouter/x-ai/…` or `nous-portal/anthropic/…`. | Remove the route. Only a native harness route is valid for that vendor. |
| The dev helper refuses a codex route. | `codex` is logged in with an API key. | Run `codex login` with the ChatGPT flow. |
For example, the native writer recipe:
```bash
kxm lane run <unit> --brief <file> --workflow implement-only
```
## Related
- [Harness routing](../reference/harness-routing.md): the rules, the decision procedure and the generic examples
- [Assignment runner](assignment-runner.md): the loop that enforces the developer roster
- [Configuration file reference](../reference/config-reference.md#developer-assignment-policy): the developer assignment policy fields
- [Routing and cost telemetry contract](../contracts/routing.md): the routing record, cost basis and dev-helper telemetry