@kontextmind/kxm 0.7.18 → 0.7.20

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

package/docs/configuration.md

@@ -85,6 +85,22 @@ later restarts. Delete the file and restart to rotate the generated token.
 
 Project tokens are an authorization boundary. A project-specific token can register only in its mapped project and see only that project's agents and messages. The administrative token remains a fallback for projects without an explicit entry. For provenance-gated workflows, configure an explicit project token and give workers only that token; reserve a distinct administrative token for operations such as quorum degradation approval.
 
+### Hub auto-start (Pi extension)
+
+`hub.autoStart` in `kxm.config.v1` controls whether harness extensions start
+the hub themselves; the default is `background`. On every extension load, the
+Pi TUI first reuses a healthy bound hub (`kxm hub bind`), then a live local
+`hub.pid` claim, then a hub already answering on the configured
+`KXM_SERVER_URL` (for example one launched directly by a harness), and only
+starts a detached `kxm-hub.mjs` wrapper when none of them exists, logging
+wrapper output to `.kxm/logs/hub-autostart.log`. Set
+`hub.autoStart: off` to never start a hub from an extension. Auto-start
+resolves credentials before launch, so a first run generates the admin token
+and persists it under the user state root exactly as `kxm hub start` does;
+the extension then authenticates with the environment token, the auto-start
+token, or the persisted credential, in that order. A failed start notifies in
+the TUI and never blocks the session.
+
 PowerShell example:
 
 ```powershell
@@ -102,7 +118,7 @@ The four derived directories stay together when only `KXM_WORKSPACE_DIR` is set.
 |---|---|---|
 | `KXM_SERVER_URL` | `http://127.0.0.1:7331` | Hub base URL |
 | `KXM_AUTH_TOKEN` | None | Project token, or the shared administrative token |
-| `KXM_PROJECT` | Current directory name | Discovery and message namespace |
+| `KXM_PROJECT` | package.json `name`, else current directory name | Discovery and message namespace |
 | `KXM_AGENT_NAME` | Harness-derived name | Unique live identity within a project |
 | `KXM_AGENT_PURPOSE` | Harness default | Capability description shown to peers |
 

package/docs/getting-started.md

@@ -84,7 +84,10 @@ research — verify them before dispatch. Declining is safe: set
 
 ## 3. Start the hub in another terminal
 
-`kxm hub start` is foreground. Keep that terminal running.
+`kxm hub start` is foreground. Keep that terminal running. The Pi extension
+can also start the hub for you (`hub.autoStart: background`, the default in
+`kxm.config.v1`): on load it reuses a healthy bound hub or a live local claim
+and starts a detached wrapper only when none exists.
 
 PowerShell:
 

package/docs/kxm-handbook.md

@@ -157,7 +157,11 @@ kxm init
 
 ### 2. Start the hub in another terminal
 
-`kxm hub start` is foreground. Keep that terminal running. Use a high-entropy
+`kxm hub start` is foreground. Keep that terminal running. (The Pi extension
+also starts the hub by default — `hub.autoStart: background` in
+`kxm.config.v1` — reusing a healthy bound hub or a live local claim and
+spawning a detached wrapper only when none exists; set `hub.autoStart: off`
+to disable. See Configuration.) Use a high-entropy
 administrative token for hub operations and a different project token for
 agents. Never pass either token on a command line.
 
@@ -314,7 +318,7 @@ network controls before allowing remote access.
 |---|---:|---|
 | `KXM_SERVER_URL` | `http://127.0.0.1:7331` | Hub URL |
 | `KXM_AUTH_TOKEN` | none | Project token for agents |
-| `KXM_PROJECT` | current directory name | Discovery/authentication namespace |
+| `KXM_PROJECT` | package.json `name`, else current directory name | Discovery/authentication namespace |
 | `KXM_AGENT_NAME` | harness-derived | Unique live name in the project |
 | `KXM_AGENT_PURPOSE` | general-purpose | Capability shown during peer discovery |
 

package/docs/troubleshooting.md

@@ -34,6 +34,10 @@ Version 0.4.3 prevents a second wrapper from replacing a live hub or worker clai
 
 The hub does not poll GitHub. Run `kxm gate github watch` with the same `runId`, `stageId`, and `signalKey`. A watcher timeout posts the exact signed `failed` signal, retains bounded check evidence, and exits `4`; it never invents `passed`.
 
+### CI jobs stay queued and never start
+
+Every CI job in `.github/workflows/ci.yml` runs on the `kontextmind-doks` label. If all jobs sit in `queued` with an online, idle runner, the runner lost that custom label (for example after re-registration — the default labels are only `self-hosted`, `Linux`/`Windows`, `X64`). Confirm with `gh api repos/kontextmind/kxm/actions/runners --jq '.runners[] | {name, labels: [.labels[].name]}'`; jobs cannot match on the default `doks` label alone. Re-add the label with `gh api repos/kontextmind/kxm/actions/runners/<id>/labels -X POST --input - <<< '{"labels":["kontextmind-doks"]}'` and jobs are picked up on the next evaluation; if not, push an empty commit to retrigger the run. The Windows runner (`kxm-win-local`) is paused by policy and must not be re-labeled to satisfy Linux jobs.
+
 ### The hub refuses to start
 
 **`KXM_PORT must be an integer between 0 and 65535`**

package/package.json

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