@kontextmind/kxm 0.7.193 → 0.7.195

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "kxm",
       "source": "./plugins/kxm",
       "description": "Durable workflows, peer agents, and kxm tui",
-      "version": "0.7.193",
+      "version": "0.7.195",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/CHANGELOG.md

@@ -714,6 +714,14 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Fixed
 
+- **`kxm vision assert --route` selects the Pi model, and an unadmitted route names the fix.**
+  The flag used to change only the admission check. Pi still ran
+  `zai-coding-cn/glm-5.3-flash`. Another admitted id is now `pi --model <id>`
+  after the native-vendor brake. The verified default invocation is unchanged.
+  `route_not_admitted` includes the route id and `kxm routes admit --model`.
+  This checkout does not admit the default; pass
+  `--route openrouter/z-ai/glm-5.3-flash`.
+
 - **The weekly model refresh opens its pull request with a GitHub App.**
   `.github/workflows/refresh-models.yml` uses `actions/create-github-app-token`
   with repository secrets `KXM_REFRESH_APP_ID` and
@@ -731,7 +739,6 @@ All notable user-facing changes are documented here. The project follows [Semant
   the same). The refresh does not rewrite a shared anchor that a
   non-OpenRouter row depends on. `.kxm/prices.yaml` is dated 2026-10-20.
   The OpenRouter `standard` rates for those two inventory rows match.
