@kontextmind/kxm 0.7.97 → 0.7.98

package/docs/reference/config-reference.md

@@ -340,11 +340,15 @@ reference. Schema: `schemas/agent.schema.json`; semantic checks in
 | `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 every harness with a fixed read-only argument set
-(`READ_ONLY_ONESHOT_ARGS` in `plugins/kxm/src/harness.ts`); it does not
-translate `tools` into harness flags. The Runtime refuses live steps that
-request `write` access until the writer sandbox is in place, so a step that
-writes a repository runs today only under the simulated producer.
+producer launches each harness 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
+[Steps the Runtime does not execute yet](#steps-the-runtime-does-not-execute-yet).
 
 ### Model selectors
 
@@ -451,9 +455,11 @@ Error codes: `executor_unknown`, `harness_unknown`, `tool_preset_unknown`,
 [Rules shared by the project bundle](#rules-shared-by-the-project-bundle), and
 `role_roster_conflicts_with_agent` (see [Roles](#kxmrolesroleyaml-kxmrolev1)).
 
-Commands: `kxm init` creates `coordinator` and `implementer`; an interactive
-`kxm init` can add workflow-guide agents for authenticated harnesses; `kxm run`
-and the Runtime read them; `kxm trust` diffs them.
+Commands: `kxm init` creates `coordinator` (`claude`, `anthropic/fable`) and
+`implementer` (`grok`, `xai/grok-4.6`) and admits both selectors in
+`.kxm/routes.yaml`; an interactive `kxm init` can add workflow-guide agents for
+reviewed harness/model pairs whose harness is authenticated, and admits their
+selectors too; `kxm run` and the Runtime read them; `kxm trust` diffs them.
 
 ## `.kxm/models/<id>.yaml` (`kxm.model.v1`)
 
@@ -672,16 +678,21 @@ these, the run is handed off (`step_unsupported`, `gate_unsupported`, or
 `limit_unsupported`) instead of executing, and `kxm runs drive` reports
 `run_handoff_required`:
 
-- `limits.maxAgentTimeMs` in the workflow or project. The built-in template
-  sets it, so the `default` workflow that `kxm init` writes cannot be driven
-  as generated.
+- `limits.maxAgentTimeMs` in the workflow or project. The current `kxm init`
+  template leaves it out; older templates set it on `default`.
 - `tools`, `secrets`, or `safeSpeculation: true` on any step.
 - `join.strategy` other than `all` or `all-settled`, `join.minimumPassed` with
   `all`, and `join.cancelRemaining`.
 - `assignments.maxAttemptsPerAssignment` above 2,
   `assignments.maxWriteRepositories` above 1, and `distinctBy` other than
   `provider`.
-- A live (non-simulated) step with `write` access to any repository.
+- A live (non-simulated) step with `write` access to any repository when its
+  agent's harness has no audited writer profile (only `pi` and `grok` have
+  one), when `assignments.maximum` is above 1, when the project's
+  `limits.maxConcurrentRuns` is above 1, or when `.kxm/roster.yaml` exists and
+  is not a `kxm.developer-roster.v1` whose writer lineup admits that harness
+  and model with `edit` permission. The checkout witness can attribute a
+  change only to one writer at a time.
 - Gate steps with `assignments.allowedAgents`, any assignment count or
   `maxAttemptsPerAssignment` other than 1, `distinctBy`,
   `maxWriteRepositories`, a join other than plain `all`, a `model`, no
@@ -1716,7 +1727,7 @@ Everything under `.kxm/` at the project root falls into one of three groups.
 | `logs/` | Ignored runtime logs | The hub and workers |
 | `state/` | Ignored restart state: the hub database `kxm.db`, Pi sessions, worker manifests | The hub and workers |
 | `run/` | Ignored sockets (`run/ssh-sockets/`) | `kxm ssh` |
-| `backups/` | Ignored; each `backup-<time>/` holds a copy of the hub database and `manifest.json` | `kxm backup` (without `--out`) |
+| `backups/` | Ignored; each `backup-<time>/` holds copies of the hub database, the Runtime stores and their prompt sidecars, and `manifest.json` | `kxm backup` (without `--out`) |
 | `config/` | Legacy: its JSON files make the project unloadable | Nothing current |
 | `.kxm-init-transaction/` (sibling of `.kxm/` at the Git root) | Ignored; interrupted `kxm init` state | `kxm init` |
 

package/docs/reference/harness-routing.md

@@ -278,7 +278,7 @@ No product producer writes `metered` today. Subscription runs are `unmetered` be
 - The catalog `date` is today.
 - The harness is `claude` and the token counts are complete. The Runtime runs every harness, Pi included, through the one-shot producer, which estimates only for `claude`. The package also ships a long-lived Pi producer that estimates for any provider, but nothing in the Runtime calls it today.
 
-`kxm routing report` groups records by harness, model, effort and role. It ranks routes by quality first (Pass%, then Rwk%), then by cost per accepted attempt. Among routes of equal quality, a route with any unknown-cost attempt ranks after every route without one, because its cost is only a lower bound. Its `$/Acc` still shows only what was priced, so a route that mixes unmetered and unknown-cost attempts can read `$0.0000`; the `*` in the `Unk` column marks it. Read `Unm` and `Unk` before you trust `$/Acc`.
+`kxm routing report` groups records by harness, model, effort and role. It ranks routes by quality first (Pass%, then Rwk%), then by cost per accepted attempt. Among routes of equal quality, a route with any unknown-cost attempt ranks after every route without one, because its cost is unknown. Its `$/Acc` prints `-` instead of a partial sum, and the `*` in the `Unk` column marks it. Read `Unm` and `Unk` before you trust `$/Acc`.
 
 The `Quota` column counts attempts whose metadata looks quota-exhausted. Nothing fails over on it. The report has no provider column, so the `Harness` column is what tells you native from Pi.
 
@@ -407,7 +407,7 @@ The code today limits where that route can run:
 - The KXM Pi extension registers the `antigravity` provider. The Runtime's Pi one-shot runs with `--no-extensions`, so it cannot reach `antigravity/…`.
 - Only an interactive Pi with KXM loaded, or a long-lived Pi worker, can use it.
 
-Admit an `antigravity/…` route only through a reviewed admission decision. Whether Google work should use `agy` or `antigravity` today is still an operator decision; see [Where the code is looser than the rules](#where-the-code-is-looser-than-the-rules).
+Admit an `antigravity/…` route only through a reviewed admission decision. The guided setup in `kxm init` maps Google guide candidates to `antigravity/gemini-3.8-flash-high` on Pi and admits that selector, but a Runtime drive of such an agent still cannot reach the provider. Whether Google work should use `agy` or `antigravity` today is still an operator decision; see [Where the code is looser than the rules](#where-the-code-is-looser-than-the-rules).
 
 ### Claude bridge: experiment only
 
@@ -493,7 +493,7 @@ These are places where the code decides less than the [routing rules](#routing-r
 - **Reseller ids without a vendor segment.** Pi also serves native vendors' models under a reseller's own provider id, for example `github-copilot/claude-…`, `amazon-bedrock/anthropic.…` or `azure-openai-responses/gpt-…`. The brake reads the provider and the vendor segment, not the model name, so it accepts these ids. Keep them out of `.kxm/routes.yaml`.
 - **Open-weight models on a third-party plan.** A DeepSeek model billed through Alibaba's plan, such as `qwen-token-plan/deepseek-v4.1-flash`, passes the brake although DeepSeek is a braked vendor. The reverse also happens: an open-weight model filed under a native vendor's namespace, such as `groq/openai/gpt-oss-120b`, is refused. Whether a third-party plan bill counts as billing the vendor is not decided.
 - **Selectors the brake cannot see.** A worker started without `--model` runs Pi's default model, and a bare model id lets Pi choose the provider. Neither names a vendor, so neither is checked. A model that a person selects inside an interactive Pi session is not checked either.
-- **The Google route.** The rules name the `antigravity` Pi provider as Google's route, but the code sends Google through `agy`: the guided setup in `kxm init` maps Google candidates to `agy`, and the Runtime's Pi one-shot cannot reach `antigravity/…` (section 4).
+- **The Google route.** The rules name the `antigravity` Pi provider as Google's route, and the guided setup in `kxm init` now writes Google roles on Pi with `antigravity/gemini-3.8-flash-high` and admits that selector. The Runtime's Pi one-shot runs with `--no-extensions`, so it cannot reach `antigravity/…` and a live drive of those roles fails at dispatch (section 4). A `google/gemini-…` selector still runs only through `agy`.
 - **Two Pi provider allowlists.** `PI_ALLOWED_PROVIDERS` in `plugins/kxm/src/harness.ts` is exported but gates nothing; on the product path, the brake and admission in `.kxm/routes.yaml` decide. The developer helper keeps a different list of its own.
 - **`limits.maxModelCost` cannot trip on a live run.** The engine counts only `metered` cost toward the cap, and no producer records `metered` today (section 2). The Runtime caps `unmetered` and `unknown` attempts at 100 per run instead; see [Cost basis and staleness](config-reference.md#cost-basis-and-staleness).
 - **Config load checks harness/model pairs only for agents that declare `harness:` and select their model through a profile or tag.** An agent with a direct `{provider, model}` selector, or one that omits `harness:` and names `provider: xai`, passes `kxm init --dry-run` and fails only at dispatch.

package/docs/reference/http-api.md

@@ -191,7 +191,7 @@ A bad token is `runtime_auth_failed`; a missing parameter is `runtime_request_in
 
 ## Web Studio server
 
