@kontextmind/kxm 0.7.195 → 0.7.196

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "kxm",
       "source": "./plugins/kxm",
       "description": "Durable workflows, peer agents, and kxm tui",
-      "version": "0.7.195",
+      "version": "0.7.196",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/CHANGELOG.md

@@ -714,6 +714,13 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Fixed
 
+- **A first run says what to do next when Git or the hub is missing.**
+  `kxm init` outside a Git worktree still exits 1 with `git_root_required` and
+  now says to run `git init`, then `kxm init` again. `kxm hub view` adds
+  `hint` when both probes are unreachable or time out: on loopback, start a
+  hub with `kxm hub start`; on a remote URL, check the address and
+  `kxm hub bind`.
+
 - **`kxm vision assert --route` selects the Pi model, and an unadmitted route names the fix.**
   The flag used to change only the admission check. Pi still ran
   `zai-coding-cn/glm-5.3-flash`. Another admitted id is now `pi --model <id>`
@@ -721,7 +728,6 @@ All notable user-facing changes are documented here. The project follows [Semant
   `route_not_admitted` includes the route id and `kxm routes admit --model`.
   This checkout does not admit the default; pass
   `--route openrouter/z-ai/glm-5.3-flash`.
-
 - **The weekly model refresh opens its pull request with a GitHub App.**
   `.github/workflows/refresh-models.yml` uses `actions/create-github-app-token`
   with repository secrets `KXM_REFRESH_APP_ID` and

package/docs/operations/troubleshooting.md

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

package/docs/reference/cli-reference.md

@@ -511,7 +511,7 @@ Calls `GET /health` and `GET /ready` on the target hub and reports whether the U
 No command-specific options.
 
 - Needs a hub to succeed. Reads only.
-- JSON keys: `target` (`url`, `scope`, and `source: "env"` when `KXM_SERVER_URL` overrides a binding), `identity` (`mode`, `modeSource`, `url`, `urlSource`, `project`, `projectSource`, `keySource`), `health`, `ready`. An unreachable hub reports `{"error":"hub_unreachable"}` for both probes. An auth proxy or redirect reports `{"error":"auth_proxy"}`.
+- JSON keys: `target` (`url`, `scope`, and `source: "env"` when `KXM_SERVER_URL` overrides a binding), `identity` (`mode`, `modeSource`, `url`, `urlSource`, `project`, `projectSource`, `keySource`), `health`, `ready`, and `hint` when both probes are unreachable or time out. An unreachable hub reports `{"error":"hub_unreachable"}` for both probes. On a loopback URL the hint is `Nothing is listening on this loopback URL. Start a local hub with kxm hub start.` A remote URL names `kxm hub bind`. An auth proxy or redirect reports `{"error":"auth_proxy"}` and has no hint.
 - Exit 0 when both probes succeed, 1 otherwise. A cloud mode with no resolvable key exits 2 with `cloud_token_missing`.
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.195",
+  "version": "0.7.196",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",

package/plugins/kxm/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "kxm",
   "displayName": "KXM",
-  "version": "0.7.195",
+  "version": "0.7.196",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",

package/plugins/kxm/dist/cli.js

@@ -30893,7 +30893,7 @@ function initializeKxmProjectAtGitRoot(start, gitRoot, options, mutationLock) {
     };
   }
   if (plan.projectRoot !== gitRoot) {
-    throw new KxmConfigError([initIssue("git_root_required", ".", "kxm init must run inside the authoritative Git worktree")]);
+    throw new KxmConfigError([initIssue("git_root_required", ".", "kxm init must run from the Git worktree root")]);
   }
   const projectId = generatedProjectId(options.projectId);
   const projectName = normalizedProjectName(gitRoot, options.projectName);
@@ -30918,7 +30918,7 @@ function initializeKxmProject(start = process.cwd(), options = {}) {
   assertNoRegisteredGates(options);
   const gitRoot = discoverGitRoot(start);
   if (!gitRoot) {
-    throw new KxmConfigError([initIssue("git_root_required", ".", "kxm init must run inside the authoritative Git worktree")]);
+    throw new KxmConfigError([initIssue("git_root_required", ".", "kxm init must run inside a Git worktree. Run git init in this directory, then run kxm init again.")]);
   }
   if (options.projectId !== void 0) generatedProjectId(options.projectId);
   if (options.projectName !== void 0) normalizedProjectName(gitRoot, options.projectName);
@@ -53997,6 +53997,8 @@ async function cmdStatus(runtime) {
   const notHub = !proxyKind && (health.kind === "not_hub" || ready.kind === "not_hub");
   const probeNote = proxyKind === "redirect" ? " \xB7 auth proxy or redirect" : proxyKind === "auth_proxy" ? " \xB7 auth proxy (HTML login page)" : notHub ? " \xB7 not a kxm hub" : "";
   const effectiveScope = connection.scope;
+  const hubDown = (health.kind === "unreachable" || health.kind === "timeout") && (ready.kind === "unreachable" || ready.kind === "timeout");
+  const hint = !hubDown ? void 0 : effectiveScope === "loopback" ? "Nothing is listening on this loopback URL. Start a local hub with kxm hub start." : "Nothing answered this hub URL. Check the address, the tunnel, and kxm hub bind.";
   const overridden = connection.urlSource === "env";
   const identity = {
     mode: connection.mode,
@@ -54013,13 +54015,15 @@ async function cmdStatus(runtime) {
     target: { url: runtime.serverUrl, scope: effectiveScope, ...overridden ? { source: "env" } : {} },
     identity,
     health: health.body,
-    ready: ready.body
+    ready: ready.body,
+    ...hint ? { hint } : {}
   };
   print(
     runtime.io,
     runtime.json,
     payload,
-    `hub health=${health.ok} ready=${ready.ok} \xB7 ${effectiveScope} hub${overridden ? " (KXM_SERVER_URL)" : ""} \xB7 mode=${identity.mode} project=${identity.project} (${connection.sourceLabel}) key=${identity.keySource}${probeNote}`
+    `hub health=${health.ok} ready=${ready.ok} \xB7 ${effectiveScope} hub${overridden ? " (KXM_SERVER_URL)" : ""} \xB7 mode=${identity.mode} project=${identity.project} (${connection.sourceLabel}) key=${identity.keySource}${probeNote}${hint ? `
+${hint}` : ""}`
   );
   return payload.ok ? 0 : 1;
 }

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

@@ -25462,7 +25462,7 @@ function sessionTokenFixHint(policy) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.195";
+var VERSION = "0.7.196";
 var CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.195",
+  "version": "0.7.196",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/src/cli/hub.ts

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

package/plugins/kxm/src/init.ts

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

package/plugins/kxm/src/mcp-server.ts

@@ -11,7 +11,7 @@ import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 import { sessionTokenFixHint } from "./session-token-hint.ts";
 
-const VERSION = "0.7.195";
+const VERSION = "0.7.196";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();