@kontextmind/kxm 0.7.194 → 0.7.196

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.194",
+      "version": "0.7.196",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/CHANGELOG.md

@@ -714,6 +714,20 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Fixed
 
+- **A first run says what to do next when Git or the hub is missing.**
+  `kxm init` outside a Git worktree still exits 1 with `git_root_required` and
+  now says to run `git init`, then `kxm init` again. `kxm hub view` adds
+  `hint` when both probes are unreachable or time out: on loopback, start a
+  hub with `kxm hub start`; on a remote URL, check the address and
+  `kxm hub bind`.
+
+- **`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 +745,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/operations/troubleshooting.md

@@ -19,6 +19,7 @@ Work from the smallest boundary outward:
 | Symptom | Cause | Fix |
 |---|---|---|
 | `kxm: command not found` | Only the Pi package or the Claude Code plugin was installed; neither installs the CLI | `npm install --global --omit=peer @kontextmind/kxm`; see [Install KXM](../start/install.md) |
+| `git_root_required` from `kxm init` | The current directory is not inside a Git worktree | Run `git init` in that directory, then `kxm init` again. If Git is present, run `kxm init` from the worktree root |
 | `kxm` works in one shell but not in another | npm's global bin directory is not on that shell's `PATH` | Run `kxm completion install` (bash and zsh also get a `PATH` entry), then open a new shell |
 | Tab completion does nothing | Completion is not installed for this shell | `kxm completion install --shell bash`, `zsh` or `fish`; it is idempotent, and `--dry-run` previews it |
 | Plugin tools fail on start | Node.js is older than 22.19 on the 22.x line, or older than 24 | Install a supported Node.js on the `PATH` the harness uses |
@@ -42,6 +43,10 @@ If it still reports `not_detected`, confirm that `%AppData%\Roaming\npm` is on t
 
 ## Hub and authentication
 
+### Nothing is listening
+
+`kxm hub view` prints `hub health=false ready=false` and, for a loopback URL, `Nothing is listening on this loopback URL. Start a local hub with kxm hub start.` A remote URL names `kxm hub bind` instead. An HTML login page or a redirect is a different failure: the status line says `auth proxy`, and the fix is the proxy or the hub URL, not `kxm hub start`.
+
 ### The hub refuses to start
 
 | Message | Fix |

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
@@ -511,7 +511,7 @@ Calls `GET /health` and `GET /ready` on the target hub and reports whether the U
 No command-specific options.
 
 - Needs a hub to succeed. Reads only.
-- JSON keys: `target` (`url`, `scope`, and `source: "env"` when `KXM_SERVER_URL` overrides a binding), `identity` (`mode`, `modeSource`, `url`, `urlSource`, `project`, `projectSource`, `keySource`), `health`, `ready`. An unreachable hub reports `{"error":"hub_unreachable"}` for both probes. An auth proxy or redirect reports `{"error":"auth_proxy"}`.
+- JSON keys: `target` (`url`, `scope`, and `source: "env"` when `KXM_SERVER_URL` overrides a binding), `identity` (`mode`, `modeSource`, `url`, `urlSource`, `project`, `projectSource`, `keySource`), `health`, `ready`, and `hint` when both probes are unreachable or time out. An unreachable hub reports `{"error":"hub_unreachable"}` for both probes. On a loopback URL the hint is `Nothing is listening on this loopback URL. Start a local hub with kxm hub start.` A remote URL names `kxm hub bind`. An auth proxy or redirect reports `{"error":"auth_proxy"}` and has no hint.
 - Exit 0 when both probes succeed, 1 otherwise. A cloud mode with no resolvable key exits 2 with `cloud_token_missing`.
 
 ```bash
@@ -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.194",
+  "version": "0.7.196",
   "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.194",
+  "version": "0.7.196",
   "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;
@@ -30877,7 +30893,7 @@ function initializeKxmProjectAtGitRoot(start, gitRoot, options, mutationLock) {
     };
   }
   if (plan.projectRoot !== gitRoot) {
-    throw new KxmConfigError([initIssue("git_root_required", ".", "kxm init must run inside the authoritative Git worktree")]);
+    throw new KxmConfigError([initIssue("git_root_required", ".", "kxm init must run from the Git worktree root")]);
   }
   const projectId = generatedProjectId(options.projectId);
   const projectName = normalizedProjectName(gitRoot, options.projectName);
