@kontextmind/kxm 0.7.164 → 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.164",
+      "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

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.164",
+  "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.164",
+  "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.
 

package/plugins/kxm/dist/claude-hook.js

@@ -568,6 +568,47 @@ function validateHubUrl(raw) {
   }
   return parsed.href.replace(/\/$/, "");
 }
+function splitTokenCommand(raw) {
+  if (/[|&;<>$`\n\r]/.test(raw)) {
+    throw new CloudTokenError(
+      "cloud_token_command_invalid",
+      "token command must be a program and arguments, not a shell pipeline"
+    );
+  }
+  const args = [];
+  let current = "";
+  let quote;
+  for (const ch of raw) {
+    if (quote) {
+      if (ch === quote) quote = void 0;
+      else current += ch;
+      continue;
+    }
+    if (ch === "'" || ch === '"') {
+      quote = ch;
+      continue;
+    }
+    if (ch === " " || ch === "	") {
+      if (current.length > 0) {
+        args.push(current);
+        current = "";
+      }
+      continue;
+    }
+    current += ch;
+  }
+  if (quote) {
+    throw new CloudTokenError("cloud_token_command_invalid", "token command has an unclosed quote");
+  }
+  if (current.length > 0) args.push(current);
+  if (args.length === 0) {
+    throw new CloudTokenError("cloud_token_command_invalid", "token command is empty");
+  }
+  return args;
+}
+function isCloudTokenEnvName(value) {
+  return TOKEN_ENV_NAME.test(value);
+}
 function isIsoTimestamp(value) {
   if (Number.isNaN(Date.parse(value))) return false;
   return value === new Date(value).toISOString();
@@ -591,7 +632,9 @@ function readHubBinding(env = process.env) {
   }
   const row = parsed;
   const keys = Object.keys(row);
-  if (keys.length !== 3 || row.schema !== HUB_BINDING_SCHEMA || typeof row.url !== "string" || typeof row.boundAt !== "string" || !isIsoTimestamp(row.boundAt)) {
+  const allowed = /* @__PURE__ */ new Set(["schema", "url", "boundAt", "cloud", "tokenEnv", "tokenCommand"]);
+  const cloudish = keys.some((key) => key === "cloud" || key === "tokenEnv" || key === "tokenCommand");
+  if (keys.some((key) => !allowed.has(key)) || !cloudish && keys.length !== 3 || row.schema !== HUB_BINDING_SCHEMA || typeof row.url !== "string" || typeof row.boundAt !== "string" || !isIsoTimestamp(row.boundAt)) {
     throw new HubBindingError(`malformed hub binding at ${file}`);
   }
   let url;
@@ -600,7 +643,34 @@ function readHubBinding(env = process.env) {
   } catch {
     throw new HubBindingError(`malformed hub binding at ${file}`);
   }
-  return { schema: HUB_BINDING_SCHEMA, url, boundAt: row.boundAt };
+  if (!cloudish) return { schema: HUB_BINDING_SCHEMA, url, boundAt: row.boundAt };
+  if (row.cloud !== true) throw new HubBindingError(`malformed hub binding at ${file}`);
+  let tokenEnv;
+  let tokenCommand;
+  if (row.tokenEnv !== void 0) {
+    if (typeof row.tokenEnv !== "string" || !isCloudTokenEnvName(row.tokenEnv)) {
+      throw new HubBindingError(`malformed hub binding at ${file}`);
+    }
+    tokenEnv = row.tokenEnv;
+  }
+  if (row.tokenCommand !== void 0) {
+    if (typeof row.tokenCommand !== "string") throw new HubBindingError(`malformed hub binding at ${file}`);
+    try {
+      splitTokenCommand(row.tokenCommand);
+    } catch {
+      throw new HubBindingError(`malformed hub binding at ${file}`);
+    }
+    tokenCommand = row.tokenCommand;
+  }
+  if (!tokenEnv && !tokenCommand) throw new HubBindingError(`malformed hub binding at ${file}`);
+  return {
+    schema: HUB_BINDING_SCHEMA,
+    url,
+    boundAt: row.boundAt,
+    cloud: true,
+    ...tokenEnv ? { tokenEnv } : {},
+    ...tokenCommand ? { tokenCommand } : {}
+  };
 }
 async function probeHubHealth(url, fetchImpl, timeoutMs = HUB_HEALTH_PROBE_MS) {
   const started = Date.now();
@@ -625,12 +695,21 @@ async function probeHubHealth(url, fetchImpl, timeoutMs = HUB_HEALTH_PROBE_MS) {
     clearTimeout(timer);
   }
 }
-var HUB_BINDING_SCHEMA, HUB_HEALTH_PROBE_MS, HubBindingError;
+var HUB_BINDING_SCHEMA, HUB_HEALTH_PROBE_MS, CloudTokenError, TOKEN_ENV_NAME, HubBindingError;
 var init_hub_binding = __esm({
   "plugins/kxm/src/hub-binding.ts"() {
     "use strict";
     HUB_BINDING_SCHEMA = "kxm.hub-binding.v1";
     HUB_HEALTH_PROBE_MS = 300;
+    CloudTokenError = class extends Error {
+      code;
+      constructor(code, message) {
+        super(message);
+        this.name = "CloudTokenError";
+        this.code = code;
+      }
+    };
+    TOKEN_ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
     HubBindingError = class extends Error {
       constructor(message) {
         super(message);
@@ -8770,11 +8849,15 @@ var project_name_exports = {};
 __export(project_name_exports, {
   defaultProjectName: () => defaultProjectName
 });
-import { readFileSync as readFileSync7 } from "node:fs";
-import { basename as basename2, join as join6 } from "node:path";
-function defaultProjectName(cwd, env = process.env) {
+import { existsSync as existsSync7, readFileSync as readFileSync7 } from "node:fs";
+import { basename as basename2, dirname as dirname3, join as join6, resolve as resolve5 } from "node:path";
+function defaultProjectName(cwd, env = process.env, explicit) {
+  const fromExplicit = explicit?.trim();
+  if (fromExplicit) return fromExplicit;
   const fromEnv = env.KXM_PROJECT?.trim();
   if (fromEnv) return fromEnv;
+  const fromProject = readProjectYamlId(cwd);
+  if (fromProject) return fromProject;
   try {
     const pkg = JSON.parse(readFileSync7(join6(cwd, "package.json"), "utf8"));
     if (typeof pkg.name === "string" && pkg.name.trim().length > 0) return pkg.name.trim();
@@ -8782,9 +8865,30 @@ function defaultProjectName(cwd, env = process.env) {
   }
   return basename2(cwd);
 }
+function readProjectYamlId(start) {
+  let dir = resolve5(start);
+  for (; ; ) {
+    const file = join6(dir, ".kxm", "project.yaml");
+    if (existsSync7(file)) {
+      try {
+        const doc = (0, import_yaml2.parse)(readFileSync7(file, "utf8"));
+        if (doc && typeof doc === "object" && !Array.isArray(doc) && typeof doc.id === "string" && doc.id.trim()) {
+          return doc.id.trim();
+        }
+      } catch {
+      }
+      return void 0;
+    }
+    const parent = dirname3(dir);
+    if (parent === dir) return void 0;
+    dir = parent;
+  }
+}
+var import_yaml2;
 var init_project_name = __esm({
   "plugins/kxm/src/project-name.ts"() {
     "use strict";
+    import_yaml2 = __toESM(require_dist(), 1);
   }
 });
 
@@ -8930,9 +9034,9 @@ __export(commands_exports, {
   timingSafeStringCompare: () => timingSafeStringCompare
 });
 import { createHash, randomUUID as randomUUID3, timingSafeEqual } from "node:crypto";
-import { chmodSync, existsSync as existsSync7, mkdirSync as mkdirSync6, readFileSync as readFileSync8, unlinkSync, writeFileSync as writeFileSync5 } from "node:fs";
+import { chmodSync, existsSync as existsSync8, mkdirSync as mkdirSync6, readFileSync as readFileSync8, unlinkSync, writeFileSync as writeFileSync5 } from "node:fs";
 import { homedir as homedir3 } from "node:os";
-import { dirname as dirname3, join as join7, resolve as resolve5 } from "node:path";
+import { dirname as dirname4, join as join7, resolve as resolve6 } from "node:path";
 function forwardedHops(handling) {
   if (!handling?.length) return void 0;
   return {
@@ -9114,15 +9218,15 @@ function parseSessionToken(token) {
   return void 0;
 }
 function resolveUserConfigDirectory(overrideDir) {
-  if (overrideDir) return resolve5(overrideDir);
-  return resolve5(process.env.KXM_USER_CONFIG_DIR?.trim() || join7(homedir3(), ".config", "kxm"));
+  if (overrideDir) return resolve6(overrideDir);
+  return resolve6(process.env.KXM_USER_CONFIG_DIR?.trim() || join7(homedir3(), ".config", "kxm"));
 }
 function sessionTokenPath(userConfigDir) {
   return join7(resolveUserConfigDirectory(userConfigDir), "session.token");
 }
 function persistSessionTokenToDisk(token, options) {
   const filePath = sessionTokenPath(options?.userConfigDir);
-  const dir = dirname3(filePath);
+  const dir = dirname4(filePath);
   mkdirSync6(dir, { recursive: true, mode: 448 });
   const mode = options?.mode ?? 384;
   writeFileSync5(filePath, `${token.trim()}
@@ -9135,7 +9239,7 @@ function persistSessionTokenToDisk(token, options) {
 }
 function readSessionTokenFromDisk(options) {
   const filePath = sessionTokenPath(options?.userConfigDir);
-  if (!existsSync7(filePath)) return void 0;
+  if (!existsSync8(filePath)) return void 0;
   try {
     const token = readFileSync8(filePath, "utf8").trim();
     if (!token) return void 0;
@@ -9148,7 +9252,7 @@ function readSessionTokenFromDisk(options) {
 }
 function clearSessionTokenFromDisk(options) {
   const filePath = sessionTokenPath(options?.userConfigDir);
-  if (!existsSync7(filePath)) return false;
+  if (!existsSync8(filePath)) return false;
   try {
     unlinkSync(filePath);
     return true;
@@ -9247,7 +9351,7 @@ function enforceToolPolicy(commandName, env = process.env, options) {
     return { allowed: true };
   }
   const tokenFile = sessionTokenPath(env.KXM_USER_CONFIG_DIR);
-  if (existsSync7(tokenFile)) {
+  if (existsSync8(tokenFile)) {
     let tokenRaw;
     try {
       tokenRaw = readFileSync8(tokenFile, "utf8").trim();
@@ -9937,7 +10041,7 @@ var init_commands = __esm({
 
 // plugins/kxm/src/claude-hook.ts
 import { readFileSync as readFileSync9, statSync } from "node:fs";
-import { join as join8, resolve as resolve6 } from "node:path";
+import { join as join8, resolve as resolve7 } from "node:path";
 
 // plugins/kxm/src/session-token-hint.ts
 var ENV_TEXT = "KXM_SESSION_TOKEN in the environment Claude Code was launched from is malformed or expired, so every kxm_* tool fails with tool_policy_denied. Ask the user to unset or replace KXM_SESSION_TOKEN in the environment Claude Code was launched from, then restart Claude Code.";
@@ -10010,7 +10114,7 @@ function truncate2(text, max) {
 }
 async function sessionStartContext(input, env) {
   const inputCwd = typeof input.cwd === "string" ? input.cwd.trim() : "";
-  const root = resolve6(env.CLAUDE_PROJECT_DIR?.trim() || inputCwd || process.cwd());
+  const root = resolve7(env.CLAUDE_PROJECT_DIR?.trim() || inputCwd || process.cwd());
   if (!isDirectory(join8(root, ".kxm"))) return void 0;
   const [
     { resolveSessionHubStatus: resolveSessionHubStatus2 },