-
 - **`kxm improve report` and `kxm routing report` include attempts settled in a registered lane.**
   Inside a KXM project, a present user-state `registry.db` is opened read-only at schema version 2. One query loads the home row and every lane row for that project id. Event-store paths come from the stored project keys, so a stale checkout path cannot hide a lane. A missing store stays a zero-record source. An absent registry, or a checkout that is not registered, still reads only that checkout's own store. `--file` still reads only the named file. See
   [kxm improve report](docs/reference/cli-reference.md#kxm-improve-report).

package/docs/README.md

@@ -121,6 +121,7 @@ KXM connects coding agents through a durable, authenticated [hub](glossary.md#hu
 | [Decisions](contributing/decisions.md) | Agents, maintainers | Medium-or-higher decisions from automated work, with weights and evidence |
 | [Learnings](contributing/learnings.md) | Agents, maintainers | Durable lessons from running the writer, landing, and docs loops |
 | [Planner bake-off, October 2026](evals/planner-bakeoff-2026-10.md) | Maintainers | Scored plans from two planner models on six KXM tasks, with cost and time |
+| [October 2026 gap audit](audits/2026-10-gap-audit.md) | Maintainers | What the 2026-10-21 pass fixed, and the decisions still waiting on the operator |
 | [Artifact templates](templates/README.md) | Workflow authors | Document templates and where workflows use them |
 
 The templates: [feature](templates/feature.md) · [bug fix](templates/bug-fix.md) · [ADR](templates/adr.md) · [architecture](templates/architecture.md) · [research](templates/research.md) · [review](templates/review.md) · [test plan](templates/test-plan.md) · [test report](templates/test-report.md) · [runbook](templates/runbook.md) · [postmortem](templates/postmortem.md) · [handoff](templates/handoff.md).

package/docs/audits/2026-10-gap-audit.md

@@ -0,0 +1,87 @@
+# October 2026 gap audit
+
+This page records the gap audit of this repository on 2026-10-21, against `main` at `19ec8a5`. It is for the operator who still has to decide runner placement, route admission, and the witnesses already listed in Tracking. The four code fixes from this pass are separate pull requests.
+
+The pass compared the CLI, routing, and CI workflows with the docs, the tests, and `.kxm/knowledge`. It left `.kxm/prices.yaml` and `.github/workflows/refresh-models.yml` untouched because [pull request #410](https://github.com/kontextmind/kxm/pull/410) owns those files. Playwright stays on Obscura. [Playwright e2e](https://github.com/kontextmind/kxm/blob/main/.github/workflows/e2e.yml) already runs `npm run e2e` on `ubuntu-latest`.
+
+## What this pass fixed
+
+Each fix is a small pull request with squash auto-merge. None of them needs a secret, a repository setting, DNS, or a runner change.
+
+| Pull request | Fix |
+|---|---|
+| [#411](https://github.com/kontextmind/kxm/pull/411) | Whole-word workflow keywords in `kxm suggest` |
+| [#412](https://github.com/kontextmind/kxm/pull/412) | `kxm vision assert --route` follows the admitted Pi model |
+| [#413](https://github.com/kontextmind/kxm/pull/413) | Next step when Git or the hub is missing |
+| [#414](https://github.com/kontextmind/kxm/pull/414) | A rate-limit abort still walks the fallback chain |
+
+`kxm suggest` used to treat a keyword as a substring. "guide" and "build" took the feature workflow because they contain `ui`, "author" took vulnerability remediation because it contains `auth`, and "change" took bug-fix because it contains `hang`. Hyphenated keywords such as `circuit-breaker` still match as one token. A prompt with no keyword still selects `feature-implementation` at score 0.
+
+`kxm vision assert` accepted `--route` and then ignored it. The flag now selects that Pi model after admission. An unknown route names `kxm routes admit`. A native-vendor id is refused before `pi` starts. The CLI reference documents the command. The built-in default route is unchanged. See decision 2.
+
+`kxm init` outside any Git worktree now says to run `git init` and then `kxm init` again. A directory that is not the worktree root still says to run from that root. `kxm hub view` says to start the hub when nothing is listening on a loopback URL, and names the tunnel and `kxm hub bind` for any other URL. An auth proxy or redirect keeps its existing probe note.
+
+A provider HTTP 429 whose body says the request was aborted used to classify as `cancelled`, which does not walk. It now stays `rate_limit` and walks. `AbortError`, a process abort, and a user cancel stay `cancelled`. `tool_policy` is its own class. Both non-walkable classes still stop the chain.
+
+## What was checked and left
+
+Product TypeScript and Python sources have no `TODO` or `FIXME` markers outside generated bundles and narrative plan text. The CLI reference already covers the registered commands. `kxm vision assert` was the missing heading, and pull request #412 adds it.
+
+Phase pages under `docs/roadmap/phases/` are symlinks to `plans/kxm-roadmap/phases/`. Plan links such as `../../plan-lane-cli.md` resolve from the real file. A scan that does not follow the symlink reports nine missing targets under `docs/roadmap/phases/`. The generator was not changed.
+
+`.kxm/knowledge` has ten pages, last indexed 2026-10-17. It has no first-run page, and [CI conventions](../../.kxm/knowledge/patterns/ci.md) does not describe the runner queue below. Those notes should wait until the runner decision lands, so the wiki does not record a queue that the operator is about to move.
+
+## Decisions for the operator
+
+Ranked by how often they block a pull request or a first run. Each one needs a setting, a host, a secret, or an admission the code must not guess.
+
+### 1. Where pull-request Linux jobs run
+
+Pull-request jobs that select the ARC scale set `kontextmind-doks` are Classify changes, Docs lint, both Linux engine shards, the Linux unit lanes (`serial`, `light-1`, `light-2`), Python MG1, Plugin validation, and `required`. Windows unit lanes already use `windows-latest`, and only when the classifier marks the change platform-sensitive. The Validate matrix does not run on a pull request. On `main` its Linux cells use `kontextmind-doks` with a three-minute timeout, and its Windows cells use `windows-latest` with a fifteen-minute timeout.
+
+[CI and release](../contributing/ci-and-release.md) records the capacity policy: one warm runner, a burst to four, three CPUs each. `test/core/ci-contract.test.ts` refuses `ubuntu-latest` inside `ci.yml`, `release.yml`, `smoke.yml`, and `nightly.yml`. The same page says the Python lane stays on `kontextmind-doks` because that scale set has no container-engine socket. `scripts/ci-postgres-17.sh` installs a pinned PostgreSQL 17.11.0 linux/x86_64 archive and maps ICU 74 to the `libicu74` apt package.
+
+Observed on 2026-10-21:
+
+- Workflow [39513962307](https://github.com/kontextmind/kxm/actions/runs/39513962307) (pull request #410, platform-sensitive) was created at 2026-10-20T23:16:53Z. Docs lint started at 2026-10-21T00:02:27Z, about 46 minutes later. Windows lanes started at 00:03:51Z, within seconds of Classify. Linux lanes then ran mostly one at a time through about 00:20Z.
+- Workflow [39510255392](https://github.com/kontextmind/kxm/actions/runs/39510255392) (planner fallback, code pull request) was created at 2026-10-20T22:44:14Z and completed at 2026-10-20T23:08:16Z, about 24 minutes, while the scale set was less busy.
+
+Classify, Docs lint, the Node unit lanes, Plugin validation, and `required` do not need the cluster. Moving those jobs to `ubuntu-latest` would drop the queue and would also edit the contract test, spend GitHub-hosted minutes, and reverse the pinned-runner rule. Python can stay on the scale set, or move to a GitHub-hosted service container, which is a different script than the pinned archive. A newer image that no longer ships `libicu74` fails that archive until the pin moves. Linux Validate on `main` has a three-minute timeout that is tight for a cold `npm ci` on a GitHub-hosted runner. Do not relabel `km-gh-rn01`. That bypasses ARC and serializes the queue.
+
+### 2. The built-in vision route
+
+`kxm vision assert` still defaults to `zai-coding-cn/glm-5.3-flash` and, for that id only, still runs `pi --provider zai-coding-cn --model glm-5.3-flash`. `.kxm/routes.yaml` removed `zai-coding-cn/*` on 2026-09-27 because that provider is not allowlisted. The admitted replacement in this checkout is `openrouter/z-ai/glm-5.3-flash`. A vision call here with no `--route` still fail-closes, and pull request #412 names `kxm routes admit` in that message. `kxm init` does not admit a vision route.
+
+Changing the default needs a vision accuracy witness on the admitted id. This pass kept the verified default argv.
+
+### 3. The starter writer model
+
+`kxm init` still admits `xai/grok-4.6`, writes `.kxm/models/grok-grok-4-6.yaml`, and puts that route on the writer roster. This repository admits `xai/grok-4.7`. `modes.ts`, `subagent-control.ts`, and the Pi producer default still name grok-4.6. Glossary and catalog examples that show grok-4.6 are selector shapes. Replacing the starter is an admission decision, with the tests and docs that pin 4.6 updated in the same change.
+
+### 4. Confirm or reverse the defaults already in Tracking
+
+These are already implemented. They wait on a yes, a change, or a decline. A decline is its own revert. The queue is [Still open](../../plans/implementation-plan.md#tracking-working-tree-not-a-release).
+
+- Q-B, Q-C, and Q-E through Q-K on pull request #298: promotion policy, schema identity, evidence on repro and implementer roles, task ranking, pass semantics, coded-repeat candidacy, direct readers, log sizes, and dispatch context. Each shipped with the recommended default and is not a Decided entry.
+- D-1: keep the nine KontextMind knowledge-plane skills, rescoped so they trigger when the user names KontextMind, or delete them. The current tree keeps them.
+- D-2: leave `plugin.json` and `marketplace.json` at 0.7.1, so `claude plugin update` does not refresh an existing install, or bump the plugin version.
+- A0: the live Claude Code witness for `kxm_hook_tool_failure` in an isolated `CLAUDE_CONFIG_DIR`. The tool stays unpublished until that witness passes.
+
+### 5. Witnesses that need a host or a secret
+
+Still open already names the owners. This pass did not schedule them.
+
+- S5 interactive login, logout, and refresh on the deployed edge, plus the deployed restore witness that is still tied to that window.
+- P0 cross-box `kxm peer`: box B binds hub A over an operator-owned forward and completes send, await, reply, checkpoint, and signal.
+- Backup restore does not remap absolute paths stored under `$S`.
+- The hub context pool reads `.kxm/memory` and skills from the hub checkout and relabels them as the caller's project.
+- Runtime runs have no journal. `kxm workflow record` looks the id up among hub webhook runs, so a `kxm run` id returns `workflow_not_found`. A journal needs a new store, and the S0–S5 queue forbids that schema change while S5 is open.
+- Routing and cost questions in the same Still open list: the Google route still wired as `agy` while Decided says `antigravity`, two Pi allowlists, `limits.maxModelCost` never tripping because no producer writes metered cost, and `qwen-token-plan/deepseek-v4.1-flash` admitted beside the native-vendor brake.
+
+## Related
+
+- [CI and release](../contributing/ci-and-release.md)
+- [Decisions](../contributing/decisions.md)
+- [KXM CLI reference](../reference/cli-reference.md)
+- [Troubleshoot KXM](../operations/troubleshooting.md)
+- [Project knowledge wiki](../../.kxm/knowledge/index.md)

package/docs/reference/cli-reference.md

@@ -13,7 +13,7 @@ Output shown under examples was captured from a source checkout, inside a throwa
 - [Task to command](#task-to-command)
 - Setup: [`init`](#kxm-init), [`config`](#kxm-config), [`completion`](#kxm-completion), [`trust`](#kxm-trust)
 - Hub and sessions: [`hub`](#kxm-hub-view), [`session`](#kxm-session), [`dash`](#kxm-dash), [`studio`](#kxm-studio)
-- Harnesses, models, and roles: [`harness`](#kxm-harness), [`plugin`](#kxm-plugin), [`auth`](#kxm-auth), [`update`](#kxm-update), [`models`](#kxm-models), [`routes`](#kxm-routes), [`role`](#kxm-role)
+- Harnesses, models, and roles: [`harness`](#kxm-harness), [`plugin`](#kxm-plugin), [`auth`](#kxm-auth), [`update`](#kxm-update), [`models`](#kxm-models), [`routes`](#kxm-routes), [`vision`](#kxm-vision), [`role`](#kxm-role)
 - Running work: [`lane`](#kxm-lane), [`land`](#kxm-land), [`assign`](#kxm-assign), [`run`](#kxm-run), [`runs`](#kxm-runs), [`docs`](#kxm-docs), [`runtime`](#kxm-runtime), [`agent`](#kxm-agent), [`workflow`](#kxm-workflow), [`gate`](#kxm-gate), [`peer`](#kxm-peer), [`task`](#kxm-task), [`goal`](#kxm-goal), [`suggest`](#kxm-suggest), [`explain`](#kxm-explain)
 - Context and learning: [`context`](#kxm-context), [`memory`](#kxm-memory), [`skills`](#kxm-skills), [`improve`](#kxm-improve), [`routing`](#kxm-routing), [`prices`](#kxm-prices)
 - Operations: [`backup`](#kxm-backup), [`restore`](#kxm-restore), [`tenant`](#kxm-tenant), [`ssh`](#kxm-ssh), [`help`](#kxm-help)
@@ -103,7 +103,7 @@ kxm -V
 - Plan with `planned`: `backup`, `restore`, `config set`, `role add|remove|modify|resume`, `workflow add|remove|modify`, `goal create`, `task create|run|sync`, `memory note|sync`, `skills evaluate|promote|reject`, `context promote`, `context wiki-compile --out`, `auth token`, `session token`, `session brief`, and `ssh run|file|close`. Each prints its normal result plus `dryRun: true` and `planned`, a list of `{action, target}` entries whose `action` is `write`, `delete`, `move`, `request`, or `ssh`. Text mode prints `dry run: <summary>` and one indented `would <action> <target>` line per entry (`session brief` appends `dry run: would write <file>` lines to the brief instead).
 - Plan in their own shape (described in each section): `init`, `run`, `runs drive|cancel`, `docs build|serve`, `runtime start|stop|sync-retry`, `hub start|stop|bind|unbind`, `session start|stop`, `agent worker`, `dash`, `studio serve`, `models inventory-refresh`, `routes admit|disable`, `update`, `completion install`, `workflow start|signal|export|checkpoint|record|wait`, every `peer` subcommand, `gate degrade|signal`, `skills create`, `improve report`, and `config edit`. `config edit --dry-run` prints one plain frame and writes nothing. `gate github watch --dry-run` still polls GitHub but does not post the signal.
 - Read-only commands run as usual, without leaving a trace: a local SQLite store is opened without creating `-wal` or `-shm` files, and `runs status|list|receipt` only attach to a running Runtime supervisor. With no supervisor running they exit 2 with `dry_run_unsupported` instead of starting one. `context wiki-compile --dry-run` still asks the hub to compile, which is a read.
-- Refused: `kxm models` (the interactive screen) and `kxm prices acknowledge` exit 2 with `dry_run_unsupported`. The CLI keeps one list of the commands that answer `--dry-run` and refuses every other command the same way before it runs, so a command added without dry-run support fails closed.
+- Refused: `kxm models` (the interactive screen), `kxm vision assert`, and `kxm prices acknowledge` exit 2 with `dry_run_unsupported`. The CLI keeps one list of the commands that answer `--dry-run` and refuses every other command the same way before it runs, so a command added without dry-run support fails closed.
 
 ```bash
 kxm config set user.theme light --dry-run
@@ -908,6 +908,38 @@ kxm studio serve --port 5000
 
 Not run: starts a long-lived server.
 
+## `kxm vision`
+
+Judge one captured screenshot through an admitted Pi route. The gate sends a bounded yes/no prompt and accepts only `{"verdict": true}` or `{"verdict": false}`. Any other answer fails closed. It does not replace a Playwright assertion.
+
+### `kxm vision assert`
+
+```text
+kxm vision assert --image <path> --question <text> [--route <id>] [--timeout-ms <n>] [--expect <true|false>]
+```
+
+| Option | Argument | Default | Description |
+|---|---|---|---|
+| `--image` | `<path>` | required | Screenshot file. A missing file fails closed with `image unreadable` |
+| `--question` | `<text>` | required | Yes/no assertion, trimmed to 500 characters inside the prompt |
+| `--route` | `<id>` | `zai-coding-cn/glm-5.3-flash` | Admitted route id. The default keeps the verified Pi command `--provider zai-coding-cn --model glm-5.3-flash`. Any other id is `pi --model <id>` after the native-vendor brake |
+| `--timeout-ms` | `<n>` | `90000` | Integer from 5000 through 300000 |
+| `--expect` | `true` or `false` | none | Exit 0 only when the verdict equals this value |
+
+- Global options apply, except `--dry-run`, which exits 2 with `dry_run_unsupported` because the command calls Pi.
+- The route must be listed under `admitted` in `.kxm/routes.yaml`. Otherwise the command exits 1 and the `divergence` names the id and `kxm routes admit --model <id>`.
+- This repository does not admit the default `zai-coding-cn/glm-5.3-flash` (`zai-coding-cn` is not an allowlisted harness). Pass `--route openrouter/z-ai/glm-5.3-flash`, which is admitted here, or admit the route you pass.
+- A native-vendor id such as `xai/grok-4.7` or `anthropic/fable` is refused before Pi starts, even when that id is admitted. The `divergence` is the Pi brake message.
+- Exit 0 when the verdict resolves and, if `--expect` is set, matches it. Exit 1 for a fail-closed divergence. Exit 2 when `--image` or `--question` is missing, `--expect` is not `true` or `false`, or `--timeout-ms` is not an integer.
+- JSON keys: `ok`, `command` (`vision assert`), `verdict` (`true`, `false`, or `null`), `route`, `raw`, `divergence` when the gate fails closed, and `expect` when `--expect` is set.
+- Text mode prints `verdict true` or `verdict false`, or `vision gate fail-closed: <divergence>`.
+
+Not run. The command calls Pi.
+
+```bash
+kxm vision assert --image .kxm/artifacts/browser/shot.png --question "Does the page show the error banner?" --route openrouter/z-ai/glm-5.3-flash --expect false
+```
+
 ## `kxm harness`
 
 ### `kxm harness list`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.193",
+  "version": "0.7.195",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",

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.193",
+  "version": "0.7.195",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",

package/plugins/kxm/dist/cli.js

@@ -28903,12 +28903,22 @@ function parseVisionVerdict(raw) {
   const match = /"verdict"\s*:\s*(true|false)/i.exec(raw);
   return match ? match[1] === "true" : null;
 }
-function defaultTransport(prompt, timeoutMs) {
-  return execFileSync(
-    "pi",
-    ["--provider", "zai-coding-cn", "--model", "glm-5.3-flash", "-p", "--no-session", prompt],
-    { encoding: "utf8", timeout: timeoutMs, windowsHide: true }
-  );
+function visionPiArgs(route) {
+  if (route === VISION_GATE_DEFAULT_ROUTE) {
+    return { ok: true, args: ["--provider", "zai-coding-cn", "--model", "glm-5.3-flash", "-p", "--no-session"] };
+  }
+  const validation = validateHarnessModelPair("pi", route);
+  if (!validation.valid) {
+    return { ok: false, divergence: validation.message ?? "route_not_pi" };
+  }
+  const trimmed = route.trim();
+  if (!trimmed.includes("/")) {
+    return { ok: false, divergence: `route_not_pi: ${trimmed} is not a provider-qualified Pi model id` };
+  }
+  return { ok: true, args: ["--model", trimmed, "-p", "--no-session"] };
+}
+function defaultTransport(args, timeoutMs) {
+  return execFileSync("pi", [...args], { encoding: "utf8", timeout: timeoutMs, windowsHide: true });
 }
 async function runVisionGate(options) {
   const projectRoot = options.projectRoot ?? process.cwd();
@@ -28922,12 +28932,17 @@ async function runVisionGate(options) {
     return { ...base, divergence: "image unreadable" };
   }
   if (!isRouteAdmitted(projectRoot, route)) {
-    return { ...base, divergence: "route_not_admitted" };
+    return {
+      ...base,
+      divergence: `route_not_admitted: ${route} is not admitted; run kxm routes admit --model ${route} or pass --route <admitted-id>`
+    };
   }
+  const piArgs = visionPiArgs(route);
+  if (!piArgs.ok) return { ...base, divergence: piArgs.divergence };
   const prompt = visionGatePrompt(options.question, options.imagePath);
   let raw;
   try {
-    raw = options.transport ? await options.transport(prompt) : defaultTransport(prompt, timeoutMs);
+    raw = options.transport ? await options.transport(prompt) : defaultTransport([...piArgs.args, prompt], timeoutMs);
   } catch (error) {
     return { ...base, divergence: `transport failed: ${String(error?.message ?? error).slice(0, 200)}` };
   }
@@ -28942,6 +28957,7 @@ var VISION_GATE_DEFAULT_ROUTE, QUESTION_MAX_CHARS, RAW_MAX_CHARS;
 var init_vision_gate = __esm({
   "plugins/kxm/src/vision-gate.ts"() {
     "use strict";
+    init_harness();
     init_routes();
     VISION_GATE_DEFAULT_ROUTE = "zai-coding-cn/glm-5.3-flash";
     QUESTION_MAX_CHARS = 500;

package/plugins/kxm/dist/mcp-server.js

@@ -25462,7 +25462,7 @@ function sessionTokenFixHint(policy) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.193";
+var VERSION = "0.7.195";
 var CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.193",
+  "version": "0.7.195",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/skills/kxm-browser-verify/SKILL.md

@@ -105,6 +105,6 @@ kxm vision assert --image .kxm/artifacts/browser/shot.png \
   --expect false
 ```
 
-- Exit 0 only when the verdict resolves and matches `--expect`; fail-closed divergences (`route_not_admitted`, `image unreadable`, `verdict unreadable`) exit 1.
-- The route must be admitted in `.kxm/routes.yaml` (default: `zai-coding-cn/glm-5.3-flash`, the 12/12-accuracy verified vision route).
+- Exit 0 only when the verdict resolves and matches `--expect`; fail-closed divergences (`route_not_admitted`, `image unreadable`, `verdict unreadable`, or the Pi native-vendor brake) exit 1.
+- The route must be admitted in `.kxm/routes.yaml`. The built-in default is `zai-coding-cn/glm-5.3-flash` (the verified Pi invocation `--provider zai-coding-cn --model glm-5.3-flash`). This checkout does not admit that id. Pass `--route openrouter/z-ai/glm-5.3-flash`, which is admitted here. `--route` selects the Pi model; a native-vendor id is refused before Pi starts.
 - The gate is a supplement to deterministic Playwright assertions, never a replacement.

package/plugins/kxm/src/mcp-server.ts

@@ -11,7 +11,7 @@ import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 import { sessionTokenFixHint } from "./session-token-hint.ts";
 
-const VERSION = "0.7.193";
+const VERSION = "0.7.195";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();

package/plugins/kxm/src/vision-gate.ts

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, statSync } from "node:fs";
+import { validateHarnessModelPair } from "./harness.ts";
 import { isRouteAdmitted } from "./routes.ts";
 
 /** Deterministic vision gate: judge a UI screenshot through an admitted
@@ -52,12 +53,27 @@ export function parseVisionVerdict(raw: string): boolean | null {
   return match ? match[1] === "true" : null;
 }
 
-function defaultTransport(prompt: string, timeoutMs: number): string {
-  return execFileSync(
-    "pi",
-    ["--provider", "zai-coding-cn", "--model", "glm-5.3-flash", "-p", "--no-session", prompt],
-    { encoding: "utf8", timeout: timeoutMs, windowsHide: true },
-  );
+/** Pi argv for an admitted vision route, without the prompt.
+ * The verified default keeps `--provider zai-coding-cn --model glm-5.3-flash`.
+ * Every other id is `pi --model <id>` after the native-vendor brake, so
+ * `--route` selects the model instead of only the admission check. */
+export function visionPiArgs(route: string): { ok: true; args: readonly string[] } | { ok: false; divergence: string } {
+  if (route === VISION_GATE_DEFAULT_ROUTE) {
+    return { ok: true, args: ["--provider", "zai-coding-cn", "--model", "glm-5.3-flash", "-p", "--no-session"] };
+  }
+  const validation = validateHarnessModelPair("pi", route);
+  if (!validation.valid) {
+    return { ok: false, divergence: validation.message ?? "route_not_pi" };
+  }
+  const trimmed = route.trim();
+  if (!trimmed.includes("/")) {
+    return { ok: false, divergence: `route_not_pi: ${trimmed} is not a provider-qualified Pi model id` };
+  }
+  return { ok: true, args: ["--model", trimmed, "-p", "--no-session"] };
+}
+
+function defaultTransport(args: readonly string[], timeoutMs: number): string {
+  return execFileSync("pi", [...args], { encoding: "utf8", timeout: timeoutMs, windowsHide: true });
 }
 
 export async function runVisionGate(options: VisionGateOptions): Promise<VisionGateResult> {
@@ -73,15 +89,20 @@ export async function runVisionGate(options: VisionGateOptions): Promise<VisionG
     return { ...base, divergence: "image unreadable" };
   }
   if (!isRouteAdmitted(projectRoot, route)) {
-    return { ...base, divergence: "route_not_admitted" };
+    return {
+      ...base,
+      divergence: `route_not_admitted: ${route} is not admitted; run kxm routes admit --model ${route} or pass --route <admitted-id>`,
+    };
   }
+  const piArgs = visionPiArgs(route);
+  if (!piArgs.ok) return { ...base, divergence: piArgs.divergence };
   const prompt = visionGatePrompt(options.question, options.imagePath);
 
   let raw: string;
   try {
     raw = options.transport
       ? await options.transport(prompt)
-      : defaultTransport(prompt, timeoutMs);
+      : defaultTransport([...piArgs.args, prompt], timeoutMs);
   } catch (error) {
     return { ...base, divergence: `transport failed: ${String((error as Error)?.message ?? error).slice(0, 200)}` };
   }