@kontextmind/kxm 0.7.180 → 0.7.182

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

package/CHANGELOG.md

@@ -6,6 +6,20 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Added
 
+- **The witnessed MG1 Python control-plane foundation is now reproducible from this repository.**
+  `python/kxm-control` provides the pinned Python 3.13 uv workspace, fixed
+  `kxmd` Postgres/Temporal caller, Authentik user and runner verification
+  that requires token expiry, tenant/project/repository registration,
+  owner/admin tenant rename, revision and artifact APIs, and a probe entry
+  point. OpenAPI and the Studio path inventory are derived from the FastAPI
+  app. The checked generator emits the revision helper. Studio exposes the
+  bounded `/api/control/account` relay with a three-second bound and explicit
+  failure states. Removing registration leaves source state untouched and
+  later registry calls return `registration_unavailable` until the schema is
+  installed again. The package does not change host or guest installs. The
+  required CI aggregate runs the Python contracts against PostgreSQL 17. This
+  does not move the hub or Runtime from their existing Node and SQLite owners.
+
 - **KXM configuration now has one owner-validated terminal editor.**
   `kxm config edit --scope project|user` and OMP/Pi `/kxm config` publish the
   same `kxm.config.v1` surface. Accepted writes are saved and re-read; rejected
@@ -651,6 +665,15 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Fixed
 