@@ -30902,7 +30918,7 @@ function initializeKxmProject(start = process.cwd(), options = {}) {
   assertNoRegisteredGates(options);
   const gitRoot = discoverGitRoot(start);
   if (!gitRoot) {
-    throw new KxmConfigError([initIssue("git_root_required", ".", "kxm init must run inside the authoritative Git worktree")]);
+    throw new KxmConfigError([initIssue("git_root_required", ".", "kxm init must run inside a Git worktree. Run git init in this directory, then run kxm init again.")]);
   }
   if (options.projectId !== void 0) generatedProjectId(options.projectId);
   if (options.projectName !== void 0) normalizedProjectName(gitRoot, options.projectName);
@@ -53981,6 +53997,8 @@ async function cmdStatus(runtime) {
   const notHub = !proxyKind && (health.kind === "not_hub" || ready.kind === "not_hub");
   const probeNote = proxyKind === "redirect" ? " \xB7 auth proxy or redirect" : proxyKind === "auth_proxy" ? " \xB7 auth proxy (HTML login page)" : notHub ? " \xB7 not a kxm hub" : "";
   const effectiveScope = connection.scope;
+  const hubDown = (health.kind === "unreachable" || health.kind === "timeout") && (ready.kind === "unreachable" || ready.kind === "timeout");
+  const hint = !hubDown ? void 0 : effectiveScope === "loopback" ? "Nothing is listening on this loopback URL. Start a local hub with kxm hub start." : "Nothing answered this hub URL. Check the address, the tunnel, and kxm hub bind.";
   const overridden = connection.urlSource === "env";
   const identity = {
     mode: connection.mode,
@@ -53997,13 +54015,15 @@ async function cmdStatus(runtime) {
     target: { url: runtime.serverUrl, scope: effectiveScope, ...overridden ? { source: "env" } : {} },
     identity,
     health: health.body,
-    ready: ready.body
+    ready: ready.body,
+    ...hint ? { hint } : {}
   };
   print(
     runtime.io,
     runtime.json,
     payload,
-    `hub health=${health.ok} ready=${ready.ok} \xB7 ${effectiveScope} hub${overridden ? " (KXM_SERVER_URL)" : ""} \xB7 mode=${identity.mode} project=${identity.project} (${connection.sourceLabel}) key=${identity.keySource}${probeNote}`
+    `hub health=${health.ok} ready=${ready.ok} \xB7 ${effectiveScope} hub${overridden ? " (KXM_SERVER_URL)" : ""} \xB7 mode=${identity.mode} project=${identity.project} (${connection.sourceLabel}) key=${identity.keySource}${probeNote}${hint ? `
+${hint}` : ""}`
   );
   return payload.ok ? 0 : 1;
 }

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

@@ -25462,7 +25462,7 @@ function sessionTokenFixHint(policy) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.194";
+var VERSION = "0.7.196";
 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.194",
+  "version": "0.7.196",
   "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/cli/hub.ts

@@ -202,6 +202,11 @@ export async function cmdStatus(runtime: Runtime): Promise<number> {
   // A cloud mode is remote when the contacted URL is that endpoint, including a
   // loopback SSH forward.
   const effectiveScope = connection.scope;
+  const hubDown = (health.kind === "unreachable" || health.kind === "timeout")
+    && (ready.kind === "unreachable" || ready.kind === "timeout");
+  const hint = !hubDown ? undefined : effectiveScope === "loopback"
+    ? "Nothing is listening on this loopback URL. Start a local hub with kxm hub start."
+    : "Nothing answered this hub URL. Check the address, the tunnel, and kxm hub bind.";
   const overridden = connection.urlSource === "env";
   const identity = {
     mode: connection.mode,
@@ -219,9 +224,10 @@ export async function cmdStatus(runtime: Runtime): Promise<number> {
     identity,
     health: health.body,
     ready: ready.body,
+    ...(hint ? { hint } : {}),
   };
   print(runtime.io, runtime.json, payload,
-    `hub health=${health.ok} ready=${ready.ok} · ${effectiveScope} hub${overridden ? " (KXM_SERVER_URL)" : ""} · mode=${identity.mode} project=${identity.project} (${connection.sourceLabel}) key=${identity.keySource}${probeNote}`);
+    `hub health=${health.ok} ready=${ready.ok} · ${effectiveScope} hub${overridden ? " (KXM_SERVER_URL)" : ""} · mode=${identity.mode} project=${identity.project} (${connection.sourceLabel}) key=${identity.keySource}${probeNote}${hint ? `\n${hint}` : ""}`);
   return payload.ok ? 0 : 1;
 }
 

package/plugins/kxm/src/init.ts

@@ -390,7 +390,7 @@ function initializeKxmProjectAtGitRoot(
   }
 
   if (plan.projectRoot !== gitRoot) {
-    throw new KxmConfigError([initIssue("git_root_required", ".", "kxm init must run inside the authoritative Git worktree")]);
+    throw new KxmConfigError([initIssue("git_root_required", ".", "kxm init must run from the Git worktree root")]);
   }
   const projectId = generatedProjectId(options.projectId);
   const projectName = normalizedProjectName(gitRoot, options.projectName);
@@ -416,7 +416,7 @@ export function initializeKxmProject(start = process.cwd(), options: KxmInitOpti
   assertNoRegisteredGates(options);
   const gitRoot = discoverGitRoot(start);
   if (!gitRoot) {
-    throw new KxmConfigError([initIssue("git_root_required", ".", "kxm init must run inside the authoritative Git worktree")]);
+    throw new KxmConfigError([initIssue("git_root_required", ".", "kxm init must run inside a Git worktree. Run git init in this directory, then run kxm init again.")]);
   }
   if (options.projectId !== undefined) generatedProjectId(options.projectId);
   if (options.projectName !== undefined) normalizedProjectName(gitRoot, options.projectName);

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.194";
+const VERSION = "0.7.196";
 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)}` };
   }