@kontextmind/kxm 0.7.194 → 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.194",
+      "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/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.194",
+  "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.194",
+  "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.194";
+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.194",
+  "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.194";
+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)}` };
   }