@kontextmind/kxm 0.7.128 → 0.7.131

package/docs/reference/harness-routing.md

@@ -99,35 +99,43 @@ pi auth check --model openrouter/qwen/qwen3-coder-plus --json --no-refresh
 
 ### How KXM builds a route
 
-- **Selector.** The selector is `<model.provider>/<model.model>`, taken from the agent YAML. The provider must not contain `/`. The model id may, for example `qwen/qwen3-coder-plus` under `openrouter`.
-- **Harness.** The harness is the agent's `harness:`, or the project's `defaultHarness` (Pi) when the agent omits it. The selector string does not choose the harness, and neither does a roster entry.
-- **Admission.** The selector must be admitted, and it must be in the role roster when that role file exists. Agent id `implementer` maps to role `writer`.
+- **Selector.** The selector is `<vendor>/<model>` from the selected `.kxm/models/<route>.yaml`. The agent names a `role`, `.kxm/roles/<role>.yaml` lists route ids, and the chosen roster entry names that model file. The model id may contain `/`, for example `openrouter/qwen/qwen3-coder-plus`.
+- **Harness.** The harness is the `harness` field on that model file. An agent file does not select it.
+- **Admission.** The selector must be admitted. The engine uses the first roster entry whose model file is readable and whose route is admitted.
 - **Dispatch probe.** Before spawning anything, the producer probes the exact harness, provider and model triple. It refuses unhosted pairs and the Pi brake.
 - **Effort.** The Runtime sets the thinking effort per attempt: the first attempt of a step runs at `low`, and any later attempt of the same step at `medium`. The live producer passes it as `--effort` to `claude`, as `model_reasoning_effort` to `codex` and as `--reasoning-effort` to `grok`. `agy`, `kimi` and `pi` get no effort flag. A roster entry's `effort` is display-only.
 
 ### Agent YAML
 
-This is the native route, from `.kxm/agents/implementer.yaml`:
+An agent names a role and nothing else about the route:
+
+```yaml
+role: writer
+```
+
+`harness` and `model` on an agent file are refused at load (`retired_agent_routing_fields`). A step `model` is refused at load and again at dispatch (`producer_route_unsupported`).
+
+### Model file
+
+This is the native route, from `.kxm/models/grok-native.yaml`:
 
 ```yaml
 harness: grok
-model:
-  provider: xai
-  model: grok-4.6
+model: grok-4.7
+vendor: xai
 ```
 
-The selector is `xai/grok-4.6` and the harness is `grok`. The live one-shot producer spawns `grok --model grok-4.6 … --output-format json --single <prompt>`.
+The selector is `xai/grok-4.7` and the harness is `grok`. The live one-shot producer spawns `grok --model grok-4.7 … --output-format json --single <prompt>`.
 
-This is the same model through Pi and OpenRouter:
+This is the same vendor through Pi and OpenRouter, which the brake refuses:
 
 ```yaml
-# harness omitted: Pi
-model:
-  provider: openrouter
-  model: x-ai/grok-4.6
+harness: pi
+model: openrouter/x-ai/grok-4.6
+vendor: xai
 ```
 
