@kontextmind/kxm 0.7.167 → 0.7.169

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

package/CHANGELOG.md

@@ -181,6 +181,18 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Changed
 
+- **Tool policy is enforced at load and before dispatch.**
+  `coordinator` and `read-only` select the read-only one-shot profile.
+  `workspace-writer` and `tests-writer` select the edit profile. Dispatch
+  uses the narrowest of the role `permission`, that preset profile, and the
+  step's repository access. An agent preset wider than its role is
+  `tool_preset_exceeds_role` at load, and `step_unsupported` before a
+  producer starts if those files were already loaded. A write step whose
+  resolved profile is read-only is the same handoff. The detail names the
+  role permission and the step access. `tools.allow` and `tools.deny` stay
+  on the MCP surface through `enforceToolPolicy`. See
+  [agent files](docs/reference/config-reference.md#kxmagentsidyaml-kxmagentv1).
+
 - **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
@@ -605,6 +617,24 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Fixed
 
+- **`kxm hub view` and `kxm hub bind` require a kxm hub body.** HTTP 200 HTML
+  (an Authentik login page) and 30x redirects are not healthy. The JSON
+  `health` field is `{ "error": "auth_proxy" }`, not the page. Bind refuses
+  with `hub_not_kxm` unless `--force` is set. A timeout or a dead host still
+  binds. `kxm hub view` names the key source that would supply the token
+  (`env:<NAME>` only when that variable is set, `op:<ref>`, `token-command`,
+  `hub-env`, or `missing`).
+- **A cloud bind no longer breaks a 0.7.159 Runtime supervisor.** Cloud fields
+  live in `hub-binding.cloud.json`. `hub-binding.json` stays a three-key local
+  record or is omitted, so the old reader falls back to the local hub instead
+  of throwing `malformed hub binding` and stopping sync. A newer schema is a
+  warning and `no_hub`, not a stalled tick. Restart the supervisor, hub, and
+  workers after upgrading and before `kxm hub bind --cloud`.
+- **`kxm update --kxm` downloads with curl when `gh` is missing**, and still
+  verifies the release sha256.
+- **The npm publish job waits until `npm view` shows the version** (bounded)
+  before it reports success. GitHub release log lines no longer say "published"
+  in a way that means the package is on npm.
 - **A one-shot outcome is the last top-level JSON object that ends the reply.** It is accepted only when the prefix before it leaves every string, object, and array closed (a naive state machine plus a container lexer over the last container openers). Anything ambiguous, truncated, or followed by prose fails closed. The authoring witness counts `HEAD`, so a writer that commits is credited.
 
 - **The test suite no longer passes `--test-timeout`.** Under `node --test` that flag bounds each file, so coverage on CI timed out `test/core/engine.test.ts` at three minutes. The wall clock in `scripts/run-bounded.mjs` still bounds each script.

package/docs/contributing/ci-and-release.md

@@ -201,7 +201,12 @@ versions by hand.
 4. **Publish npm** runs in the protected `npm-publish` environment. It skips a
    version already on npm. Otherwise `scripts/kxm-publish-npm.mjs` confirms the
    GitHub release is published, downloads the asset, verifies its sha256
-   against the release digest, and runs `npm publish` on that exact file.
+   against the release digest, and runs `npm publish` on that exact file. The
+   job then polls `npm view @kontextmind/kxm@<version> version` (up to 20
+   minutes, `KXM_NPM_VISIBLE_WAIT_MS=0` skips the wait) and reports success
+   only after the registry shows that version. Log lines that say the GitHub
+   release is public are not an npm publish. The registry can lag the GitHub
+   release by many minutes.
 
 Every step is idempotent. Rerunning the Release workflow for a tag that is
 already published or already on npm reports it and changes nothing.

package/docs/operations/runtime-sync.md

@@ -94,8 +94,9 @@ sync prj_a17d607765e144cd95b93a8715d360b6: blocked (pending 0, acked 1, refused
 | State | Meaning | Action |
 |---|---|---|
 | `ok` | Rows are being acknowledged | None |
-| `no_hub` | No hub is bound or set; rows are kept locally by design | Bind a hub if you want hub-side views |
+| `no_hub` | No hub is bound or set, or this build ignored a binding it does not understand; rows are kept locally by design | Bind a hub if you want hub-side views. A warning that names `hub-binding.json` means restart the supervisor after upgrading, then bind again |
 | `blocked` | Transport or credential failure; rows stay pending and the tick backs off, up to 5 minutes | Fix the cause; the next attempt resumes on its own |
+| `sync: the supervisor is running but did not answer /v1/sync/status` | The process is up, and `kxm runtime status` could not read `GET /v1/sync/status`. A hung supervisor, a token mismatch, or a supervisor started before an upgrade | `kxm runtime stop`, then `kxm runtime start`. Restart the hub and workers too after an upgrade and before a cloud bind |
 | `refusing` | The hub durably refused rows, or answered without a result for some | Fix the hub side, then run `kxm runtime sync-retry` |
 
 A project whose run store this release cannot open shows `blocked (its store is not readable by this build)` with the reason; see [Upgrade KXM](upgrade.md#understand-schema-changes). Right after the supervisor starts, the status can read `no project registered with this Runtime yet` until the first tick.

package/docs/operations/troubleshooting.md

@@ -89,6 +89,7 @@ If a malformed claim remains, read the exact `.pid` JSON in the state directory
 | `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-command` was passed without `--cloud`. `--token-env` and `--key-op` are key references and are valid on a local bind |
+| `hub_not_kxm` | The URL returned an HTML login page or a 30x redirect, not a kxm `/health` body. `https://hub.kxmd.dev` is an Authentik forward-auth page. Bind the SSH forward `http://127.0.0.1:17331`. `--force` records the URL anyway and does not make the proxy a hub |
 | 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
@@ -209,6 +210,9 @@ A gate step declares an outcome its `expect` value never produces. The message n
 | `runtime supervisor is not running` or `runtime_not_running` | The supervisor stopped | `kxm runtime start`; commands such as `kxm run` also start it on demand |
 | `runtime_supervisor_unreachable` | A live supervisor process does not answer its token probe | Check the PID from `kxm runtime status`, stop a hung process with your OS tools, then `kxm runtime start` |
 | `project_required` | The command ran outside a KXM project | Run it from the checkout, or run `kxm init` |
+| `project_home_conflict` | This checkout is not the registered home for that project id. A different repository already owns it, the home runtime is immutable, or the primary checkout is already the home row | Use the original checkout, or a worktree of that repository. Do not copy the project id into an unrelated clone, and do not delete the database |
+| `runtime_schema_newer` | The store was written by a newer release than this build | Upgrade KXM. Do not delete the database |
+| `sync: the supervisor is running but did not answer /v1/sync/status` | The supervisor process is up, and `GET /v1/sync/status` failed. A hung process, a token mismatch, or a supervisor started on an older release | `kxm runtime stop`, then `kxm runtime start`. After an upgrade, restart the hub and workers before a cloud bind. See [Check sync status](runtime-sync.md#check-sync-status) |
 | `producer_route_not_admitted` | A live drive uses a model route that is not admitted | `kxm routes admit --model <provider/model>`, or drive with `--simulated` |
 | A 429, timeout, or provider error fails the attempt on the first route | The role's `policy.fallback.onError` is empty, omits that class, or `maxSwitches` is already spent. Cancellation, policy refusal, and authentication do not walk | List the class on the role, admit the next route, and read `routing.route_switched` in the run events. `kxm routing report` prints Route switches |
 | `pi_not_authenticated: pi harness not detected (pi_native_impersonation_blocked)` | A Pi agent's model belongs to a vendor with its own harness | Set the agent's native `harness:`, or choose an admitted Pi route whose vendor has none |

package/docs/operations/upgrade.md

@@ -6,7 +6,7 @@ Move the `kxm` CLI, the hub, the Runtime, and the Claude Code or Pi integrations
 
 - Protected storage for a full backup; see [Back up and restore KXM](backup-and-restore.md).
 - A window in which the hub, the Runtime supervisor and long-lived workers may stop.
-- The GitHub CLI (`gh`, signed in) if you apply updates with `kxm update --kxm` from the default `github` source, which downloads the release tarball with it.
+- The GitHub CLI (`gh`, signed in) if you apply updates with `kxm update --kxm` from the default `github` source. When `gh` is not installed, that command downloads the same `kxm-<version>.tgz` with curl and still checks the release sha256 before installing. Without a working `kxm` either, use the curl commands in [Update the CLI without gh](#update-the-cli-without-gh).
 
 ## Check for an update
 
@@ -54,12 +54,27 @@ Use the path that matches how KXM was installed. `kxm update --kxm` applies an u
 | Project dependency | `npm install @kontextmind/kxm@latest` in that project |
 | Source checkout | `git pull`, then `npm ci` |
 
-`kxm update --kxm` refuses to install a GitHub release that does not publish a SHA-256 digest for its tarball (`release_digest_missing`) or whose download does not match it (`release_digest_mismatch`). Preview the steps first:
+`kxm update --kxm` refuses to install a GitHub release that does not publish a SHA-256 digest for its tarball (`release_digest_missing`) or whose download does not match it (`release_digest_mismatch`). When `gh --version` fails, the download step is `curl --fail --silent --show-error --location` against `https://github.com/kontextmind/kxm/releases/download/v<version>/kxm-<version>.tgz`, and the digest check is unchanged. Preview the steps first:
 
 ```bash
 kxm update --kxm --dry-run
 ```
 
+### Update the CLI without gh
+
+On a host that has neither `gh` nor a working `kxm`, download the release tarball and check the digest printed on the GitHub release before installing:
+
+```bash
+version=0.7.166
+curl --fail --silent --show-error --location \
+  --output "kxm-${version}.tgz" \
+  "https://github.com/kontextmind/kxm/releases/download/v${version}/kxm-${version}.tgz"
+sha256sum "kxm-${version}.tgz"
+npm install --global --omit=peer "./kxm-${version}.tgz"
+```
+
+Refuse a tarball whose sha256 does not match the release asset digest.
+
 ### Update harnesses and plugins
 
 Without `--check` or a lone `--kxm`, `kxm update` also runs the native updaters of detected harnesses. Narrow it with a harness id and one scope:
@@ -76,7 +91,7 @@ kxm update pi --models             # refresh Pi model catalogs
 
 ## Start and verify
 
-1. Start the hub (or its service), then the Runtime with `kxm runtime start`.
+1. Start the hub (or its service), then the Runtime with `kxm runtime start`. Restart workers too. Do this after the upgrade and again before `kxm hub bind --cloud`, so an older supervisor does not keep a binding it cannot read.
 2. Check `kxm hub view`, `/ready` and `/metrics`.
 3. Check `kxm runtime status` until every project reports `ok` or `no_hub`.
 4. Send one request between two agents and read one Runtime run with `kxm runs status <run-id>`.

package/docs/operations.md

@@ -88,16 +88,32 @@ kxm hub bind --cloud \
   http://127.0.0.1:17331
 ```
 
-Expected output:
+Expected output when `KXMD_HUB_TOKEN` is set:
 
 ```text
 bound hub http://127.0.0.1:17331 · remote · health=on · token is not stored
 hub health=true ready=true · remote hub · mode=cloud project=prj_example (.kxm/config.yaml hub.cloud.project) key=env:KXMD_HUB_TOKEN
 ```
 
+With only `--token-command`, and `KXMD_HUB_TOKEN` unset, `kxm hub view` prints
+`key=token-command`. It names the source that would actually supply the token:
+`env:<NAME>` only when that variable is non-empty, otherwise `op:<ref>`,
+`token-command`, `hub-env`, or `missing`. An unset variable is not reported as
+the source.
+
 `--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).
+pipeline (`|`, `&`, `;`, and redirection are refused). `--token-command` is
+stored only in the machine-wide binding (`hub-binding.cloud.json` under the
+user state root). It is not written to `.kxm/config.yaml`. Config holds
+`key.op` and `key.env` references only.
+
+`https://hub.kxmd.dev` is behind an Authentik forward-auth proxy. Clients
+cannot use it: `GET /health` returns the login page (HTTP 200 HTML, or a 302).
+`kxm hub view` treats that as unhealthy (`health=false`, and the JSON `health`
+field is `{ "error": "auth_proxy" }`, not the HTML). `kxm hub bind` refuses
+with `hub_not_kxm` and writes nothing unless you pass `--force`. The supported
+client path is the SSH forward above.
 
 <details><summary>PowerShell</summary>
 
@@ -114,8 +130,8 @@ kxm hub view
 | | 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 the active mode's key reference in `.kxm/config.yaml`, then this machine's hub-env | The active mode's key reference, then the binding's named source. Hub-env is not a fallback |
+| Token stored in the binding | No | No. `hub-binding.cloud.json` names `tokenEnv` and/or `tokenCommand`. `hub-binding.json` stays a three-key local record, or is omitted, so a 0.7.159 reader does not throw |
+| Credential later commands send | Agent commands use `KXM_AUTH_TOKEN`, then `hub.local` `key.env` / `key.op`, then this project's saved project token. They never use the hub-env admin token (`project_token_missing`). `kxm hub view` and `kxm tenant status` may use the admin token | The active mode's key reference, then the binding's named source. Hub-env is not a fallback |
 | Missing source | Agent commands report `project_token_missing` and name the project id that was sent | `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`) |
 
@@ -124,6 +140,47 @@ kxm hub view
 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.
 
+A local bind does not give agents the admin token from hub-env. Give them a
+project token in one of these ways:
+
+- On the client, export `KXM_AUTH_TOKEN` to that project's token, or set
+  `hub.local.key.env` / `hub.local.key.op` in `.kxm/config.yaml`.
+- On the hub, map the project id in `hub.projects` (an `op://` reference or an
+  environment variable name) or in `KXM_PROJECT_TOKENS`, keyed by the same id
+  the client sends.
+
+### Where to store tokens
+
+Keep hub admin and project tokens in 1Password and point KXM at `op://` references
+(`--key-op`, `key.op`, or `--token-command "op read op://..."`). Do not paste the
+token into `.kxm/config.yaml`, `hub-binding.json`, or `hub-binding.cloud.json`.
+
+A hub host that has no `op` binary should take the token from the environment
+or from a systemd credentials file. The unit in
+[Supervise the hub and Runtime](operations/deploy.md#the-hub) loads
+`EnvironmentFile=/etc/kxm/hub.env` (mode 0600) for `KXM_AUTH_TOKEN` and
+`KXM_PROJECT_TOKENS`.
+
+### Restart after an upgrade, and before a cloud bind
+
+Restart the Runtime supervisor, the hub, and workers after upgrading and before
+`kxm hub bind --cloud`:
+
+```bash
+kxm runtime stop
+kxm hub stop
+kxm runtime start
+kxm hub start
+```
+
+A 0.7.159 supervisor treats any extra key in `hub-binding.json` as
+`malformed hub binding` and stops syncing. This release keeps cloud fields in
+`hub-binding.cloud.json` and leaves `hub-binding.json` as a three-key local
+record, or omits it. An older reader then keeps the local hub instead of
+throwing. A binding newer than this build is ignored with a warning, and sync
+continues as `no_hub` rather than stalling. Processes that were already running
+keep the binding they loaded at start, so restart them after the upgrade.
+
 The hub project id is the same value everywhere: `--project` or `KXM_PROJECT`,
 then the active mode's `project` in `.kxm/config.yaml`, then the `id` in
 `.kxm/project.yaml`, then `package.json` `name`, then the directory name.
@@ -147,7 +204,8 @@ hub:
       op: op://Private/kxm/local-project-token
       env: KXM_LOCAL_PROJECT_TOKEN
   cloud:
-    url: https://hub.kxmd.dev
+    # Clients use an SSH forward. https://hub.kxmd.dev is an Authentik login page.
+    url: http://127.0.0.1:17331
     project: prj_example
     key:
       op: op://Private/kxmd/project-token
@@ -167,7 +225,8 @@ with `hub_config_invalid`.
 `kxm hub bind` and `kxm hub bind --cloud` write the mode, URL, project id, and
 key reference. `--key-op` is the `op://` reference for either mode.
 `--token-env` names the variable for either mode. `--token-command` stays
-cloud-only. `kxm hub view` prints the mode, URL, project id, and key source.
+cloud-only, and only in `hub-binding.cloud.json`, not in this file.
+`kxm hub view` prints the mode, URL, project id, and key source.
 It does not print the token. `kxm hub unbind` removes the binding and
 `hub.mode`, and leaves the `local` and `cloud` blocks in place.
 
@@ -185,7 +244,8 @@ send the `.kxm/project.yaml` id and the hub has no token for it.
 kxm hub unbind
 ```
 
-Unbind deletes `hub-binding.json` and clears `hub.mode` in `.kxm/config.yaml`.
+Unbind deletes `hub-binding.json` and `hub-binding.cloud.json`, and clears
+`hub.mode` in `.kxm/config.yaml`.
 The `local` and `cloud` blocks stay, so the next bind can switch mode again.
 It does not delete hub-env, and it does not close the SSH forward. Stop the
 forward by ending the `ssh -N` session.
@@ -200,6 +260,9 @@ forward by ending the `ssh -N` session.
 | `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 |
+| `hub_not_kxm`, or `kxm hub view` prints `auth proxy` with `health=false` | The URL is an Authentik (or other) login page, or a 30x redirect, not a kxm hub. `https://hub.kxmd.dev` is that case | Bind `http://127.0.0.1:17331` through the SSH forward. `--force` writes the binding anyway and is not a working client path |
+| `key=env:KXMD_HUB_TOKEN` while that variable is unset | An older `kxm hub view` named the configured variable even when it was empty | Upgrade. The line names `token-command`, `op:<ref>`, `hub-env`, or `missing` for the source that actually supplies the token |
+| `malformed hub binding` and sync stops after a cloud bind | A supervisor older than this release read cloud fields in `hub-binding.json` | Upgrade, then restart the supervisor, hub, and workers before binding `--cloud` again |
 
 ## Next steps
 

package/docs/reference/cli-reference.md

@@ -477,12 +477,12 @@ Starts, inspects, and stops the local KXM hub, and binds this machine to a hub.
 kxm hub view
 ```
 
-Calls `GET /health` and `GET /ready` on the target hub and reports whether the URL is loopback or remote, plus the mode, project id, and key source in effect. The key source is an environment variable name or an `op://` reference. The token is not printed.
+Calls `GET /health` and `GET /ready` on the target hub and reports whether the URL is loopback or remote, plus the mode, project id, and key source in effect. A probe counts only when the response is JSON (`application/json`, or `text/plain` with a JSON object) of the hub shape: `/health` is `{ "ok": true, "agents": <number> }` and `/ready` is `{ "ok": true, "storage": "sqlite"|"memory" }`. An HTTP 200 HTML login page, or a 30x redirect, is not healthy. The JSON `health` and `ready` fields then hold `{ "error": "auth_proxy" }` and never the HTML. The key source is the one that would supply the token: `env:<NAME>` only when that variable is non-empty, `op:<ref>`, `token-command`, `hub-env`, or `missing`. The token is not printed.
 
 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.
+- 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"}`.
 - Exit 0 when both probes succeed, 1 otherwise. A cloud mode with no resolvable key exits 2 with `cloud_token_missing`.
 
 ```bash
@@ -569,15 +569,16 @@ kxm hub stop --wait-ms 8000 --json
 ### `kxm hub bind`
 
 ```text
-kxm hub bind <url> [--cloud] [--token-env <name>] [--token-command <command>] [--key-op <op://vault/item/field>]
+kxm hub bind <url> [--cloud] [--token-env <name>] [--token-command <command>] [--key-op <op://vault/item/field>] [--force]
 ```
 
-Binds this machine to a running hub by writing `hub-binding.json` under the user state root and the non-secret endpoint (mode, URL, project id, key reference) into `.kxm/config.yaml`, then probes the hub's health for up to 300 ms. Every hub client uses that endpoint when `KXM_SERVER_URL` is unset. The token is never written.
+Binds this machine to a running hub by writing the binding under the user state root and the non-secret endpoint (mode, URL, project id, key reference) into `.kxm/config.yaml`, then probes the hub's health for up to 300 ms. A local bind writes `hub-binding.json` (`schema`, `url`, `boundAt` only). A `--cloud` bind writes `hub-binding.cloud.json` and leaves a three-key local file in place, or omits `hub-binding.json`, so a 0.7.159 reader does not throw `malformed hub binding` and stop sync. `--token-command` is stored only in that cloud file, not in `.kxm/config.yaml`. Every hub client uses that endpoint when `KXM_SERVER_URL` is unset. The token is never written.
 
 - 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 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`, `--key-op`, or a combination. The token is not written. A non-empty variable wins; otherwise an `op://` reference is read with `op read`, or the command runs. `--token-command` without `--cloud` fails with `cloud_flag_required`. `--token-env` and `--key-op` are also valid on a local bind and are stored only as references in config. A missing cloud 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).
+- The probe accepts a kxm `/health` body. A timeout (`health=unknown`) or a connection failure (`health=off`) still writes the binding. An HTML login page or a 30x redirect is `hub_not_kxm` (exit 2, `kind` `auth_proxy` or `redirect`) and writes nothing. The error names an auth proxy or a redirect. `--force` writes anyway. `https://hub.kxmd.dev` is an Authentik login page; clients use the SSH forward at `http://127.0.0.1:17331`.
 - Mutates the binding file and `.kxm/config.yaml`. `--dry-run` validates and prints the plan without writing.
 - JSON keys: `url`, `scope`, `file`, `configFile`, `project`, `health` (`on`, `off`, or `unknown`), `probeMs`. A cloud bind also returns `cloud`, and `tokenEnv` or `tokenCommand` when set.
 
@@ -984,7 +985,20 @@ Checks for or applies a KXM operator package update, and runs the native updater
 
 - Arguments: `[harness]`, Harness id (default: every detected harness).
 - `--check` cannot be combined with any other update flag or a harness (exit 2, `scope_conflict`), and at most one of `--self`, `--extensions`, `--models` is allowed (exit 2).
-- From a source checkout, `--check` reports the running version without network access, and `--kxm` is refused (exit 2, `install_kind_source`) with an instruction to `git pull`. Only npm-global installs can apply `--kxm`; other install kinds exit 2 with `install_kind_<kind>`. A GitHub release must publish a sha256 digest for `kxm-<version>.tgz` or the install fails closed (`release_digest_missing`, `release_digest_mismatch`).
+- From a source checkout, `--check` reports the running version without network access, and `--kxm` is refused (exit 2, `install_kind_source`) with an instruction to `git pull`. Only npm-global installs can apply `--kxm`; other install kinds exit 2 with `install_kind_<kind>`. A GitHub release must publish a sha256 digest for `kxm-<version>.tgz` or the install fails closed (`release_digest_missing`, `release_digest_mismatch`). When `gh` is missing, the github source downloads that same asset with `curl --fail --silent --show-error --location` and still verifies the digest before `npm install -g`.
+
+On a host with neither `gh` nor a working `kxm`, download and check it yourself:
+
+```bash
+version=0.7.166
+curl --fail --silent --show-error --location \
+  --output "kxm-${version}.tgz" \
+  "https://github.com/kontextmind/kxm/releases/download/v${version}/kxm-${version}.tgz"
+# Compare with the sha256 digest published on the GitHub release asset.
+sha256sum "kxm-${version}.tgz"
+npm install --global --omit=peer "./kxm-${version}.tgz"
+```
+
 - Settings come only from `update.yaml` under the user state root (`auto: true` enables auto-apply); a project `.kxm/update.yaml` is ignored with a warning.
 - Without `--check` or a lone `--kxm`, KXM probes harnesses (as `harness list` does) and runs each updater for the selected scope. An unknown harness id exits 2 (`unknown_harness` step); a failed step exits 1.
 - Honors `--dry-run`: steps are planned, not run, and the cached update notice is not refreshed.
@@ -1612,7 +1626,7 @@ Create a KXM run without executing steps. The run pins the project's `homeRuntim
 - Refuses `--workspace` (exit 2, `workspace_option_unsupported`).
 - Needs a KXM project. Starts and uses the Runtime; no hub needed. Honors `--dry-run`, which validates the project and prints the plan without starting the supervisor.
 - JSON keys: `idempotent`, `run` (`runId`, `homeRuntimeId`, `status`, `configRevision`), `supervisor` (`runtimeId`, `port`, `started`), and `execution` (`status: not_started`, `mode: live`, `defaultHarness`, `authentication: not_checked`, `prerequisites`, `nextSteps`). Dry run: `projectRoot`, `workflowId`, `configRevision`, `defaultHarness`, `prerequisites`. The obsolete `phase: pre-3a` field is no longer returned.
-- Errors: `workflow_required` (exit 2), `project_required`, `run_workflow_unknown`, `brief_and_prompt`, `brief_unreadable`, `lane_missing`, `lane_run_open`, `run_failed` with `issues` (any invalid file in the project fails the load, for example `gate_outcome_impossible`), `run_io_failed` (exit 1).
+- Errors: `workflow_required` (exit 2), `project_required`, `run_workflow_unknown`, `brief_and_prompt`, `brief_unreadable`, `lane_missing`, `lane_run_open`, `run_failed` with `issues` (any invalid file in the project fails the load, for example `gate_outcome_impossible`), `run_io_failed` (exit 1). `project_home_conflict` means this checkout is not the registered home for that project id: a different repository already owns it, the home runtime is immutable, or the primary checkout is already the home row. Use the original checkout, or a worktree of that repository. Do not copy the project id into an unrelated clone, and do not delete the database. `runtime_schema_newer` means the store was written by a newer release than this build. Upgrade KXM. Do not delete the database.
 - The `default` workflow that `kxm init` writes does not set `limits.maxAgentTimeMs`, so it can be driven. A workflow that sets that limit is created, but `kxm runs drive` refuses it with `run_handoff_required` (`limit_unsupported`); projects from older `kxm init` templates carry it on `default`.
 
 ```bash
@@ -1826,6 +1840,7 @@ No command-specific options.
 - Reads only. Never starts the supervisor.
 - JSON keys: `running`, `runtimeId`, `pid`, `port`, `state`, `heartbeatAt`, `startedAt`, `sync`.
 - Exit 0 when running, 1 when not (the JSON still says `ok: true`).
+- When the supervisor process is up but `GET /v1/sync/status` fails, the text line is `sync: the supervisor is running but did not answer /v1/sync/status`. The usual causes are a hung supervisor, a token the status command does not hold, or a supervisor started before an upgrade. `kxm runtime stop` and `kxm runtime start` replace it. A binding this build cannot read is a warning and `no_hub`, not a stalled sync; restart after upgrading and before a cloud bind. See [Check sync status](../operations/runtime-sync.md#check-sync-status).
 
 ```bash
 kxm runtime status

package/docs/reference/config-reference.md

@@ -337,7 +337,7 @@ with `retired_agent_routing_fields`.
 | `skills` | Unique identifiers, at most 64 | Optional | Skill names granted to the agent |
 | `instructions` | String, at most 16,000 characters | Optional | Not read by any code path yet. Step `instructions` are what reach the prompt. |
 | `executor` | `local`, `ssh`, or `exe-dev` | Optional | Loader (`executor_unknown`); recorded in the executor-policy revision; no dispatch path selects an executor from it yet |
-| `tools.preset` | `coordinator`, `read-only`, `workspace-writer`, or `tests-writer` | Optional | Loader (`tool_preset_unknown`): the preset must be registered. An agent `tools.preset` may only narrow the role preset. Enforcement of that rule is pending (P3). |
+| `tools.preset` | `coordinator`, `read-only`, `workspace-writer`, or `tests-writer` | Optional | Loader (`tool_preset_unknown`): the preset must be registered. `coordinator` and `read-only` select the read-only one-shot profile. `workspace-writer` and `tests-writer` select the edit profile. An agent preset may only narrow the role. A wider preset is `tool_preset_exceeds_role` at load. |
 | `tools.allow`, `tools.deny` | Unique identifiers, at most 128 each | Optional | A tool in both lists is `tool_policy_contradiction`; steps may only narrow the ceiling |
 | `defaultRepositoryAccess` | `none`, `read`, or `write` | Optional; the ceiling is `none` when absent | Loader: access ceiling for repositories not listed in `repositories` |
 | `repositories` | Map of repository ID to `none`, `read`, or `write`; at most 64 | Optional | Loader: per-repository access ceiling; IDs must be declared (`repository_unknown`) |
@@ -349,18 +349,30 @@ with `retired_agent_routing_fields`.
 | `session.reuse` | `compatible-run-scope` | Optional | Not read by any code path yet |
 | `session.maxIdleMs` | Integer, 0 to 31,536,000,000 | Optional | Not read by any code path yet |
 
-Tool presets are names checked against a registered list. The live one-shot
-producer launches the harness named by the selected model file, with a fixed
-argument set, and does not translate `tools` into harness flags. A read-only
-step uses the read-only set (`READ_ONLY_ONESHOT_ARGS` in
-`plugins/kxm/src/harness.ts`). A step with `write` access uses the audited
-writer set (`WRITER_ONESHOT_ARGS`), which exists only for `pi` (`-a` with
-extensions, skills, prompt templates and sessions off) and `grok`
-(`--always-approve` with subagents and web search off). Both approve every
-tool call, shell commands included, and neither confines the process to the
-checkout. A live write step on any other harness is handed off; see
+Tool presets are names checked against a registered list, then mapped onto
+the harness one-shot profiles in `plugins/kxm/src/harness.ts`. `coordinator`
+and `read-only` use the read-only argument set (`READ_ONLY_ONESHOT_ARGS`).
+`workspace-writer` and `tests-writer` use the audited writer set
+(`WRITER_ONESHOT_ARGS`), which exists only for `pi` (`-a` with extensions,
+skills, prompt templates and sessions off) and `grok` (`--always-approve`
+with subagents and web search off). Both approve every tool call, shell
+commands included, and neither confines the process to the checkout.
+
+Dispatch permission is the narrowest of the role `permission`, the preset
+profile (the role preset, then the agent preset), and the step's repository
+access (`write` is edit; `read` and `none` are read-only). A preset cannot
+widen a role. An agent preset that is wider fails load with
+`tool_preset_exceeds_role`, and dispatch refuses that file again with
+`step_unsupported` (field `tools.preset`) when the process already loaded
+it. A write step whose resolved profile is read-only is `step_unsupported`
+(field `permission`) before the producer starts. The detail names the role
+permission and the step access. A live write that does resolve to edit
+still hands off on a harness with no audited writer set; see
 [Steps the Runtime does not execute yet](#steps-the-runtime-does-not-execute-yet).
 
+`tools.allow` and `tools.deny` apply to the MCP surface through
+`enforceToolPolicy` in `plugins/kxm/src/commands.ts`.
+
 Example (the shape `kxm init` writes for `writer`):
 
 ```yaml
@@ -394,7 +406,7 @@ Runtime cannot reach the `antigravity` Pi provider yet. `kxm run` and the
 Runtime read the agents. `kxm trust` diffs them.
 
 Error codes: `retired_agent_routing_fields`, `executor_unknown`,
-`tool_preset_unknown`, `tool_policy_contradiction`, `repository_unknown`, and
+`tool_preset_unknown`, `tool_preset_exceeds_role`, `tool_policy_contradiction`, `repository_unknown`, and
 the path codes under
 [Rules shared by the project bundle](#rules-shared-by-the-project-bundle).
 
@@ -1311,6 +1323,8 @@ no recorded cost is never ready.
 ```yaml
 # .kxm/config.yaml (project scope) or ~/.config/kxm/config.yaml (user scope).
 # The project file wins. Key fields are references, never tokens.
+# --token-command is not a config field. It lives only in the machine-wide
+# hub-binding.cloud.json written by `kxm hub bind --cloud`.
 hub:
   autoStart: background        # background | off
   mode: local                  # local | cloud
@@ -1321,7 +1335,8 @@ hub:
       op: op://Private/kxm/local-project-token
       env: KXM_LOCAL_PROJECT_TOKEN
   cloud:
-    url: https://hub.kxmd.dev
+    # Clients use an SSH forward. https://hub.kxmd.dev is an Authentik login page.
+    url: http://127.0.0.1:17331
     project: prj_example
     key:
       op: op://Private/kxmd/project-token

package/docs/start/install.md

@@ -8,7 +8,7 @@ KXM has three parts you can install: the `kxm` command-line tool, the Claude Cod
 - Git.
 - Claude Code, if you want the plugin.
 - Pi, if you want Pi agents. Install it with `npm install --global @earendil-works/pi-coding-agent` and sign in to a model provider as the [Pi documentation](https://pi.dev/docs/latest) describes.
-- The GitHub CLI (`gh`), only if you plan to update with `kxm update --kxm`, which downloads the release tarball from GitHub.
+- The GitHub CLI (`gh`), only if you plan to update with `kxm update --kxm` from the GitHub source. When `gh` is missing, that command falls back to curl and still checks the release checksum. The manual curl commands are in [Upgrade KXM](../operations/upgrade.md#update-the-cli-without-gh).
 
 ## Choose what to install
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.167",
+  "version": "0.7.169",
   "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.167",
+  "version": "0.7.169",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",