-`kxm studio serve` runs a separate local server, on `127.0.0.1:4242` by default, with `/`, `/health`, `GET /api/layout` and `POST /api/mutate`. It answers every route with `Access-Control-Allow-Origin: *`, so any web page in a local browser can read the layout. The mutate route requires a bearer session token only when one resolves; with none it accepts any caller. It accepts an allowlisted command name but executes nothing. See [`kxm studio serve`](cli-reference.md#kxm-studio-serve).
+`kxm studio serve` runs a separate local server, on `127.0.0.1:4242` by default, with `/`, `/health`, `GET /api/layout` and `POST /api/mutate`. It answers every route with `Access-Control-Allow-Origin: *`, so any web page in a local browser can read the layout. The mutate route requires a bearer session token only when one resolves; with none it accepts any caller. It answers an allowlisted command name with HTTP 501 and `error: "mutation_handler_missing"`, and executes nothing. See [`kxm studio serve`](cli-reference.md#kxm-studio-serve).
 
 ## Related
 

package/docs/start/first-workflow.md

@@ -250,11 +250,11 @@ The file is a `kxm.workflow.v1` definition. `coordinator` names the agent that o
 | Cost | None | Model usage on your accounts |
 
 > [!WARNING]
-> Without `--simulated`, `kxm runs drive` calls live harnesses. An agent whose model is not an admitted route fails with `producer_route_not_admitted`. Read [Harness routing](../reference/harness-routing.md) before your first live drive. A live drive hands off any agent, panel, approval or wait step with `write` access; gate steps are exempt, and the read-only `spec-and-plan` template avoids the refusal.
+> Without `--simulated`, `kxm runs drive` calls live harnesses. An agent whose model is not an admitted route fails with `producer_route_not_admitted`. Read [Harness routing](../reference/harness-routing.md) before your first live drive. A live step with `write` access runs only on a harness with an audited writer profile (`pi` or `grok`), as a single assignment, in a project whose `limits.maxConcurrentRuns` is 1, and, when `.kxm/roster.yaml` exists, only on a route in its writer lineup; any other live write step is handed off. A live write step settles `passed` only when the checkout changed, and a read-only step that changes the checkout settles `failed`. Gate steps are exempt. The read-only `spec-and-plan` template needs none of this.
 
-### Why not the `default` workflow
+### Why start with `first` and not `default`
 
-`kxm init` also writes a `default` workflow that plans, implements and runs the test gate. It declares `limits.maxAgentTimeMs`, an agent-time budget the Runtime cannot enforce yet. A drive of it is refused with HTTP 409 `run_handoff_required` (reason `limit_unsupported`), and the run stays `preparing` until you cancel it with `kxm runs cancel <run-id>`. [Steps the Runtime does not execute yet](../reference/config-reference.md#steps-the-runtime-does-not-execute-yet) lists every setting that causes a handoff.
+`kxm init` also writes a `default` workflow. Its coordinator plans on `claude` / `anthropic/fable`, its implementer writes the checkout on `grok` / `xai/grok-4.6`, and a `test` gate runs `npm test`; `kxm init` admits exactly those two models in `.kxm/routes.yaml`. You can drive it, but even a simulated drive runs `npm test` in your checkout, and a live drive spends both subscriptions and passes the implement step only when Grok changes the checkout. `first` calls no model and runs no command, so it is the safer first run. [Steps the Runtime does not execute yet](../reference/config-reference.md#steps-the-runtime-does-not-execute-yet) lists every setting that makes a drive hand the run off.
 
 ### Two kinds of runs
 
@@ -264,7 +264,7 @@ The file is a `kxm.workflow.v1` definition. `coordinator` names the agent that o
 
 | Message or symptom | Cause | Fix |
 |---|---|---|
-| `run_handoff_required` naming `limits.maxAgentTimeMs` | You drove the `default` workflow | Cancel the run and use `first` |
+| `run_handoff_required` naming `limits.maxAgentTimeMs` | The workflow declares an agent-time budget, which the Runtime does not enforce; a project from an older `kxm init` template has one on `default` | Cancel the run, remove the limit or use `first` |
 | `trust check failed: review every expansion above before merging` | The workflow is not committed | Review it, then commit it |
 | `workflow <id> does not exist in this project` | The ID is not a local workflow | Use an ID from `kxm workflow definitions` marked `[local]` |
 | `gate_outcome_impossible` from `kxm init` | A gate step routes failure on `failed` | Declare `implementation-failure` on the gate step |

package/docs/start/quickstart-claude-code.md

@@ -320,7 +320,7 @@ Continue with [step 4](#4-bind-this-machine-and-check-the-hub) through [step 7](
 
 ### Before you update
 
-From the directory the hub runs in, back up its database, then stop the hub and the Runtime:
+From the directory the hub runs in, back up its database and the Runtime stores, then stop the hub and the Runtime:
 
 ```bash
 kxm backup
@@ -331,7 +331,7 @@ kxm runtime stop
 `kxm backup` writes a verified copy and a hashed manifest to `.kxm/backups/backup-<timestamp>/`.
 
 > [!WARNING]
-> `kxm backup` copies the hub store only. It does not find the Runtime's registry and run event stores under the user state root. Copy those while the Runtime is stopped, as [Back up everything else](../operations/backup-and-restore.md#back-up-everything-else) describes.
+> `kxm backup` copies the hub store and the Runtime's registry and run event stores, and those Runtime stores belong to every project on this machine. A later `kxm restore` rolls all of them back. It does not copy bindings, `update.yaml` or the other state roots; [Back up everything else](../operations/backup-and-restore.md#back-up-everything-else) covers those.
 
 [Back up and restore KXM](../operations/backup-and-restore.md) and [Upgrade KXM](../operations/upgrade.md) cover restores and rollback.
 

package/package.json

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