@kontextmind/kxm 0.7.163 → 0.7.165

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

package/CHANGELOG.md

@@ -6,6 +6,15 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Added
 
+- **`kxm hub bind --cloud` attaches a client to a remote hub reached through a loopback forward.**
+  The binding records `--token-env` and/or `--token-command` and never the token.
+  Later commands, including the environment for a Pi worker, use that source and
+  do not fall back to this machine's hub-env token. Peer commands and
+  `kxm tenant status` resolve one project id: flag or `KXM_PROJECT`, then
+  `.kxm/project.yaml`, then `package.json`, then the directory name. The
+  SSH-forward recipe is in
+  [Operate a KXM hub](docs/operations.md#cross-box-peer-attach).
+
 - **A live agent step uses a configurable one-shot timeout, and a cancelling run recovers when its child has already exited.**
   The bound is the step `timeoutMs`, or the project `limits.agentStepTimeoutMs`
   when the step omits it (minimum 60 seconds, default one hour). A wider step
@@ -156,6 +165,19 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Changed
 
+- **The checked-in price catalog and model inventory match the live OpenRouter and Nous feeds.**
+  `.kxm/prices.yaml` is dated 2026-09-28. It adds `xai/grok-4.7` (alias
+  `x-ai/grok-4.7`) at $1.60 input and $4.80 output per 1M tokens, with cache
+  read $0.40. `openrouter/z-ai/glm-5.3-flash` moves from $0.09 / $0.30 to
+  $0.15 / $0.50 (cache read $0.03); the anchored `zai-coding-cn/glm-5.3-flash`
+  row moves with it. `qwen-token-plan/deepseek-v4.1-flash` (alias
+  `deepseek/deepseek-v4.1-flash`) moves from $0.15 / $0.60 to $0.014 / $0.40
+  (cache read $0.004) because the routing docs still name that selector.
+  `xai/grok-4.6` stays: its base rate still matches the live catalog, and code
+  and tests still name it. `.kxm/models/inventory.yaml` was refreshed with
+  `kxm models inventory-refresh`. Pi, Grok, and agy were not installed for that
+  fetch, so models that exist only in those CLIs remain the 2026-09-16 rows.
+
 - **Windows pull-request unit lanes finish inside the job limit.** The light
   lane on `windows-latest` was cancelled at 20 minutes on #361, #362, and
   #363 after it stopped reporting tests. `package-install.test.ts` (171s on

package/README.md

@@ -105,6 +105,8 @@ You need Node.js 22.19 or newer on the 22.x line, or Node.js 24 or newer, plus G
    kxm hub view
    ```
 
+   A hub on another machine, reached through an SSH forward to loopback, uses `kxm hub bind --cloud` so this machine's hub-env token is not sent. The recipe is in [Operate a KXM hub](docs/operations.md#cross-box-peer-attach).
+
    Expected output:
 
    ```text

package/docs/README.md

@@ -96,6 +96,7 @@ KXM connects coding agents through a durable, authenticated [hub](glossary.md#hu
 
 | Page | For | What you get |
 |---|---|---|
+| [Operate a KXM hub](operations.md) | Hub operators | Index of the operations guides, and cross-box attach over an SSH forward |
 | [Deploy KXM](operations/deploy.md) | Hub operators | Deployment classes, supervision, and hosted per-tenant hubs behind a proxy |
 | [Monitor KXM](operations/monitoring.md) | Hub operators | `kxm dash`, health and readiness, metrics, logs and alerts |
 | [Back up and restore KXM](operations/backup-and-restore.md) | Hub operators | `kxm backup` and `kxm restore`, the state roots, and a stopped-hub recipe |

package/docs/architecture/inventory.md

@@ -32,9 +32,10 @@ On macOS the user state root is `Library/Application Support/KXM` under the
 home directory (`kxmUserStateRoot` in `plugins/kxm/src/bindings.ts`). Windows
 uses `AppData/Local/KXM`. Other platforms use `$XDG_STATE_HOME/kxm` or
 `.local/state/kxm`. `KXM_STATE_HOME` overrides that root when it is absolute.
-The tracker mentions `docs/operations.md` for the six backup roots. That file
-is not in this checkout. The six roots are described in
-[Backup and restore](../operations/backup-and-restore.md).
+The tracker mentions `docs/operations.md` for the six backup roots. That page
+indexes the operations guides and links the six roots to
+[Backup and restore](../operations/backup-and-restore.md). It also holds
+[Cross-box peer attach](../operations.md#cross-box-peer-attach).
 
 ## Related
 

package/docs/contributing/harness-routing-internals.md

@@ -1,13 +1,13 @@
 # Harness routing internals
 
-This page records how the KXM repository applies [harness routing](../reference/harness-routing.md) to its own work: the routes this checkout admits, its writer roster, its price catalog, and the developer roster policy that `just assign` and the dev helper enforce. It is maintainer material. The snapshots were captured on 2026-09-23 on one operator machine, from a source checkout where `node scripts/kxm.mjs` is the same program as `kxm`; they change whenever an admission changes.
+This page records how the KXM repository applies [harness routing](../reference/harness-routing.md) to its own work: the routes this checkout admits, its writer roster, its price catalog, and the developer roster policy that `just assign` and the dev helper enforce. It is maintainer material. The route and roster transcripts below were regenerated on 2026-09-28 from this checkout, where `node scripts/kxm.mjs` is the same program as `kxm`. Readiness notes that name a capture machine are from 2026-09-23 and were not re-probed. The transcripts change whenever an admission changes.
 
 > [!IMPORTANT]
 > The files are the authority, not this page: `.kxm/routes.yaml`, `.kxm/roles/*.yaml`, `.kxm/models/*.yaml`, and `.kxm/prices.yaml`. Product routing decisions are recorded under Tracking → Decided in `plans/implementation-plan.md`.
 
 ## Current ids (2026-09-27)
 
-The command transcripts below are the 2026-09-23 capture. The files now use one id shape per kind. A route id is `<harness>-<model-slug>[-<provider>]`, with `.` written as `-`. An agent id equals its role. A workflow id is `default`, `land`, or `<role>-only`. An agent step id equals that role.
+The files use one id shape per kind. A route id is `<harness>-<model-slug>[-<provider>]`, with `.` written as `-`. An agent id equals its role. A workflow id is `default`, `land`, or `<role>-only`. An agent step id equals that role.
 
 This checkout's routes are `grok-grok-4-7`, `pi-qwen3-coder-plus-openrouter`, `agy-gemini-3-8-flash-high`, `agy-gemini-3-8-flash-medium`, `claude-fable`, `codex-gpt-5-6-sol`, `pi-qwen3-8-flash-openrouter`, and `pi-glm-5-3-flash-openrouter`. Agents are `planner`, `writer`, `reviewer-arch`, and `reviewer-cli`. `opus-claude` was removed because `opus` is not an admitted selector. `qwen-token-plan/*` and `zai-coding-cn/*` left the admitted list because those harnesses are not allowlisted; their `prices.yaml` rows stay. Old ids resolve as aliases. Every roster entry names an effort. `reviewer-arch` dispatches `claude-fable`. #343's architecture critic ran on opus because the justfile recipe review-arch hardcoded that model; the role file on that commit listed only `fable-claude`. The helper now refuses `opus`.
 
@@ -18,26 +18,22 @@ This checkout's routes are `grok-grok-4-7`, `pi-qwen3-coder-plus-openrouter`, `a
 ```text
 schema: kxm.role.v2
 id: writer
-description: ""
+purpose: writer
+permission: edit
+description: Primary implementation agent.
 skills: []
 roster:
-  - model: xai/grok-4.6
+  - route: grok-grok-4-7
     effort: medium
-    enabled: true
-  - model: openrouter/qwen/qwen3-coder-plus
+  - route: pi-qwen3-coder-plus-openrouter
     effort: medium
-    enabled: true
-  - model: zai-coding-cn/glm-5.3-flash
+  - route: agy-gemini-3-8-flash-high
     effort: medium
-    enabled: true
-  - model: qwen-token-plan/qwen3.8-flash
+  - route: agy-gemini-3-8-flash-medium
     effort: medium
-    enabled: true
-  - model: google/gemini-3.8-flash-high
-    enabled: true
 ```
 
-The implementer agent declares `harness: grok`, so of this roster only `xai/grok-4.6` can run under it; the Pi selectors need an agent without `harness:`.
+The writer role lists route ids, in order: `grok-grok-4-7`, then `pi-qwen3-coder-plus-openrouter`, then `agy-gemini-3-8-flash-high` and `agy-gemini-3-8-flash-medium`. `grok-grok-4-7` is harness `grok`, model `grok-4.7`, vendor `xai`. An agent file does not declare `harness:`.
 
 `node scripts/kxm.mjs routes list`:
 
@@ -49,12 +45,17 @@ admitted openai/gpt-5.6-sol
 admitted openrouter/qwen/qwen3-coder-plus
 admitted openrouter/qwen/qwen3.8-flash
 admitted openrouter/z-ai/glm-5.3-flash
-admitted qwen-token-plan/deepseek-v4.1-flash
-admitted qwen-token-plan/qwen3.8-flash
-admitted qwen-token-plan/qwen3.8-max
-admitted xai/grok-4.6
-admitted zai-coding-cn/glm-5.3
-admitted zai-coding-cn/glm-5.3-flash
+admitted xai/grok-4.7
+planner claude-fable
+planner pi-qwen3-8-flash-openrouter
+reviewer-arch claude-fable
+reviewer-arch pi-glm-5-3-flash-openrouter
+reviewer-cli codex-gpt-5-6-sol
+reviewer-cli pi-qwen3-8-flash-openrouter
+writer grok-grok-4-7
+writer pi-qwen3-coder-plus-openrouter
+writer agy-gemini-3-8-flash-high
+writer agy-gemini-3-8-flash-medium
 ```
 
 `routes admit --model openrouter/qwen/qwen3-coder-plus --dry-run` exits 2 with `select a model from the refreshed inventory` even though that selector is already admitted, because the inventory never carries `openrouter/…` selectors. Selectors like these are admitted by a Git-reviewed edit of `.kxm/routes.yaml`.
@@ -63,7 +64,7 @@ On the capture machine, `kxm harness list` showed `claude` detected but logged o
 
 ### Price catalog and inventory
 
-`.kxm/prices.yaml` is dated `2026-09-16`, so every current run records `providerMetadata.priceCatalogStale: true` and no list estimate. The list prices below come from `.kxm/models/inventory.yaml`, fetched `2026-09-16T14:54:53Z`, in USD per 1M tokens. The checkout has no routing records yet, so none of the examples has recorded latency; for latency, run a bounded side-by-side experiment and compare p50 and p95 in `kxm routing report`.
+`.kxm/prices.yaml` is dated `2026-09-28`. A run on that date can record a list estimate. Any other day records `providerMetadata.priceCatalogStale: true` and no list estimate. The list prices below come from `.kxm/models/inventory.yaml`. OpenRouter and Nous were fetched at `2026-09-28T14:02:09.052Z`. `pi`, `grok`, and `agy` were not installed for that refresh, so models that exist only in those CLIs are still the 2026-09-16 rows. Prices are USD per 1M tokens. The checkout has no routing records yet, so none of the examples has recorded latency; for latency, run a bounded side-by-side experiment and compare p50 and p95 in `kxm routing report`.
 
 ## The developer roster
 
@@ -108,15 +109,15 @@ The product brake, the dev helper and the roster policy now agree on the vendor
 
 These extend the generic examples on the reference page with this checkout's admissions, developer policy routes, readiness on the capture machine, and inventory prices.
 
-### Grok 4.6
+### Grok 4.7
 
 | | Native `grok` | Pi + OpenRouter |
 |---|---|---|
-| Selector | `xai/grok-4.6`: admitted, and first in the writer roster | `openrouter/x-ai/grok-4.6`: not admitted |
+| Selector | `xai/grok-4.7`: admitted, and first in the writer roster | `openrouter/x-ai/grok-4.7`: not admitted |
 | Developer roster | `grok-grok-4-7`, the writer route with `edit` | Refused: `native vendor cannot use Pi` |
-| Readiness | `grok` shows auth `yes` | `pi auth check --provider openrouter` returned `not_ready` |
-| Billing | grok.com subscription (OAuth) | $2.00 input, $6.00 output, $0.50 cached input |
-| Context | 500K (Pi's `xai` row; `grok models` does not print one) | 500,000 |
+| Readiness | `grok` showed auth `yes` on the 2026-09-23 capture machine | `pi auth check --provider openrouter` returned `not_ready` on that capture |
+| Billing | grok.com subscription (OAuth) | $1.60 input, $4.80 output, $0.40 cached input |
+| Context | 500,000 (`x-ai/grok-4.7` in the refreshed inventory) | 500,000 |
 
 Pi's own `xai` provider reported `ready` (OAuth) on the capture machine. When the grok quota runs out, the next writer in the lineup is `pi-qwen3-coder-plus-openrouter`, a different vendor.
 
@@ -147,7 +148,7 @@ In the inventory, `openai/gpt-5.6-sol` has sources `openrouter+nous` and carries
 
 | | Native `agy` | `antigravity` Pi provider | Pi + OpenRouter |
 |---|---|---|---|
-| Selector | `google/gemini-3.8-flash-high`: admitted, last in the writer roster | `antigravity/gemini-3.8-flash`: not admitted | `openrouter/google/gemini-3.8-flash`: not admitted |
+| Selector | `google/gemini-3.8-flash-high` and `google/gemini-3.8-flash-medium`: admitted, the last two writer routes | `antigravity/gemini-3.8-flash`: not admitted | `openrouter/google/gemini-3.8-flash`: not admitted |
 | Billing | Google subscription | Google subscription | $0.75 input, $3.75 output, $0.075 cached input |
 | Context | `agy` does not print it; the vendored catalog lists 1,048,576 | 1,048,576 | 1,048,576 |
 

package/docs/glossary.md

@@ -38,7 +38,7 @@ The service that authenticates [agents](#agent), stores [messages](#message) and
 
 ### Hub binding
 
-The record that `kxm hub bind <url>` writes to `hub-binding.json` in the [user state root](#user-state-root), naming the hub this machine uses. `kxm hub view` checks it, and the Runtime syncs to it. Binding a remote hub requires a credential.
+The record that `kxm hub bind <url>` writes to `hub-binding.json` in the [user state root](#user-state-root), naming the hub this machine uses. `kxm hub view` checks it, and the Runtime syncs to it. Binding a remote hub requires a credential. `kxm hub bind --cloud` marks a loopback forward as remote and records a token variable or command, never the token.
 
 ### KontextMind
 
@@ -104,11 +104,11 @@ Another [agent](#agent) in the same [project](#project). `kxm_list` and `kxm pee
 
 ### Project
 
-The authentication and discovery namespace on the hub. An agent names it with `KXM_PROJECT` (otherwise the `package.json` name, then the directory name), and its key in the hub's `KXM_PROJECT_TOKENS` holds its token. Agents see only peers in the same project. Compare [project ID](#project-id).
+The authentication and discovery namespace on the hub. Every command resolves it the same way: `--project` or `KXM_PROJECT`, then the [project ID](#project-id) in `.kxm/project.yaml`, then the `package.json` name, then the directory name. Its key in the hub's `KXM_PROJECT_TOKENS` holds its token. Agents see only peers in the same project.
 
 ### Project ID
 
-The stable `prj_` identifier in `.kxm/project.yaml`. The [Runtime](#runtime) and hub sync use it. It is not the hub [project](#project) name, even though both describe the same body of work.
+The stable `prj_` identifier in `.kxm/project.yaml`. It is the hub [project](#project) name unless `--project` or `KXM_PROJECT` overrides it. The [Runtime](#runtime) store keeps this id as the local key.
 
 ### Project token
 

package/docs/operations/troubleshooting.md

@@ -87,6 +87,9 @@ If a malformed claim remains, read the exact `.pid` JSON in the state directory
 | `hub_url_invalid` | Use an `http` or `https` URL without user info, query or fragment |
 | `hub_bind_unauthenticated` | The URL is remote and this machine has no token for the project; export it and bind again |
 | `hub_credential_unreadable` | Repair or remove `hub-env.json` under the user state root |
+| `cloud_token_missing` | A `--cloud` binding's variable is empty and it has no working command. Export the variable or fix `--token-command`. This machine's hub-env token is not sent |
+| `cloud_flag_required` | `--token-env` or `--token-command` was passed without `--cloud` |
+| 401 after binding a loopback forward | The bind was not `--cloud`, so the client sent the local hub-env token. See [Cross-box peer attach](../operations.md#cross-box-peer-attach) |
 
 ## Claude Code plugin and MCP
 

package/docs/operations.md

@@ -0,0 +1,154 @@
+# Operate a KXM hub
+
+This page is the operator index for a [hub](glossary.md#hub): where the other
+operations guides live, and how to attach a client on another machine to a hub
+that is not reachable from the internet. The client in that setup is a local
+`kxm` CLI, plus the Pi and Claude Code agents that CLI starts.
+
+## Where each procedure lives
+
+| Procedure | Page |
+|---|---|
+| Install the services on a tenant box, including loopback listeners | [Deploy KXM](operations/deploy.md) |
+| Health, readiness, metrics, logs, and alerts | [Monitor KXM](operations/monitoring.md) |
+| Stopped-state backup of all six state roots, and restore | [Back up and restore KXM](operations/backup-and-restore.md) |
+| Package update, plugin reinstall, and schema ceilings | [Upgrade KXM](operations/upgrade.md) |
+| Runtime outbox, sync refusals, and hub leases | [Operate Runtime sync and leases](operations/runtime-sync.md) |
+| Symptoms, causes, and fixes | [Troubleshoot KXM](operations/troubleshooting.md) |
+
+The six roots are the checkout, the workspace, workspace state, the user state
+root, user config, and federated telemetry. The stopped-state copy of each one
+is in [Back up and restore KXM](operations/backup-and-restore.md).
+
+## Before you begin
+
+- The `kxm` CLI is installed on the client machine.
+- You can open SSH to the hub host, and you already have that host's key.
+- The hub's admin token is in a password manager. 1Password CLI (`op`) is the
+  usual source. The token is never written into `hub-binding.json`.
+
+## Cross-box peer attach
+
+Use this when the hub listens on loopback on a private machine and your client
+reaches it through an SSH local forward. A plain `kxm hub bind` of
+`http://127.0.0.1:17331` is a loopback bind: it stores no credential, and later
+commands send this machine's hub-env admin token. The remote hub rejects that
+token with 401. `--cloud` marks the binding remote even though the URL is
+loopback, and names where the token comes from without storing the token.
+
+### Open the forward with a pinned host key
+
+Pin the host key before the first connection. Do not accept a key on first use.
+
+```bash
+ssh-keyscan -H 10.31.0.21 >> ~/.ssh/known_hosts
+ssh -N \
+  -o ExitOnForwardFailure=yes \
+  -o StrictHostKeyChecking=yes \
+  -o UserKnownHostsFile="$HOME/.ssh/known_hosts" \
+  -L 127.0.0.1:17331:127.0.0.1:7331 \
+  user@10.31.0.21
+```
+
+Leave that SSH session open. Hub traffic then goes to `127.0.0.1:17331` on the
+client and comes out on the hub host's loopback port 7331.
+
+<details><summary>PowerShell</summary>
+
+```powershell
+ssh-keyscan -H 10.31.0.21 >> $env:USERPROFILE\.ssh\known_hosts
+ssh -N `
+  -o ExitOnForwardFailure=yes `
+  -o StrictHostKeyChecking=yes `
+  -o UserKnownHostsFile="$env:USERPROFILE\.ssh\known_hosts" `
+  -L 127.0.0.1:17331:127.0.0.1:7331 `
+  user@10.31.0.21
+```
+
+</details>
+
+### Bind the forward as a cloud hub
+
+Pick one token source. The environment variable is enough when the shell
+already holds the token. The command form asks 1Password each time a command
+needs the token. Do not put the token text in `--token-command`: that string
+is stored in the binding.
+
+```bash
+export KXMD_HUB_TOKEN="$(op read 'op://Private/kxmd/admin-token')"
+kxm hub bind --cloud --token-env KXMD_HUB_TOKEN http://127.0.0.1:17331
+kxm hub view
+```
+
+Or name the 1Password command and skip the variable:
+
+```bash
+kxm hub bind --cloud \
+  --token-command "op read op://Private/kxmd/admin-token" \
+  http://127.0.0.1:17331
+```
+
+Expected output:
+
+```text
+bound hub http://127.0.0.1:17331 · remote · health=on · token is not stored
+hub health=true ready=true · remote hub
+```
+
+`--token-env` and `--token-command` can be combined. A non-empty variable wins.
+Otherwise the command runs. The command is a program and arguments, not a shell
+pipeline (`|`, `&`, `;`, and redirection are refused).
+
+<details><summary>PowerShell</summary>
+
+```powershell
+$env:KXMD_HUB_TOKEN = op read "op://Private/kxmd/admin-token"
+kxm hub bind --cloud --token-env KXMD_HUB_TOKEN http://127.0.0.1:17331
+kxm hub view
+```
+
+</details>
+
+### What --cloud changes
+
+| | Local bind | `--cloud` bind |
+|---|---|---|
+| Loopback URL | Scope `loopback`. No credential required | Scope `remote`, including an SSH forward |
+| Token stored in `hub-binding.json` | No | No. The file names `tokenEnv` and/or `tokenCommand` |
+| Credential later commands send | `KXM_AUTH_TOKEN`, then this machine's hub-env | The named source only. Hub-env is not a fallback |
+| Missing source | Agent commands report `project_token_missing` | `cloud_token_missing` or `cloud_token_command_failed`. The local admin token is not sent |
+| `kxm hub start` from an extension | May start a local hub | Does not start a local hub when the forward is down (`cloud_hub_unreachable`) |
+
+`kxm hub view`, `kxm tenant status`, `kxm peer`, `kxm workflow` agent commands,
+`kxm context`, Runtime presence, and the environment exported for a Pi worker
+all use that source. `kxm agent worker` puts `KXM_AUTH_TOKEN` in the child
+process environment only. It does not write the token to disk.
+
+The hub project id is the same value for peer commands and `kxm tenant status`:
+`--project` or `KXM_PROJECT`, then the `id` in `.kxm/project.yaml`, then
+`package.json` `name`, then the directory name.
+
+### Remove the binding
+
+```bash
+kxm hub unbind
+```
+
+Unbind deletes `hub-binding.json`. It does not delete hub-env, and it does not
+close the SSH forward. Stop the forward by ending the `ssh -N` session.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| 401 `invalid_auth` after binding `127.0.0.1:17331` | The bind was not `--cloud`, so the client sent this machine's hub-env admin token | Bind again with `--cloud` and a token source that holds the remote hub's token. Unset a stale `KXM_AUTH_TOKEN` that points at the local hub |
+| `cloud_token_missing` | `KXMD_HUB_TOKEN` (or the variable you named) is unset or empty, and no command is configured | Export the variable or pass `--token-command`. The local hub-env token is intentionally unused |
+| `cloud_token_command_failed` | `op` exited non-zero, timed out, or printed more than one line | Run the same command in a terminal and sign in to 1Password. Do not paste the token into the binding |
+| Clients through one SSH host get locked out together | The hub rate-limits by agent id, otherwise by source address. Every forward from one SSH session shares `127.0.0.1` on the hub. `sshd` `MaxStartups` and `MaxSessions` can refuse new forwards first | Give each long-lived agent its own name. Raise the SSH limits on that host if many people share one jump host. Do not point two tenants at one hub |
+| `kxm hub view` says `loopback` for the forward | `--cloud` was omitted | Bind again with `--cloud`. `KXM_SERVER_URL` overrides the binding URL and is labeled on its own |
+
+## Next steps
+
+- Deploy the hub itself: [Deploy KXM](operations/deploy.md)
+- Read health and metrics: [Monitor KXM](operations/monitoring.md)
+- Command flags: [kxm hub bind](reference/cli-reference.md#kxm-hub-bind)

package/docs/reference/cli-reference.md

@@ -569,16 +569,17 @@ kxm hub stop --wait-ms 8000 --json
 ### `kxm hub bind`
 
 ```text
-kxm hub bind <url>
+kxm hub bind <url> [--cloud] [--token-env <name>] [--token-command <command>]
 ```
 
 Binds this machine to a running hub by writing `hub-binding.json` under the user state root, then probes the hub's health for up to 300 ms. Every hub client uses the binding when `KXM_SERVER_URL` is unset.
 
 - Arguments: `<url>`, Hub base URL (http or https).
 - A URL with credentials, a query, a fragment, or a scheme other than http or https fails with `hub_url_invalid` (exit 2).
-- A remote (non-loopback) URL is refused with `hub_bind_unauthenticated` (exit 2, `nextAction: "export_kxm_auth_token"`) unless a credential for the current project resolves from `KXM_AUTH_TOKEN` or the persisted `hub-env.json`. A malformed record fails with `hub_credential_unreadable` (exit 2).
+- A remote (non-loopback) URL is refused with `hub_bind_unauthenticated` (exit 2, `nextAction: "export_kxm_auth_token"`) unless a credential for the current project resolves from `KXM_AUTH_TOKEN` or the persisted `hub-env.json`. A malformed record fails with `hub_credential_unreadable` (exit 2). A loopback URL without `--cloud` still binds with no credential.
+- `--cloud` marks the binding remote even when the URL is a loopback forward. It requires `--token-env`, `--token-command`, or both. The token is not written. A non-empty variable wins; otherwise the command runs. Source flags without `--cloud` fail with `cloud_flag_required`. A missing source later fails with `cloud_token_missing` and does not fall back to hub-env. See [Cross-box peer attach](../operations.md#cross-box-peer-attach).
 - Mutates the binding file. `--dry-run` validates and prints the plan without writing.
-- JSON keys: `url`, `scope`, `file`, `health` (`on`, `off`, or `unknown`), `probeMs`.
+- JSON keys: `url`, `scope`, `file`, `health` (`on`, `off`, or `unknown`), `probeMs`. A cloud bind also returns `cloud`, and `tokenEnv` or `tokenCommand` when set.
 
 ```bash
 kxm hub bind http://127.0.0.1:7331 --dry-run

package/docs/reference/configuration.md

@@ -108,7 +108,7 @@ Every agent client (the Pi extension, the Claude Code MCP server, and the `kxm p
 |---|---|---|
 | `KXM_SERVER_URL` | `http://127.0.0.1:7331` | Hub base URL. For the CLI, the machine's `kxm hub bind` URL is used when this is unset |
 | `KXM_AUTH_TOKEN` | See below | The project token for this agent's project |
-| `KXM_PROJECT` | `name` in `package.json` in the working directory, else the directory name | Project for discovery and authentication |
+| `KXM_PROJECT` | `id` in the nearest `.kxm/project.yaml`, else `name` in `package.json` in the working directory, else the directory name | Project for discovery and authentication. An explicit `--project` flag on `kxm peer list` and `kxm tenant status` wins over this variable. The same resolver is used by peer commands, tenant status, workers, the Pi extension, and the Claude Code MCP server |
 | `KXM_AGENT_NAME` | Harness-specific (see below) | Name peers see; unique among online agents in the project, compared case-insensitively |
 | `KXM_AGENT_PURPOSE` | Harness-specific (see below) | One line peers use to decide what to send this agent |
 
@@ -120,6 +120,16 @@ Every agent client (the Pi extension, the Claude Code MCP server, and the `kxm p
 
 A clean shutdown marks an identity offline. Reconnecting with the same project and name resumes its durable agent ID and rotates its agent key. If the Claude Code name is already online in the project, the MCP server registers once more as `<name>-<pid>`.
 
+A `--cloud` hub binding replaces this table's token lookup for every client, including agents. The token comes from the binding's `--token-env` or `--token-command`, never from this machine's hub-env file, and it is not written to disk. `kxm agent worker` copies it into the child process environment as `KXM_AUTH_TOKEN`.
+
+Also check plugin.json is valid JSON.
+
+And configuration table cell might be very long. That's ok.
+
+Look at harness table "never the admin token" - the new paragraph clarifies cloud. Good.
+
+Plugin README add one sentence under which token.
+
 ## Claude Code plugin settings
 
 The plugin asks for `server_url`, `auth_token`, `agent_name`, `agent_purpose` and `project` when you install it, and passes them to its MCP server as `KXM_SERVER_URL`, `KXM_AUTH_TOKEN`, `KXM_AGENT_NAME`, `KXM_AGENT_PURPOSE` and `KXM_PROJECT`. It also sets `KXM_PROJECT_DIR` to the directory Claude Code started in. Change them with `/plugin configure kxm@kxm`. Every field, default and token rule is in [Claude Code plugin settings](config-reference.md#claude-code-plugin-settings) and the [plugin README](../../plugins/kxm/README.md).

package/docs/reference/harness-routing.md

@@ -131,11 +131,11 @@ This is the same vendor through Pi and OpenRouter, which the brake refuses:
 
 ```yaml
 harness: pi
-model: openrouter/x-ai/grok-4.6
+model: openrouter/x-ai/grok-4.7
 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: 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 selector is `openrouter/x-ai/grok-4.7` 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.
 
@@ -156,7 +156,9 @@ roster:
   - route: pi-qwen3-coder-plus-openrouter
     effort: medium
   - route: agy-gemini-3-8-flash-high
+    effort: medium
   - route: agy-gemini-3-8-flash-medium
+    effort: medium
 ```
 
 `grok-grok-4-7` resolves to `.kxm/models/grok-grok-4-7.yaml`: harness `grok`, model `grok-4.7`, vendor `xai`, status `admitted`, permission `edit`. `pi-qwen3-coder-plus-openrouter` is harness `pi`, model `openrouter/qwen/qwen3-coder-plus`, vendor `alibaba`. `agy-gemini-3-8-flash-high` 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-grok-4-7)`. The previous ids (`grok-native`, `qwen-openrouter-pi`, `gemini-agy`) are aliases.
@@ -171,8 +173,8 @@ Role files are what `kxm role` and the Runtime membership check use.
 
 ```text
 admitted openrouter/qwen/qwen3-coder-plus
-admitted xai/grok-4.6
-disabled openrouter/x-ai/grok-4.6
+admitted xai/grok-4.7
+disabled openrouter/x-ai/grok-4.7
 ```
 
 The first segment of an id is the provider, and the rest is the model id. A route id does not name a harness. The first segment tells you which harness can run it. For an aggregator, the next segment names the vendor, and the Pi brake reads that too:
@@ -205,11 +207,11 @@ select a model from the refreshed inventory
 It exits with code 2. A bare OpenRouter slug is accepted, but it is not a dispatchable selector:
 
 ```bash
-kxm routes admit --model x-ai/grok-4.6 --dry-run
+kxm routes admit --model x-ai/grok-4.7 --dry-run
 ```
 
 ```text
-would admit x-ai/grok-4.6
+would admit x-ai/grok-4.7
 ```
 
 If that id were admitted, an agent would need `provider: x-ai`. Pi has no provider called `x-ai`, so the Pi auth probe would fail closed. When a route needs a provider prefix that the inventory does not carry, admit it by a Git-reviewed edit of `.kxm/routes.yaml`, after the admission decision is reviewed.
@@ -218,13 +220,13 @@ If that id were admitted, an agent would need `provider: x-ai`. Pi has no provid
 
 The same model shows up under different ids depending on the file:
 
-| Where | Id for Grok 4.6 | What that id means |
+| Where | Id for Grok 4.7 | What that id means |
 |---|---|---|
-| `.kxm/routes.yaml`, agent selector | `xai/grok-4.6` | Provider `xai`. Needs `harness: grok`. |
-| `.kxm/routes.yaml`, agent selector | `openrouter/x-ai/grok-4.6` | OpenRouter through Pi. The brake refuses it. |
-| `.kxm/models/inventory.yaml`, source `pi` | `xai/grok-4.6` | Pi's own `xai` provider. The brake refuses it. |
-| `.kxm/models/inventory.yaml`, source `openrouter` | `x-ai/grok-4.6` | The OpenRouter catalog slug. The inventory stores OpenRouter ids without an `openrouter/` prefix. |
-| `.kxm/prices.yaml` | `id: xai/grok-4.6`, `provider: xai`, alias `x-ai/grok-4.6` | A list price that applies only to provider `xai`, because price lookup filters by provider. |
+| `.kxm/routes.yaml`, agent selector | `xai/grok-4.7` | Provider `xai`. Needs `harness: grok`. |
+| `.kxm/routes.yaml`, agent selector | `openrouter/x-ai/grok-4.7` | OpenRouter through Pi. The brake refuses it. |
+| `.kxm/models/inventory.yaml`, source `pi` | `xai/grok-4.6` | Pi's own `xai` provider from the last `pi --list-models` capture. The brake refuses it. This refresh did not re-run Pi, and that capture has no `xai/grok-4.7` row. |
+| `.kxm/models/inventory.yaml`, source `openrouter` | `x-ai/grok-4.7` | The OpenRouter catalog slug. The inventory stores OpenRouter ids without an `openrouter/` prefix. |
+| `.kxm/prices.yaml` | `id: xai/grok-4.7`, `provider: xai`, alias `x-ai/grok-4.7` | A list price that applies only to provider `xai`, because price lookup filters by provider. `xai/grok-4.6` remains a separate row. |
 
 An inventory id can also mean something else in `.kxm/routes.yaml`. For example, the inventory can list `openai/gpt-5.6-sol` from the OpenRouter feed with OpenRouter prices, while in `.kxm/routes.yaml` the same string means provider `openai` through native `codex`.
 
@@ -341,12 +343,12 @@ The live one-shot producer runs every harness read-only, with a 120-second proce
 
 The Runtime does not run a step live when it has `write` access to a repository; it hands the run off with `step_unsupported`. Only Pi runs as a long-lived worker.
 
-### Grok 4.6
+### Grok 4.7
 
 | | Native `grok` | Pi + OpenRouter |
 |---|---|---|
-| 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` |
+| Model file | `harness: grok`, `model: grok-4.7`, `vendor: xai` | `harness: pi`, `model: openrouter/x-ai/grok-4.7`, `vendor: xai` |
+| Selector | `xai/grok-4.7` | `openrouter/x-ai/grok-4.7` |
 | Billing | grok.com subscription (OAuth) | OpenRouter credit |
 | Recorded `costBasis` | `unknown` | None: the brake refuses it before dispatch |
 | Mode | One-shot `grok --single`. Not a worker. | Refused as a one-shot and as a worker model |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.163",
+  "version": "0.7.165",
   "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.163",
+  "version": "0.7.165",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",
@@ -65,7 +65,7 @@
     "project": {
       "type": "string",
       "title": "Project",
-      "description": "Hub project key; must match a key in the hub KXM_PROJECT_TOKENS. Blank uses the package.json name, then the directory name",
+      "description": "Hub project key; must match a key in the hub KXM_PROJECT_TOKENS. Blank uses the .kxm/project.yaml id, then the package.json name, then the directory name",
       "required": false
     }
   }

package/plugins/kxm/README.md

@@ -58,7 +58,7 @@ Claude Code asks for these options when you install the plugin. Change them late
 | `auth_token` | `KXM_AUTH_TOKEN` | Blank | This project's token from the hub's `KXM_PROJECT_TOKENS`. Leave it blank on the machine that runs the hub. Never the hub admin token. Marked sensitive. |
 | `agent_name` | `KXM_AGENT_NAME` | `claude` | Name other agents see. The first active session in a project keeps it; a later concurrent session registers as `<name>-<pid>`. |
 | `agent_purpose` | `KXM_AGENT_PURPOSE` | `Claude Code implementation and review agent` | One line that peers use to decide what to send this agent. |
-| `project` | `KXM_PROJECT` | Blank | Hub project key; must match a key in the hub's `KXM_PROJECT_TOKENS`. Blank uses `name` from the project's `package.json`, then the directory name. |
+| `project` | `KXM_PROJECT` | Blank | Hub project key; must match a key in the hub's `KXM_PROJECT_TOKENS`. Blank uses the `id` in `.kxm/project.yaml`, then `name` from `package.json`, then the directory name. |
 
 The MCP server also receives `KXM_PROJECT_DIR`, set to the directory Claude Code was started in (`CLAUDE_PROJECT_DIR`). It decides the default project key and whether this is a KXM project (one with a `.kxm/` directory).
 
@@ -67,7 +67,7 @@ The MCP server also receives `KXM_PROJECT_DIR`, set to the directory Claude Code
 The plugin acts as an agent of one hub project and authenticates with that project's token. It never uses the hub admin token.
 
 - On the machine that runs the hub, leave `auth_token` blank. The MCP server then uses the project token the hub saved for this project in `hub-env.json` under the user state root (`KXM_STATE_HOME`, or the platform default listed in [State outside the project](../../docs/reference/config-reference.md#state-outside-the-project)). It uses only that entry, never the admin token saved beside it.
-- On any other machine, enter this project's token at `/plugin configure kxm@kxm`. Get it from whoever runs the hub, through your password manager.
+- On any other machine, enter this project's token at `/plugin configure kxm@kxm`. Get it from whoever runs the hub, through your password manager. When the machine is bound with `kxm hub bind --cloud`, leave `auth_token` blank: the MCP server reads the binding's token source and does not store the token. The recipe is [Cross-box peer attach](../../docs/operations.md#cross-box-peer-attach).
 - Never enter the hub admin token. It is the operator's credential. The hub accepts it for any project that has no token of its own, so an agent holding it could act in projects it was never given.
 - Without a project token, every `kxm_*` tool fails with `KXM has no project token for project <p> on this machine`, and the MCP server does not contact the hub.