-The selector is `openrouter/x-ai/grok-4.6` and the harness is `pi`. The Pi brake refuses it before Pi starts, because the vendor segment `x-ai` is xAI, which has a native harness. A vendor with no native harness runs in the same shape: with `model: qwen/qwen3-coder-plus`, Pi is spawned with `--model openrouter/qwen/qwen3-coder-plus`, its read-only flags (section 3) and `-p --mode json`. Write `model.model` exactly as the provider names it. For OpenRouter that is the vendor slug, so `x-ai`, not `xai`.
+The selector is `openrouter/x-ai/grok-4.6` and the harness is `pi`. The Pi brake refuses it before Pi starts, because the vendor segment `x-ai` is xAI, which has a native harness. A vendor with no native harness runs in the same shape: with `model: openrouter/qwen/qwen3-coder-plus`, Pi is spawned with `--model openrouter/qwen/qwen3-coder-plus`, its read-only flags (section 3) and `-p --mode json`. Write `model` exactly as the provider names it. For OpenRouter that is the vendor slug, so `x-ai`, not `xai`.
 
 The harness and the selector have to agree. Pi refuses `provider: xai` and `openrouter/x-ai/…`. `grok` refuses `provider: openrouter`. [What the brake refuses](#what-the-brake-refuses) has the exact messages.
 
@@ -152,9 +160,9 @@ roster:
 
 `grok-native` resolves to `.kxm/models/grok-native.yaml`: harness `grok`, model `grok-4.7`, vendor `xai`, status `admitted`, permission `edit`. `qwen-openrouter-pi` is harness `pi`, model `openrouter/qwen/qwen3-coder-plus`, vendor `alibaba`. `gemini-agy` is harness `agy`, model `gemini-3.8-flash-high`, vendor `google`. `kxm role list` prints the first route id as the primary, for example `(grok-native)`.
 
-The model that runs a step still comes from the agent file. The harness is the agent's `harness:`, or Pi when the agent omits it. A route file records which harness can host that model; it does not replace the agent. If the implementer agent declares `harness: grok`, only the Grok selector can run under it. A Pi selector under that agent fails closed with `grok_not_authenticated: grok harness not detected (harness_unhosted_model)`. To run a Pi selector, create a separate agent with `harness:` omitted. The engine does not walk the roster to fail over on its own.
+Dispatch resolves a step from the agent `role`, then `.kxm/roles/<role>.yaml`, then the selected `.kxm/models/<route>.yaml`. That model file carries `harness`, `model`, `vendor`, `status`, and `permissions`. The engine walks the roster in order and uses the first admitted route whose model file is readable. A missing or unreadable model file is a refusal (`roster_model_unreadable` at load, `producer_route_unsupported` at dispatch), not a skip to the next entry. A route file that names a harness the model cannot run on still fails closed with `harness_unhosted_model`.
 
-Dispatch still reads `.kxm/roster.yaml` until P2. Role files are what `kxm role` and the Runtime membership check use.
+Role files are what `kxm role` and the Runtime membership check use.
 
 ### Route ids in `.kxm/routes.yaml`
 
@@ -308,7 +316,7 @@ kxm routing report --file ./run-events.jsonl --equivalent-list-cost
 
 ## 3. Examples: the same model, two routes
 
-Each example shows the agent YAML for the native route and for the same model through Pi, and which one the rules pick. For a native vendor, the Pi brake refuses the Pi column; it is shown so that you recognize the id. Whether a route is admitted is in your `.kxm/routes.yaml`. List prices and context sizes are in `.kxm/models/inventory.yaml` after `kxm models inventory-refresh`, and `pi --list-models` shows context, max output, thinking and image support per model. A provider missing from `pi --list-models` usually has no credentials, which is itself a readiness hint.
+Each example shows the model file for the native route and for the same model through Pi, and which one the rules pick. For a native vendor, the Pi brake refuses the Pi column; it is shown so that you recognize the id. Whether a route is admitted is in your `.kxm/routes.yaml`. List prices and context sizes are in `.kxm/models/inventory.yaml` after `kxm models inventory-refresh`, and `pi --list-models` shows context, max output, thinking and image support per model. A provider missing from `pi --list-models` usually has no credentials, which is itself a readiness hint.
 
 ### How the live producer runs each harness
 
@@ -330,7 +338,7 @@ The Runtime does not run a step live when it has `write` access to a repository;
 
 | | Native `grok` | Pi + OpenRouter |
 |---|---|---|
-| Agent YAML | `harness: grok`, `provider: xai`, `model: grok-4.6` | `harness:` omitted, `provider: openrouter`, `model: x-ai/grok-4.6` |
+| Model file | `harness: grok`, `model: grok-4.6`, `vendor: xai` | `harness: pi`, `model: openrouter/x-ai/grok-4.6`, `vendor: xai` |
 | Selector | `xai/grok-4.6` | `openrouter/x-ai/grok-4.6` |
 | Billing | grok.com subscription (OAuth) | OpenRouter credit |
 | Recorded `costBasis` | `unknown` | None: the brake refuses it before dispatch |
@@ -350,7 +358,7 @@ pi auth check --provider xai --json --no-refresh
 
 | | Native `codex` | Pi + OpenRouter |
 |---|---|---|
-| Agent YAML | `harness: codex`, `provider: openai`, `model: gpt-5.6-sol` | `harness:` omitted, `provider: openrouter`, `model: openai/gpt-5.6-sol` |
+| Model file | `harness: codex`, `model: gpt-5.6-sol`, `vendor: openai` | `harness: pi`, `model: openrouter/openai/gpt-5.6-sol`, `vendor: openai` |
 | Selector | `openai/gpt-5.6-sol` | `openrouter/openai/gpt-5.6-sol` |
 | Readiness | Needs `codex` auth `yes` with `authMethod: ChatGPT` | Never reached: the brake refuses it first |
 | Billing | ChatGPT subscription | OpenRouter credit |
@@ -373,7 +381,7 @@ A larger context window on the OpenRouter route does not make OpenRouter an allo
 
 | | Native `claude` | Pi + OpenRouter |
 |---|---|---|
-| Agent YAML | `harness: claude`, `provider: anthropic`, `model: fable` | `harness:` omitted, `provider: openrouter`, `model: anthropic/claude-fable-5.1` |
+| Model file | `harness: claude`, `model: fable`, `vendor: anthropic` | `harness: pi`, `model: openrouter/anthropic/claude-fable-5.1`, `vendor: anthropic` |
 | Selector | `anthropic/fable` | `openrouter/anthropic/claude-fable-5.1` |
 | Billing | claude.ai subscription | OpenRouter credit |
 | Recorded `costBasis` | `unmetered`, `priceRef: subscription:claude`, plus a list estimate when `prices.yaml` has an `anthropic` row dated today | None: refused before dispatch |
@@ -385,7 +393,7 @@ A larger context window on the OpenRouter route does not make OpenRouter an allo
 
 | | Native `agy` | `antigravity` Pi provider | Pi + OpenRouter |
 |---|---|---|---|
-| Agent YAML | `harness: agy`, `provider: google`, `model: gemini-3.8-flash-high` | `harness:` omitted, `provider: antigravity`, `model: gemini-3.8-flash` | `harness:` omitted, `provider: openrouter`, `model: google/gemini-3.8-flash` |
+| Model file | `harness: agy`, `model: gemini-3.8-flash-high`, `vendor: google` | `harness: pi`, `model: antigravity/gemini-3.8-flash`, `vendor: google` | `harness: pi`, `model: openrouter/google/gemini-3.8-flash`, `vendor: google` |
 | Selector | `google/gemini-3.8-flash-high` | `antigravity/gemini-3.8-flash` | `openrouter/google/gemini-3.8-flash` |
 | Readiness | Needs `agy` auth `yes` (`antigravity-oauth`) | Registered only by the KXM Pi extension. `pi auth check` never loads extensions, so `pi auth check --provider antigravity` returns `provider_not_found`. | Never reached: the brake refuses it (vendor segment `google`) |
 | Billing | Google subscription | Google subscription | OpenRouter credit |

package/docs/reference/workflow-catalog.md

@@ -1094,11 +1094,11 @@ This cross-reference points each software and security workflow at the KXM pages
 
 These three files live in this repository's `.kxm/workflows`. `kxm init` does not write them.
 
-| Workflow | Replaces |
+| Workflow | Runs through |
 |---|---|
-| `implement-only` | `just impl`. The recipe is retired once this lands. |
-| `review-arch-only` | `just review-arch`. The recipe is retired once this lands. |
-| `review-cli-only` | `just review-cli`. The recipe is retired once this lands. |
+| `implement-only` | `kxm lane run`. Replaces a retired transport recipe. |
+| `review-arch-only` | `kxm lane run`. Replaces a retired transport recipe. |
+| `review-cli-only` | `kxm lane run`. Replaces a retired transport recipe. |
 
 ## Related
 

package/docs/start/first-workflow.md

@@ -254,7 +254,7 @@ The file is a `kxm.workflow.v1` definition. `coordinator` names the agent that o
 | Cost | None | Model usage on your accounts |
 
 > [!WARNING]
-> Without `--simulated`, `kxm runs drive` calls live harnesses. An agent whose model is not an admitted route fails with `producer_route_not_admitted`. Read [Harness routing](../reference/harness-routing.md) before your first live drive. A live step with `write` access runs only on a harness with an audited writer profile (`pi` or `grok`), as a single assignment, in a project whose `limits.maxConcurrentRuns` is 1, and, when `.kxm/roster.yaml` exists, only on a route in its writer lineup; any other live write step is handed off. A live write step settles `passed` only when the checkout changed, and a read-only step that changes the checkout settles `failed`. Gate steps are exempt. The read-only `spec-and-plan` template needs none of this.
+> Without `--simulated`, `kxm runs drive` calls live harnesses. An agent whose model is not an admitted route fails with `producer_route_not_admitted`. Read [Harness routing](../reference/harness-routing.md) before your first live drive. A live step with `write` access runs only on a harness with an audited writer profile (`pi` or `grok`), as a single assignment, in a project whose `limits.maxConcurrentRuns` is 1, and only on a route in the writer roster under `.kxm/roles/writer.yaml`; any other live write step is handed off. A live write step settles `passed` only when the checkout changed, and a read-only step that changes the checkout settles `failed`. Gate steps are exempt. The read-only `spec-and-plan` template needs none of this.
 
 ### Why start with `first` and not `default`
 

package/examples/project/.kxm/agents/coordinator.yaml

@@ -1,7 +1,6 @@
 schema: kxm.agent.v1
 purpose: Coordinate the pinned workflow and emit only schema-validated commands.
-model:
-  profile: primary
+role: planner
 tools:
   preset: coordinator
 defaultRepositoryAccess: read

package/examples/project/.kxm/agents/critic-1.yaml

@@ -1,8 +1,6 @@
 schema: kxm.agent.v1
 purpose: First fixed-identity critic for migrated strict producer policies.
-harness: claude
-model:
-  profile: critic-claude
+role: reviewer-arch
 tools:
   preset: read-only
 defaultRepositoryAccess: read

package/examples/project/.kxm/agents/critic-2.yaml

@@ -1,7 +1,6 @@
 schema: kxm.agent.v1
 purpose: Second fixed-identity critic for migrated strict producer policies.
-model:
-  profile: critic-grok
+role: reviewer-cli
 tools:
   preset: read-only
 defaultRepositoryAccess: read

package/examples/project/.kxm/agents/critic-3.yaml

@@ -1,7 +1,6 @@
 schema: kxm.agent.v1
-purpose: Third provider-distinct critic used by the KXM MOA target.
-model:
-  profile: critic-gemini
+purpose: Third architecture critic, bound to reviewer-arch like critic-1.
+role: reviewer-arch
 tools:
   preset: read-only
 defaultRepositoryAccess: read

package/examples/project/.kxm/agents/implementer.yaml

@@ -1,7 +1,6 @@
 schema: kxm.agent.v1
 purpose: Implement the approved plan in the assignment-owned repository worktree.
-model:
-  tag: implementation
+role: writer
 tools:
   preset: workspace-writer
 defaultRepositoryAccess: none

package/examples/project/.kxm/agents/planner.yaml

@@ -1,7 +1,6 @@
 schema: kxm.agent.v1
 purpose: Produce an implementation plan grounded in the pinned repositories and evidence.
-model:
-  tag: planning
+role: planner
 tools:
   preset: read-only
 defaultRepositoryAccess: read

package/examples/project/.kxm/agents/reproducer.yaml

@@ -1,7 +1,6 @@
 schema: kxm.agent.v1
 purpose: Create and execute a production-coupled failing reproduction without changing production code.
-model:
-  tag: implementation
+role: writer
 tools:
   preset: tests-writer
 defaultRepositoryAccess: none

package/examples/project/.kxm/agents/reviewer.yaml

@@ -1,7 +1,6 @@
 schema: kxm.agent.v1
 purpose: Independently review correctness, security, regression risk, and evidence.
-model:
-  tag: critic
+role: reviewer-cli
 tools:
   preset: read-only
 defaultRepositoryAccess: read

package/examples/project/.kxm/workflows/fix.yaml

@@ -92,10 +92,6 @@ steps:
     agent: critic-1
     maxAttempts: 3
     description: Verify reporter-path coupling, failure causality, expected behavior, and absence of production edits.
-    model:
-      tag: critic
-      capabilities:
-        - structured-output
     repositories:
       control: read
       api: read
@@ -110,8 +106,6 @@ steps:
       maximum: 3
       maxParallel: 3
       maxAttemptsPerAssignment: 2
-      distinctBy:
-        - provider
     join:
       strategy: all-settled
       minimumPassed: 2
@@ -165,10 +159,6 @@ steps:
     agent: critic-1
     maxAttempts: 3
     description: Independently review the plan for correctness, scope, security, and regression risk.
-    model:
-      tag: critic
-      capabilities:
-        - structured-output
     repositories:
       control: read
       api: read
@@ -183,8 +173,6 @@ steps:
       maximum: 3
       maxParallel: 3
       maxAttemptsPerAssignment: 2
-      distinctBy:
-        - provider
     join:
       strategy: all-settled
       minimumPassed: 2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.128",
+  "version": "0.7.131",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",
@@ -34,12 +34,12 @@
     "build:runtime": "node scripts/build-runtime.mjs",
     "build": "npm run build:mcp && npm run build:runtime && npm run build:packages",
     "check:generated": "npm run build && node scripts/check-generated.mjs",
-    "test:core": "npm run build && node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-concurrency=4 test/core/*.test.ts",
-    "test:simulations": "npm run build && node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-concurrency=4 test/simulations/*.test.ts",
-    "test:complete": "npm run build && node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-concurrency=4 test/core/*.test.ts test/simulations/*.test.ts",
-    "test": "npm run build && node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-concurrency=4 test/core/*.test.ts packages/core/*/tests/unit/*.test.ts",
-    "test:coverage:core": "npm run build && node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-concurrency=4 --experimental-test-coverage --test-coverage-lines=91 --test-coverage-branches=80 --test-coverage-functions=92 --test-coverage-include=plugins/kxm/src/**/*.ts --test-coverage-exclude=plugins/kxm/src/server.ts --test-coverage-exclude=plugins/kxm/src/mcp-server.ts --test-coverage-exclude=plugins/kxm/src/runtime-supervisor.ts --test-coverage-include=packages/core/*/src/**/*.ts test/core/*.test.ts packages/core/*/tests/unit/*.test.ts",
-    "test:coverage:complete": "npm run build && node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-concurrency=4 --experimental-test-coverage --test-coverage-lines=93 --test-coverage-branches=80 --test-coverage-functions=93 --test-coverage-include=plugins/kxm/src/**/*.ts --test-coverage-exclude=plugins/kxm/src/server.ts --test-coverage-exclude=plugins/kxm/src/mcp-server.ts --test-coverage-exclude=plugins/kxm/src/runtime-supervisor.ts --test-coverage-include=packages/core/*/src/**/*.ts test/core/*.test.ts test/simulations/*.test.ts packages/core/*/tests/unit/*.test.ts",
+    "test:core": "npm run build && node scripts/run-bounded.mjs 1200000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 test/core/*.test.ts",
+    "test:simulations": "npm run build && node scripts/run-bounded.mjs 1200000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 test/simulations/*.test.ts",
+    "test:complete": "npm run build && node scripts/run-bounded.mjs 2400000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 test/core/*.test.ts test/simulations/*.test.ts",
+    "test": "npm run build && node scripts/run-bounded.mjs 1200000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 test/core/*.test.ts packages/core/*/tests/unit/*.test.ts",
+    "test:coverage:core": "npm run build && node scripts/run-bounded.mjs 2400000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 --experimental-test-coverage --test-coverage-lines=91 --test-coverage-branches=80 --test-coverage-functions=92 --test-coverage-include=plugins/kxm/src/**/*.ts --test-coverage-exclude=plugins/kxm/src/server.ts --test-coverage-exclude=plugins/kxm/src/mcp-server.ts --test-coverage-exclude=plugins/kxm/src/runtime-supervisor.ts --test-coverage-include=packages/core/*/src/**/*.ts test/core/*.test.ts packages/core/*/tests/unit/*.test.ts",
+    "test:coverage:complete": "npm run build && node scripts/run-bounded.mjs 2400000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 --experimental-test-coverage --test-coverage-lines=93 --test-coverage-branches=80 --test-coverage-functions=93 --test-coverage-include=plugins/kxm/src/**/*.ts --test-coverage-exclude=plugins/kxm/src/server.ts --test-coverage-exclude=plugins/kxm/src/mcp-server.ts --test-coverage-exclude=plugins/kxm/src/runtime-supervisor.ts --test-coverage-include=packages/core/*/src/**/*.ts test/core/*.test.ts test/simulations/*.test.ts packages/core/*/tests/unit/*.test.ts",
     "test:coverage": "npm run test:coverage:core",
     "typecheck": "tsc --noEmit",
     "lint:docs": "markdownlint-cli2",
@@ -48,7 +48,7 @@
     "verify": "npm test && npm run check && npm run check:generated",
     "validate:claude": "claude plugin validate . --strict && claude plugin validate plugins/kxm --strict",
     "validate:ci": "npm run test:coverage && npm run check && npm pack --dry-run",
-    "validate:pr": "npm run build && npm run typecheck && node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-concurrency=4 test/core/artifacts-exist.test.ts test/core/ci-contract.test.ts test/core/envelope.test.ts test/core/envelope-contract.test.ts test/core/protocol.test.ts test/core/repo-root.test.ts test/core/routes-count.test.ts test/core/smoke.test.ts test/core/version-surfaces.test.ts && npm run check:versions && node scripts/check-generated.mjs",
+    "validate:pr": "npm run build && npm run typecheck && node scripts/run-bounded.mjs 1200000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 test/core/artifacts-exist.test.ts test/core/ci-contract.test.ts test/core/envelope.test.ts test/core/envelope-contract.test.ts test/core/protocol.test.ts test/core/repo-root.test.ts test/core/routes-count.test.ts test/core/smoke.test.ts test/core/version-surfaces.test.ts && npm run check:versions && node scripts/check-generated.mjs",
     "validate": "npm run validate:ci && npm run validate:claude",
     "test:packages": "npx nx run-many -t test --output-style=static",
     "check:packages": "npx nx run-many -t build,test:coverage,typecheck --output-style=static",

package/plugins/kxm/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "kxm",
   "displayName": "KXM",
-  "version": "0.7.128",
+  "version": "0.7.131",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",