+- **`kxm improve report` and `kxm routing report` include attempts settled in a registered lane.**
+  Inside a KXM project, a present user-state `registry.db` is opened read-only at schema version 2. One query loads the home row and every lane row for that project id. Event-store paths come from the stored project keys, so a stale checkout path cannot hide a lane. A missing store stays a zero-record source. An absent registry, or a checkout that is not registered, still reads only that checkout's own store. `--file` still reads only the named file. See
+  [kxm improve report](docs/reference/cli-reference.md#kxm-improve-report).
+
+- **Browser integration tests isolate the Steel credential environment.**
+  Each test restores the operator's variables afterward, so ambient Authentik
+  credentials cannot override a case that deliberately exercises the legacy
+  API-key path.
+
 - **`kxm supervise` keeps supervisor state across a restart.**
   `status`, `record`, and `tick` store in-flight lanes, the last-seen pull
   request and CI state, and backoff timers in `.kxm/state/supervisor.json`.

package/docs/architecture/authentication.md

@@ -1,7 +1,7 @@
 # Authentication
 
-Read from `plugins/kxm/src/harness.ts` and `plugins/kxm/src/cli.ts`.
-
+Read from `plugins/kxm/src/harness.ts`, `plugins/kxm/src/cli.ts`, and
+`python/kxm-control/src/kxm_control/auth.py`.
 `kxm harness list` runs `probeHarnesses` (`cmdHarnessList` in
 `plugins/kxm/src/cli/project.ts`). For each detected harness that has
 `authArgs`, `probeEntry` runs that command and `interpretAuth` reads the
@@ -23,6 +23,15 @@ the harness command's own stdout.
 issues, or clears the local session token file. That token is a KXM session
 token, not a provider key. Provider logins stay in each harness.
 
+The MG1 Python control API uses a separate Authentik boundary. It accepts only
+RS256 tokens whose issuer and audience match its configured values, whose
+`exp` is present and unexpired, and whose `kxm_actor` is `user` or `runner`.
+A token without `exp` is rejected.
+The signed subject and actor kind must match
+an explicit tenant membership; a user membership never authorizes a runner
+token with the same subject. Only a user can create a tenant. The API does not
+store the bearer token.
+
 ## Related
 
 - [Access](access.md)

package/docs/architecture/hosted-direction.md

@@ -52,11 +52,13 @@ roadmap question. The tracker wins.
 proposal is not in this repository. Its delivery position is unchanged:
 none of the delivery is scheduled there.
 
-The tracker names that file. The sentences that can be repeated without a
-hostname, an account name, or a secret are: a first move is recorded as
-installed, Postgres and Temporal are described as loopback only, KXM does not
-write those stores, Redis Streams, NATS, raw WebSockets, and the A2A Python
-SDK stay backlog, there is no S3, and the SQLite write path is unchanged.
+Today the Node hub and Runtime still write local SQLite and local files. The
+checked-in MG1 Python control API is the narrow exception: it owns only central
+registration and bounded tenant artifacts in the fixed `kxmd` PostgreSQL
+account. Temporal is provisioned for `kxmd`, but no production workflow cutover
+is selected. Redis Streams, NATS, raw WebSockets, the A2A Python SDK, and S3
+remain backlog. The rest of this page remains a target, not a live deployment
+description.
 
 ## Related
 

package/docs/architecture/inventory.md

@@ -6,7 +6,8 @@ Read from `plugins/kxm/src/cli.ts`, `plugins/kxm/src/config-editor.ts`,
 `plugins/kxm/src/runtime-paths.ts`, `plugins/kxm/src/mcp-server.ts`,
 `plugins/kxm/src/oneshot-producer.ts`, `plugins/kxm/src/studio-layout.ts`,
 `plugins/kxm/src/cli/types.ts` (`workspaceDirs`),
-`plugins/kxm/src/local-snapshot.ts`, and `scripts/kxm-worker.mjs`.
+`plugins/kxm/src/local-snapshot.ts`, `scripts/kxm-worker.mjs`, and
+`python/kxm-control/src/kxm_control/{api,registry}.py`.
 
 | Surface | Started by | Listener or path | Store it owns | Defining file |
 | --- | --- | --- | --- | --- |
@@ -17,11 +18,12 @@ Read from `plugins/kxm/src/cli.ts`, `plugins/kxm/src/config-editor.ts`,
 | Hub cloud binding | `kxm hub bind <url> --cloud --token-env/--token-command` | no listener; writes the binding record and never stores the token | binding record; token stays in the named env or command | `plugins/kxm/src/cli/hub.ts` |
 | Runtime supervisor | `kxm runtime` / `scripts/kxm-runtime-supervisor.mjs` | `127.0.0.1` and the requested port, or ephemeral | registry and event stores below | `plugins/kxm/src/runtime-supervisor.ts` |
 | Runtime registry | opened by the supervisor | `runtime/registry.db` under the user state root | `registry.db`. A lane worktree registers under its project: same project id, its own control root, `lane_of` set. A registering root is the primary worktree when its git common dir is `<root>/.git`; if that primary registers while the live home row is not primary, the primary becomes the home row and every other live row of that repository becomes its lane. | `plugins/kxm/src/runtime-paths.ts` |
-| Runtime event store | opened by the supervisor | `runtime/projects/<key>/run-events.db` | `run-events.db` | `plugins/kxm/src/runtime-paths.ts` |
+| Runtime event store | opened by the supervisor | `runtime/projects/<key>/run-events.db` | `run-events.db`. `kxm improve report` and `kxm routing report` read the home store and every lane store for the registered project id through one read-only query of `registry.db` (`plugins/kxm/src/improve-sources.ts`). An absent registry, or a checkout that is not registered, reads only that checkout's own store. Paths come from the stored project keys. | `plugins/kxm/src/runtime-paths.ts` |
 | MCP server | Claude plugin or stdio launch | stdio | none | `plugins/kxm/src/mcp-server.ts` |
 | One-shot harness | supervisor producer | child process, no listener | none | `plugins/kxm/src/oneshot-producer.ts` |
 | Pi worker | `kxm agent worker` | no HTTP listener in `scripts/kxm-worker.mjs` | none of its own | `scripts/kxm-worker.mjs` |
-| Studio | `kxm studio serve` | `127.0.0.1:4242` | none | `plugins/kxm/src/studio-layout.ts` |
+| Studio | `kxm studio serve` | `127.0.0.1:4242` | none; `/api/control/account` is a bounded relay to the configured control API | `plugins/kxm/src/studio-layout.ts` |
+| Python control API | ASGI server loading `kxm_control.api:app` | deployment-selected; the package declares no network default | `kxm_registry` in the fixed `kxmd` PostgreSQL database and the configured tenant artifact root | `python/kxm-control/src/kxm_control/api.py` |
 | Workspace config | `workspaceDirs` | `.kxm/config`, or `KXM_CONFIG_DIR` | files in that directory | `plugins/kxm/src/cli/types.ts` |
 | Workspace logs | `workspaceDirs` | `.kxm/logs`, or `KXM_LOGS_DIR` | log files | `plugins/kxm/src/cli/types.ts` |
 | Workspace assets | `workspaceDirs` | `.kxm/assets`, or `KXM_ASSETS_DIR` | asset files | `plugins/kxm/src/cli/types.ts` |

package/docs/architecture/platform.md

@@ -2,7 +2,8 @@
 
 Read from `plugins/kxm/src/cli.ts`, `plugins/kxm/src/runtime-supervisor.ts`,
 `scripts/kxm-hub.mjs`, `plugins/kxm/src/hub.ts`, `plugins/kxm/src/mcp-server.ts`,
-and `plugins/kxm/src/oneshot-producer.ts`.
+`plugins/kxm/src/oneshot-producer.ts`, and
+`python/kxm-control/src/kxm_control/api.py`.
 
 KXM on this checkout is local-first. The `kxm` CLI is the operator entry
 (`plugins/kxm/src/cli.ts`, launched through `scripts/kxm.mjs`). The hub is an
@@ -18,17 +19,29 @@ requested. The MCP server (`plugins/kxm/src/mcp-server.ts`) uses
 spawned by the producer registered in `plugins/kxm/src/oneshot-producer.ts`.
 That child process is not a listener.
 
+The checked-in MG1 Python control API is additive. It owns central registration
+and bounded tenant artifacts through the fixed `kxmd` account. Only an owner
+or admin membership can rename a tenant. Removing the registration schema
+leaves source state in place, and later registry routes return
+`registration_unavailable` until the schema is installed again. The API does
+not install or change host or guest software. It does not replace the Node
+hub, Runtime, CLI, or their SQLite stores. Studio can relay
+`GET /api/control/account` to this service when `KXM_CONTROL_URL` is configured.
+
 ```mermaid
 flowchart LR
   cli["kxm CLI"]
-  hub["hub"]
-  sup["Runtime supervisor"]
+  hub["Node hub"]
+  sup["Node Runtime supervisor"]
   mcp["MCP server"]
   shot["one-shot harness"]
+  studio["Studio"]
+  control["MG1 Python control API"]
   cli -->|"kxm hub start"| hub
   mcp -->|"HTTP to hub"| hub
   cli -->|"kxm run"| sup
   sup -->|"spawn producer"| shot
+  studio -->|"bounded account read"| control
 ```
 
 ## Listeners
@@ -39,7 +52,8 @@ flowchart LR
 | Supervisor HTTP | `127.0.0.1` and an ephemeral port when the requested port is `0` |
 | MCP | stdio, no TCP port |
 | CLI and one-shot harness | no listener |
-| Studio, when served | `127.0.0.1:4242` from `createStudioServer` in `plugins/kxm/src/studio-layout.ts` |
+| Studio, when served | `127.0.0.1:4242` from `createStudioServer` in `plugins/kxm/src/studio-layout.ts`; its optional control relay targets `KXM_CONTROL_URL` |
+| Python control API | ASGI listener selected by deployment; the package declares no host or port default |
 | Antigravity OAuth callback | loopback port `51121` only during login (`plugins/kxm/src/providers/antigravity/auth/oauth.ts`) |
 
 ## Related

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

@@ -1,7 +1,8 @@
 # CI and release
 
-Pull requests run lint, typecheck, and the unit suite on Linux Node 24.
-Pushes to `main` also run that suite and the full OS × Node matrix.
+Pull requests run lint, typecheck, the Node unit suite on Linux Node 24, and
+the Python control-plane suite against PostgreSQL 17. Pushes to `main` also run
+the Node suite and the full OS × Node matrix.
 The complete suite with coverage floors runs nightly, every merge to `main`
 cuts a patch release, and every release is verified before it reaches npm.
 This page explains which checks run where, how a merge becomes a published
@@ -15,7 +16,7 @@ release and an npm publish; the nightly job adds the slower suites.
 
 ```mermaid
 flowchart LR
-  PR[Pull request] -->|"unit shards, docs lint, plugin validation"| REQ["CI / required"]
+  PR[Pull request] -->|"Node shards, Python/Postgres, docs lint, plugin validation"| REQ["CI / required"]
   REQ --> MERGE{Merged?}
   MERGE -->|yes| MAIN[main]
   MAIN -->|"unit shards plus validate:pr matrix"| PUSH[Push CI]
@@ -40,6 +41,7 @@ together.
 | Pull request, push to `main`, or manual | `ci.yml` (`required`) | Aggregates the lanes below into one pass/fail check named `CI / required` |
 | Pull request and push | `ci.yml` (Docs lint) | `lint:docs` and `check:versions`, always |
 | Code pull request and code push | `ci.yml` (Unit engine and Unit, Linux Node 24) | `engine.test.ts` split by test name; `permission.test.ts`, `runtime.test.ts`, and `package-install.test.ts` one file at a time; every other unit file in two light shards. Typecheck and `check-generated` run on `light-1` |
+| Code pull request and code push | `ci.yml` (Python control plane) | Python 3.13 `unittest` contracts from the frozen uv workspace against PostgreSQL 17 started by `scripts/ci-postgres-17.sh` |
 | Platform-sensitive pull request | `ci.yml` (Unit, Windows Node 24) | The same unit lanes on `windows-latest` |
 | Push to `main`, or manual | `ci.yml` (Validate matrix) | `validate:pr` on Linux and Windows for Node 22.19.0 and Node 24; not on a pull request |
 | Code pull request and code push | `ci.yml` (Plugin validation) | `claude plugin validate --strict` on the marketplace and the plugin |
@@ -73,7 +75,8 @@ What moved off the pull-request lane, and what did not:
   runs `validate:pr` on Windows.
 - Coverage, `test/simulations`, and `npm pack --dry-run` stay in the nightly
   complete suite. They were not part of pull-request CI before this split.
-- Plugin validation still runs on code pull requests and code pushes.
+- Python control-plane validation and Plugin validation still run on code pull
+  requests and code pushes.
 
 Run `npm run verify` locally before every push. A nightly failure is a release
 blocker: it is the only place the simulation suite and coverage floors run.
@@ -82,8 +85,13 @@ blocker: it is the only place the simulation suite and coverage floors run.
 
 Code pull requests run Docs lint, two Linux Node 24 engine shards, a serial
 lane (`permission.test.ts`, then `runtime.test.ts`, then
-`package-install.test.ts`), two light shards for every other unit file, and
-Plugin validation. `light-1` typechecks and checks generated bundles.
+`package-install.test.ts`), two light shards for every other Node unit file,
+the Python 3.13 control-plane suite against PostgreSQL 17, and Plugin
+validation. The Python lane stays on `kontextmind-doks`. That scale set has
+no container-engine socket, so the job starts PostgreSQL 17 with
+`scripts/ci-postgres-17.sh` on `127.0.0.1:5432` and uses the same admin and
+test DSNs as the contributor procedure in [Develop KXM](development.md).
+`light-1` typechecks and checks generated bundles.
 `engine.test.ts` is split by test name because that file alone was 174
 seconds; the serial lane keeps the next longest files off the light pool,
 which was 268 seconds when every non-engine file shared one job.
@@ -165,9 +173,10 @@ workaround.
 The first job, Classify changes, lists the changed paths and sets `code=false`
 when every path matches `*.md` (including `plans/**/*.md`), `docs/**`,
 `.kxm/assets/**`, `LICENSE`, the issue and PR templates, or `dependabot.yml`.
-A non-markdown file under `plans/` is code. Unit lanes, Plugin validation,
-and the Validate matrix are skipped. Docs lint runs, and `CI / required`
-passes. `scripts/ci-classify.mjs` and `ci-contract.test.ts` pin this behavior.
+A non-markdown file under `plans/` is code. Unit lanes, the Python control-plane
+lane, Plugin validation, and the Validate matrix are skipped. Docs lint runs,
+and `CI / required` passes. `scripts/ci-classify.mjs` and
+`ci-contract.test.ts` pin this behavior.
 
 `platform=true` when a path is a package manifest, the lockfile, a file under
 `scripts/` or `.github/workflows/`, or a filename that names path, process,

package/docs/contributing/decisions.md

@@ -198,3 +198,34 @@ Evidence: Evidence: `git diff HEAD origin/main` on the stale branch showed upstr
 - Interim recommendation: use the opt-in installer until OMP exposes a
   first-class transactional status-preset API.
 Evidence: `plugins/kxm/src/cli/plugins.ts`, `plugins/kxm/src/session-work.ts`, and `test/core/cli.test.ts`.
+
+## 2026-10-11 — Bring the witnessed MG1 Python foundation onto main (migration)
+
+- Context: the tracker records MG1 as passed off-repo while the operator's
+  primary checkout holds the matching untracked Python workspace, MG0 evidence,
+  and Studio control-account proxy. Leaving the implementation outside Git
+  makes the recorded gate irreproducible and blocks MG2 from a reviewed base.
+- Options:
+  - Keep MG1 off-repo and start the roadmap's role-authority work — weight 0.2.
+    Avoids a CI change, but preserves the tracker/source contradiction and risks
+    losing the only implementation matching the deployed witness.
+  - Import MG1 at `python/kxm-control`, keep Node as the current product owner,
+    and add a required Python/PostgreSQL contract lane — weight 0.9. Makes the
+    accepted foundation reproducible without claiming a Python cutover.
+  - Replace the Node CLI and Runtime with the Python package now — weight 0.1.
+    MG2 through MG8 are still open, so this would skip import, bridge, runner,
+    parity, and retirement gates.
+- Selected: import the bounded MG1 foundation and its evidence, harden the
+  Studio proxy, and make the Python unit/contract suite part of `CI / required`.
+  SQLite and the Node Runtime remain authoritative. OpenAPI and the Studio
+  path inventory are derived from the FastAPI app; the checked generator emits
+  the revision helper. The package does not change host or guest installs.
+  After registration removal, registry routes return `registration_unavailable`
+  until the schema is installed again.
+- Solid recommendation: keep every accepted migration wave in Git with its
+  generated contracts and a required service-backed test lane.
+- Interim recommendation: if the service lane is unavailable, do not merge the
+  Python source; retain the off-repo tracker wording rather than claiming an
+  unverified gate.
+Evidence: `plans/implementation-plan.md`, `plans/plan-python-migration.md`,
+`python/kxm-control/tests/test_mg1.py`, and `.github/workflows/ci.yml`.

package/docs/contributing/development.md

@@ -23,7 +23,10 @@ extension, the Claude Code plugin, or the bundled skills.
     `kxm lane run <unit> --brief <file> --workflow implement-only`.
     The read-only critic workflows on the same command are
     `review-arch-only` and `review-cli-only`.
-  - Docker for the clean-container install smoke.
+  - Docker for the clean-container install smoke and the Python control-plane
+    contract suite.
+  - Python 3.13 and [`uv`](https://docs.astral.sh/uv/) for the Python
+    control-plane contract suite.
 
 ## Set up a checkout
 
@@ -255,6 +258,41 @@ It runs three scripts in order:
 | 2 | `npm run check` | `tsc --noEmit`, `markdownlint-cli2`, and version surfaces |
 | 3 | `npm run check:generated` | Generated artifacts are tracked and match the staged copy |
 
+Changes to the Python control plane also run its frozen-workspace contract
+suite before the npm gate. The suite drops and recreates `kxm_mg1_test`, so
+the admin DSN account needs database create and drop privilege. The `postgres`
+superuser in the container below is that account. Run PostgreSQL 17 in a
+disposable container published only on loopback `127.0.0.1:5432`, with
+`POSTGRES_PASSWORD=postgres`. Leave port `5432` on loopback free. Wait until
+`pg_isready` succeeds, export the two DSNs CI uses, run the frozen suite, and
+remove the container afterward:
+
+```bash
+docker rm -f kxm-mg1-pg >/dev/null 2>&1 || true
+docker run --detach --name kxm-mg1-pg \
+  --publish 127.0.0.1:5432:5432 \
+  --env POSTGRES_PASSWORD=postgres \
+  postgres:17
+for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30; do
+  docker exec kxm-mg1-pg pg_isready -U postgres && break
+  sleep 1
+done
+docker exec kxm-mg1-pg pg_isready -U postgres
+export KXM_MG1_ADMIN_DSN='host=127.0.0.1 port=5432 dbname=postgres user=postgres password=postgres'
+export KXM_MG1_TEST_DSN='host=127.0.0.1 port=5432 dbname=kxm_mg1_test user=postgres password=postgres'
+uv run --project python --frozen python -m unittest discover -s python/kxm-control/tests
+suite_status=$?
+docker rm -f kxm-mg1-pg
+(exit "$suite_status")
+```
+
+The required CI aggregate repeats that suite against PostgreSQL 17 with the
+same two DSNs and the same `postgres` superuser. On the `kontextmind-doks`
+runners, `scripts/ci-postgres-17.sh` starts that server on `127.0.0.1:5432`
+from a pinned PostgreSQL 17 binary. Contributors use the `postgres:17`
+container procedure above, which publishes the same port and DSNs. The suite
+remains a CI lane rather than a third root gate script.
+
 Every suite script passes `--test-force-exit`, and `scripts/run-bounded.mjs` stops the run if the suite is still going after its wall-clock limit (20 minutes, or 40 for the complete and coverage suites). The bound is that wall clock per script. A per-test timeout is not used because under `node --test` each file is itself a test, so a per-test timeout also bounds each file.
 
 Other scripts you will use:

package/docs/contributing/test-matrix.md

@@ -84,6 +84,7 @@ to run one file is in [Develop KXM](development.md#run-one-file-or-one-test).
 | Promotion needs the configured admin token with no loopback bypass; proposed items never reach a packet | `e5-memory-floor.test.ts` |
 | `kxm memory`: candidates, marker-delimited sync blocks, and one brief across CLI, Pi and the Claude hook | `e5b-harness-agnostic-memory.test.ts` |
 | `kxm improve report` reads Runtime-settled attempts, drops simulated and duplicate ones, and flags only same-ask repeats | `improve.test.ts` ("kxm improve report resolves Runtime-settled attempts from the event log and flags only same-ask cross-run repeats"), `cli.test.ts`, `cli-experience.test.ts`, `commands-policy.test.ts` |
+| A registered lane's attempt appears in `kxm improve report` and `kxm routing report` run from the primary checkout; a duplicate still drops and `--file` stays isolated | `improve.test.ts` ("kxm improve report and kxm routing report from the primary include an attempt recorded only in a registered lane") |
 | Improvement candidates exclude write steps; promotion readiness never authorizes | `improve.test.ts` |
 | Telemetry classification and JSONL recovery | `telemetry.test.ts`, `cli.test.ts` |
 
@@ -100,7 +101,7 @@ The context suites in detail:
 | `wiki.test.ts` | Wiki compilation determinism, lifecycle preservation, contradiction visibility, lint |
 | `skills.test.ts` | Skill candidate lifecycle, quarantine, immutability, CLI |
 | `routing.test.ts` | Behavioral hash, record parsing, comparisons, `kxm routing report` |
-| `improve.test.ts` | Routing-record sources, event-log outcomes, same-ask candidacy, candidate files, promotion readiness |
+| `improve.test.ts` | Routing-record sources, registered lane stores, event-log outcomes, same-ask candidacy, candidate files, promotion readiness |
 
 ## Claude Code plugin and MCP
 

package/docs/reference/cli-reference.md

@@ -3499,21 +3499,21 @@ Proposes coded-repeat candidates from this project's Runtime routing records and
 kxm improve report [--file <path>] [--out-dir <path>]
 ```
 
-Generate the improvement report and candidates from routing records. Inside a KXM project (the current directory's Git root holds `.kxm/project.yaml`) it reads the project's Runtime event store, then `telemetry.jsonl` in the workspace logs directory; `--file` reads only the named file. Routing records (`kxm.routing-record.v1` and `v2`, bare or nested under `routing`, `envelope.routing`, or a `routing.attempt.recorded` event) are grouped by workflow, step, agent role, and ask. Groups that qualify become proposed candidates, each written as a `.diff` and a `.json` file. Nothing is applied.
+Generate the improvement report and candidates from routing records. Inside a KXM project (the current directory's Git root holds `.kxm/project.yaml`) it reads that project's Runtime event stores, then `telemetry.jsonl` in the workspace logs directory; `--file` reads only the named file. Routing records (`kxm.routing-record.v1` and `v2`, bare or nested under `routing`, `envelope.routing`, or a `routing.attempt.recorded` event) are grouped by workflow, step, agent role, and ask. Groups that qualify become proposed candidates, each written as a `.diff` and a `.json` file. Nothing is applied.
 
 | Option | Argument | Default | Description |
 |---|---|---|---|
-| `--file` | `<path>` | the Runtime store, then `.kxm/logs/telemetry.jsonl` | Read only this routing-record JSONL instead of the project's Runtime store and telemetry |
+| `--file` | `<path>` | the Runtime stores, then `.kxm/logs/telemetry.jsonl` | Read only this routing-record JSONL instead of the project's Runtime stores and telemetry |
 | `--out-dir` | `<path>` | `<project>/.kxm/candidates` | Directory for candidates (default .kxm/candidates) |
 
-- The Runtime store is `<state root>/runtime/projects/<key>/run-events.db`, with the key derived from the checkout's real path, so each checkout and worktree reads only its own. It is opened read-only for one query over its events table and is never created, written, or migrated. Outside a KXM project only telemetry is read, and the text output says `Runtime store not read`.
-- A telemetry record whose `attemptId` the store already supplied is dropped (`duplicatesDropped`). Attempts from simulated drives are excluded (`excludedSimulated`). Each Runtime attempt's outcome is resolved from the event log and never written back: `accepted` when the run completed and the step was not re-entered, `reworked` when the step was entered again, `failed` when the run failed, undecided (`undecided`) when the run was cancelled or is still running.
+- Each Runtime store is `<state root>/runtime/projects/<key>/run-events.db`. When `runtime/registry.db` is absent, or this checkout's project key is not in it, the command reads only the store derived from this checkout's real path and does not create the registry. When the registry is present and this checkout is registered, it is opened read-only with no migration and no write lock, requires schema version 2, and one query returns the home row and every lane row for that project id. The home store is listed first, then lanes by registration time and key. Store paths are built from those stored keys and `runtime/projects`, not from the checkout path saved on the row, so a stale path cannot change the key. A missing store is an engine source with `exists=false` and zero records. A registry that is not a regular database file, is not schema version 2, or does not have exactly one home row and 24-character lowercase hex keys exits 1 with `improve_source_unreadable`. Each store is opened read-only for one query over its events table and is never created, written, or migrated. Outside a KXM project only telemetry is read, and the text output says `Runtime store not read`. The example below is an unregistered checkout, so it lists one engine source.
+- A telemetry record whose `attemptId` an earlier source already supplied is dropped (`duplicatesDropped`). The same drop applies between the home store and a lane store: the first source wins. Attempts from simulated drives are excluded (`excludedSimulated`). Each Runtime attempt's outcome is resolved from the event log and never written back: `accepted` when the run completed and the step was not re-entered, `reworked` when the step was entered again, `failed` when the run failed, undecided (`undecided`) when the run was cancelled or is still running.
 - A group becomes a candidate only when the same objective was decided in at least 2 runs, at least 0.75 of its decided records were accepted, and its step writes no repository. A group that passes but misses shows `no (writes-repository)` or `no (ask-not-repeated)`. `Weighted` is the recency-weighted record count (`improvement.telemetryHalfLifeDays`); it orders rows and never decides candidacy.
 - Reads `improvement.*` from the project and user configuration (see [`kxm.config.v1`](config-reference.md#personalization-settings-kxmconfigv1)) and reports each candidate's promotion readiness under `improvement.promotionPolicy`. Readiness never authorizes anything. Under `critic_quorum` every candidate reports not ready, because this command cites no critic receipts. A configuration that cannot be loaded exits 1 with `config_invalid`.
-- A Runtime store that exists but cannot be read exits 1 with `improve_source_unreadable`; `detail` names the path.
+- A Runtime store or registry that exists but cannot be read, and a registry whose identity is corrupt, exits 1 with `improve_source_unreadable`; `detail` names the path.
 - Writes candidate files under `--out-dir` (relative to the current directory) and the report at `.kxm/assets/improvements/<timestamp>.json`. Honors `--dry-run` (writes neither). No hub needed.
 - JSON keys: `path`, `events`, `recordsCount`, `groupsCount`, `candidatesCount`, `candidates`, `report` (`schema`, `createdAt`, `reviewDecision`, `recordsCount`, `groups`, `candidates`, `promotionPolicy`, `promotion`, and `routeSwitches` when the store recorded any), `sources`, `projectRoot` (`null` outside a project). `routeSwitches` lists opted-in mid-attempt walks (`from`, `to`, `reason`, optional `effort`, `attemptId`, `stepId`). It is omitted when there are none.
-- Each `sources` entry has `kind` (`engine`, `telemetry`, or `file`), `path`, `exists`, `records`, and `duplicatesDropped`; the `engine` entry also has `skippedInvalid`, `excludedSimulated`, and `undecided`.
+- Each `sources` entry has `kind` (`engine`, `telemetry`, or `file`), `path`, `exists`, `records`, and `duplicatesDropped`; each `engine` entry also has `skippedInvalid`, `excludedSimulated`, and `undecided`. A registered project has one `engine` entry for the home store and one for each lane store.
 - Each `report.groups` row has `workflowHash`, `workflowId` (Runtime records), `stepId`, `agentRole`, `promptHash`, `recurrence`, `distinctRuns`, `askRecurrence`, `undecidedRecords`, `meanCost`, `meanLatency`, `verifyPassRate` (accepted share of decided records), `rework`, `weightedRecurrence`, `undatedRecords`, `costSamples`, `writesRepository`, `evidenceRefs`, `isCandidate`, and, when they apply, `excludedReason`, `candidateKind`, and `candidateId`.
 - Each `report.promotion` entry has `candidateId`, `policy`, `readyForReview`, and `reason`.
 
@@ -3565,18 +3565,18 @@ kxm routing report [-f <path>] [-l] [--prices <path>]
 
 Compare verified completion, cost, and rework per behavioral configuration. The table ranks routes quality-first with columns Harness, Model, Effort, Role, Att, Pass%, Rwk%, p50(ms), p95(ms), CtxTok, Metered($), $/Acc, Unm, Unk, Quota, and optionally ListEquiv($).
 
-Without `--file` it reads the same sources as [`kxm improve report`](#kxm-improve-report): the current project's Runtime event store (read-only), then the workspace `telemetry.jsonl`, dropping a telemetry copy of an attempt the store already supplied and excluding simulated drives. A Runtime attempt counts toward Pass% only when the event log shows its run completed without the step being re-entered.
+Without `--file` it reads the same sources as [`kxm improve report`](#kxm-improve-report): the registered home store and every lane store for that project (read-only), or only this checkout's store when the registry is absent or this checkout is unregistered, then the workspace `telemetry.jsonl`, dropping a later copy of an attempt an earlier source already supplied and excluding simulated drives. A Runtime attempt counts toward Pass% only when the event log shows its run completed without the step being re-entered.
 
 | Option | Argument | Default | Description |
 |---|---|---|---|
-| `-f`, `--file` | `<path>` | the Runtime store, then workspace telemetry | Read only this telemetry or event log JSONL file (default: this project's Runtime event store plus workspace telemetry) |
+| `-f`, `--file` | `<path>` | the Runtime stores, then workspace telemetry | Read only this telemetry or event log JSONL file (default: this project's Runtime event stores plus workspace telemetry) |
 | `-l`, `--equivalent-list-cost` | none | off | Include equivalent list price column using price catalog |
 | `--list-prices` | none | off | Alias for --equivalent-list-cost |
 | `--prices` | `<path>` | `.kxm/prices.yaml` | Path to price catalog (default: .kxm/prices.yaml) |
 
 - Reads only. A price catalog that cannot be loaded is skipped silently.
 - `--equivalent-list-cost` loads the catalog without the freshness check the producers apply, so it prices with a catalog of any date, including one the producers treat as stale. Check the catalog `date` before you rely on `ListEquiv($)`.
-- A Runtime store that exists but cannot be read exits 1 with `improve_source_unreadable`.
+- A Runtime store or registry that exists but cannot be read exits 1 with `improve_source_unreadable`. `--file` does not read the registry or any event store.
 - Ranking: quality first (Pass%, then Rwk%), then cost per accepted attempt. Among routes of equal quality, any route with an unknown-cost attempt ranks after every route without one. Such a route's cost is unknown, not a partial sum: `$/Acc` prints `-` (JSON `costPerAcceptedUsd: null`) and the `*` in `Unk` marks it.
 - The `Quota` column counts attempts whose metadata looks quota-exhausted (a quota failure class, a `quota` flag, or text such as `rate limit` or `HTTP 429`). It is a count only. Quota is not an `onError` class, and the column does not choose a route. Walks a role opted into are listed under Route switches when the store has `routing.route_switched` events (`from`, `to`, `reason`, optional `effort`, `stepId`).
 - The text output does not list the sources, and prints `no routing records in telemetry` when no source holds a record. The Rwk% column counts records with `transitions` greater than 0, which Runtime records never set.

package/docs/reference/configuration.md

@@ -30,6 +30,7 @@ Names that start with `KXM_` are not all operator settings. This map covers ever
 | Agents | `KXM_SERVER_URL`, `KXM_AUTH_TOKEN`, `KXM_PROJECT`, `KXM_AGENT_NAME`, `KXM_AGENT_PURPOSE` | [Agent settings](#agent-settings) |
 | Long-lived Pi workers | `KXM_PI_COMMAND`, `KXM_WORKER_*` (operator settings), `KXM_AGENT_LOG_PATH` | [Long-lived worker settings](#long-lived-worker-settings) |
 | Runtime supervisor | `KXM_STATE_HOME`, `KXM_RUNTIME_SYNC_INTERVAL_MS`, `KXM_RUNTIME_STOP_GRACE_MS` | [Runtime supervisor settings](#runtime-supervisor-settings) |
+| Studio and Python control plane | `KXM_CONTROL_URL`, `KXM_KXMD_*`, `KXM_AUTHENTIK_*`, `KXM_POSTGRES_*`, `KXM_DATABASE`, `KXM_DB_USER`, `KXM_TEMPORAL_*` | [Studio and Python control-plane settings](#studio-and-python-control-plane-settings) |
 | Operator CLI and sessions | `KXM_USER_CONFIG_DIR`, `KXM_USER_TELEMETRY_DIR`, `KXM_SESSION_TOKEN`, `KXM_SESSION_BRIEF`, `KXM_WORKFLOW_*`, `GITHUB_TOKEN`, and others | [CLI and session settings](#cli-and-session-settings) |
 | Nous model providers | `KXM_NOUS_PROVIDERS`, `KXM_NOUS_PROXY_URL`, `KXM_NOUS_DISCOVERY_TIMEOUT_MS`, `KXM_NOUS_CATALOG_FILE`, `NOUS_API_KEY` | [Nous providers](../guides/nous-providers.md) |
 | Browser automation | `KXM_BROWSER`, `OBSCURA_CDP_URL`, `OBSCURA_PORT`, `STEEL_API_URL`, `STEEL_UI_URL`, `STEEL_AUTH_HEADER`, `STEEL_AUTH_BASIC`, `STEEL_AUTH_USER`, `STEEL_AUTH_TOKEN`, `STEEL_API_KEY` (legacy), `USE_PASS_CLI` | [Browser settings](#browser-automation) |
@@ -187,6 +188,27 @@ The Runtime supervisor runs `kxm run` workflows and syncs their summaries to the
 | `KXM_RUNTIME_SYNC_INTERVAL_MS` | `10000` | How often the supervisor heartbeats and pushes its outbox, clamped to `250` through `60000` |
 | `KXM_RUNTIME_STOP_GRACE_MS` | `30000` | How long a stopping supervisor waits for open drives, `0` to `600000`; an invalid value warns and uses the default |
 
+## Studio and Python control-plane settings
+
+The MG1 Python service is additive: these values do not redirect the Node hub
+or Runtime from SQLite. Requests cannot override its database host, database,
+role, Temporal target, or namespace.
+
+| Variable | Default | Effect |
+|---|---|---|
+| `KXM_CONTROL_URL` | Unset | Python control API base URL used by Studio's `GET /api/control/account` relay. The relay returns `control_unconfigured` when absent, and aborts a nonresponding upstream after three seconds with `control_unreachable` |
+| `KXM_KXMD_PASSWORD` | None; required | PostgreSQL password for the fixed `kxmd` role. Keep it in the deployment secret manager |
+| `KXM_POSTGRES_HOST` | `127.0.0.1` | PostgreSQL host selected by the service deployment, including an operator-owned tunnel |
+| `KXM_POSTGRES_PORT` | `5432` | PostgreSQL port, from 1 through 65535 |
+| `KXM_DATABASE` | `kxmd` | Fixed database assertion. Any other value refuses startup-time account resolution |
+| `KXM_DB_USER` | `kxmd` | Fixed PostgreSQL role assertion. Any other value is refused |
+| `KXM_TEMPORAL_TARGET` | `127.0.0.1:7233` | Temporal endpoint selected by the service deployment |
+| `KXM_TEMPORAL_NAMESPACE` | `kxmd` | Fixed Temporal namespace assertion. Any other value is refused |
+| `KXM_KXMD_ARTIFACTS` | `/var/lib/kxm/artifacts/kxmd` | Root for bounded per-tenant artifacts |
+| `KXM_AUTHENTIK_ISSUER` | None; required for authenticated routes | Exact token issuer |
+| `KXM_AUTHENTIK_AUDIENCE` | None; required for authenticated routes | Exact token audience |
+| `KXM_AUTHENTIK_JWKS_URL` | None; required for authenticated routes | JWKS endpoint used to verify RS256 user and runner tokens |
+
 ## CLI and session settings
 
 | Variable | Default | Effect |

package/package.json

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