@kontextmind/kxm 0.7.128 → 0.7.131

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

package/.kxm/README.md

@@ -15,7 +15,6 @@ a `default` workflow, `gates.yaml` and `template-provenance.yaml`.
 | `agents/`, `models/`, `workflows/` | Agents, model profiles and workflows, one YAML file each | Tracked |
 | `gates.yaml` | The executable gate registry | Tracked |
 | `roles/`, `routes.yaml`, `prices.yaml` | Role rosters, admitted model routes, dated list prices | Tracked |
-| `roster.yaml` | The developer assignment roster for this repository | Tracked, and must be committed |
 | `template-provenance.yaml` | Hashes of the template `kxm init` used | Tracked |
 | `models/inventory.yaml` | The discovered model catalog | Generated; track it for a reviewed snapshot |
 | `config.yaml` | Shared personalization settings | Tracked if the project shares them |
@@ -26,6 +25,10 @@ a `default` workflow, `gates.yaml` and `template-provenance.yaml`.
 | `state/` | The hub database `kxm.db`, Pi sessions and restart state | Ignored |
 | `run/` | SSH control sockets from `kxm ssh` | Ignored |
 
+The role files under `.kxm/roles/` and the model files under `.kxm/models/`
+carry the developer policy. The assignment runner reads them at
+`refs/remotes/origin/main`.
+
 The [configuration reference](../docs/reference/config-reference.md#workspace-layout-tracked-ignored-and-state)
 describes every file, the ignore rules to add, and the state KXM keeps outside
 the project.

package/.kxm/agents/coordinator.yaml

@@ -1,5 +1,6 @@
 schema: kxm.agent.v1
 purpose: Coordinate the pinned workflow and emit schema-validated commands.
+role: planner
 tools:
   preset: coordinator
 defaultRepositoryAccess: read

package/.kxm/agents/critic-arch.yaml

@@ -1,9 +1,6 @@
 schema: kxm.agent.v1
 purpose: Architecture critic for the approved workflow change.
-harness: claude
-model:
-  provider: anthropic
-  model: fable
+role: reviewer-arch
 tools:
   preset: read-only
 defaultRepositoryAccess: read

package/.kxm/agents/critic-cli.yaml

@@ -1,9 +1,6 @@
 schema: kxm.agent.v1
 purpose: CLI and verification critic for the approved workflow change.
-harness: codex
-model:
-  provider: openai
-  model: gpt-5.6-sol
+role: reviewer-cli
 tools:
   preset: read-only
 defaultRepositoryAccess: read

package/.kxm/agents/implementer.yaml

@@ -1,9 +1,6 @@
 schema: kxm.agent.v1
 purpose: Implement the approved change within the declared repository scope.
-harness: grok
-model:
-  provider: xai
-  model: grok-4.7
+role: writer
 tools:
   preset: workspace-writer
 defaultRepositoryAccess: none

package/.kxm/workflows/implement-only.yaml

@@ -1,5 +1,5 @@
 schema: kxm.workflow.v1
-description: One implementer step with a drive receipt. Replaces just impl.
+description: One implementer step with a drive receipt.
 coordinator: coordinator
 limits:
   maxTransitions: 2

package/.kxm/workflows/review-arch-only.yaml

@@ -1,5 +1,5 @@
 schema: kxm.workflow.v1
-description: One read-only architecture critic step. Replaces just review-arch.
+description: One read-only architecture critic step.
 coordinator: coordinator
 limits:
   maxTransitions: 2

package/.kxm/workflows/review-cli-only.yaml

@@ -1,5 +1,5 @@
 schema: kxm.workflow.v1
-description: One read-only CLI critic step. Replaces just review-cli.
+description: One read-only CLI critic step.
 coordinator: coordinator
 limits:
   maxTransitions: 2

package/CHANGELOG.md

@@ -138,6 +138,17 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Changed
 
+- **Dispatch reads role and model files, and agents bind a role.**
+  `scripts/roster-policy.mjs` builds the developer policy from
+  `.kxm/models/*.yaml` and `.kxm/roles/*.yaml` at `refs/remotes/origin/main`.
+  The engine resolves harness, model, and effort from the agent's `role`
+  and that role's roster. A step `model` does not override that route.
+  `kxm routes` prints `policy` (`admitted`, `disabled`) and `membership`
+  from the role files. `.kxm/routes.yaml` keeps admitted and disabled
+  selectors. `reviewer-arch` resolves to `fable-claude`. `opus-claude` is
+  admitted and named by no roster, so it is absent from `routes` and the
+  lineups. `gemini-agy` is in the writer lineup. An agent `tools.preset`
+  may only narrow its role preset; that rule is recorded and enforced in P3.
 - **Role and model files are live `kxm.role.v2` and `kxm.model.v2`.**
   `schemas/role.schema.json` and `schemas/model.schema.json` are the files
   `kxm config` validates. Each admitted roster route is a
@@ -153,7 +164,9 @@ All notable user-facing changes are documented here. The project follows [Semant
   in the developer ceilings or the harness inventory can dispatch them:
   `zai-coding-cn/glm-5.3-flash`, `qwen-token-plan/qwen3.8-flash`,
   `qwen-token-plan/qwen3.8-max`, and `zai-coding-cn/glm-5.3`.
-  Dispatch still reads `.kxm/roster.yaml` until P2.
+  Dispatch resolves harness, provider, model, and effort from the role roster.
+  A live request with no harness is refused. A roster entry with no effort
+  leaves thinking unset.
 
 - **Usage errors under `--json` print a `usage_error` envelope and exit 2.**
   A missing required option, unknown command, or other Commander usage error
@@ -418,6 +431,14 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Removed
 
+- **The developer roster file and the transport just recipes.**
+  The single roster document and the `impl`, `plan`, `review-arch`,
+  `review-cli`, `impl-bg`, and `dispatch` recipes are gone. One-step
+  workflows are the transport: `kxm lane run <unit> --brief <file> --workflow implement-only`,
+  and the same command with `review-arch-only` or `review-cli-only`.
+  Transfer policy from `.kxm/roster.yaml` to the role and model files and
+  delete the retired roster before running KXM. KXM refuses a leftover
+  `.kxm/roster.yaml`.
 - **`.kxm/template-provenance.yaml` was removed from this project, a repository
   change rather than a product change,** because the installed kxm no longer
   recognizes its recorded revision and a project without the file validates as
@@ -425,6 +446,26 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Fixed
 
+- **The test suite no longer passes `--test-timeout`.** Under `node --test` that flag bounds each file, so coverage on CI timed out `test/core/engine.test.ts` at three minutes. The wall clock in `scripts/run-bounded.mjs` still bounds each script.
+- **A git worktree lane registers under its project.** The Runtime registry
+  keeps the home row and adds the lane as its own control root and event
+  store, with the same project id and home runtime (`lane_of` on the lane
+  row). A foreign clone with that id is still `project_home_conflict`. A
+  registered root whose directory is gone is replaced, and that replacement
+  logs one `project_registration_replaced` event. `kxm lane drop` unregisters
+  the lane root when the Runtime is running, and still drops the worktree
+  when the Runtime is stopped. `kxm runs status` and `kxm lane status` print
+  the root they read. On the first read-write open, the registry table is
+  rebuilt and the registry advances from schema 1 to 2, copying every row
+  forward with `lane_of` empty. `kxm lane drop` refuses `lane_run_open` and names every
+  unsettled run in that lane's event store unless `--force` is set. Unregister
+  answers 409 `runtime_project_busy` or `runtime_project_has_lanes` unless the
+  body sets `force`.
+- **`npm test` exits when the suite finishes.** The script passes
+  `--test-force-exit`, so a green run does not sit in the event loop and a
+  red run still prints its failures. Two full runs of the suite without the
+  flag also exited once the files finished; the handle that kept an earlier
+  run alive was not reproduced in this tree.
 - **`kxm land` names the pull request from the first commit subject and matches the Release run by time.**
   `--title` sets the title; otherwise the subject of the first commit on the
   branch is used, and a missing subject refuses `land_pr_title_missing`. The

package/docs/architecture/inventory.md

@@ -13,7 +13,7 @@ Read from `plugins/kxm/src/cli.ts`, `scripts/kxm-hub.mjs`, `plugins/kxm/src/hub.
 | Hub | `kxm hub start` via `scripts/kxm-hub.mjs` | `127.0.0.1:7331` | `.kxm/state/kxm.db` under the workspace state dir | `plugins/kxm/src/hub.ts` |
 | Hub credentials | written when the hub starts | `hub-env.json` under the user state root | that JSON file, not SQLite | `plugins/kxm/src/hub-env.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` | `plugins/kxm/src/runtime-paths.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` |
 | 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` |

package/docs/concepts/architecture.md

@@ -211,7 +211,7 @@ The package ships a directory of `SKILL.md` suites that Pi and Claude Code both
 Project behavior lives in Git under `.kxm/`: `project.yaml`, `agents/`, `models/`, `workflows/`, `gates.yaml`, `roles/`, `routes.yaml`, `memory/`, and `skills/`. The project bundle (`project.yaml`, `agents/`, `models/`, `workflows/`, and `gates.yaml`) is restricted YAML checked against a JSON Schema. `routes.yaml`, `roles/`, and the front matter in `memory/` and `skills/` are parsed as ordinary YAML with their own checks, and a live drive re-reads an agent file the same way to resolve its route. Git review is the activation boundary:
 
 - Every run pins revision hashes of the project bundle, memory, executor policy, and tool policy. An edit affects only later runs, and a run whose pinned revisions drift is refused.
-- `kxm trust diff` prints a structured permission diff against a base revision (default `HEAD`). `kxm trust check` exits non-zero when the change expands permissions. Neither covers `routes.yaml`, `roles/`, `roster.yaml`, or `prices.yaml`, so admitting a route is not flagged.
+- `kxm trust diff` prints a structured permission diff against a base revision (default `HEAD`). `kxm trust check` exits non-zero when the change expands permissions. Neither covers `routes.yaml`, `roles/`, `the role files`, or `prices.yaml`, so admitting a route is not flagged.
 - Legacy `.kxm/config/*.json` files are refused, never converted.
 
 Webhook workflow definitions are separate JSON that the hub loads at start, with secrets named by environment variable. Personal settings merge built-in defaults, then `~/.config/kxm/config.yaml`, then the project's `.kxm/config.yaml`. See the [configuration file reference](../reference/config-reference.md) and [Configuration](../reference/configuration.md).

package/docs/concepts/data-and-storage.md

@@ -162,7 +162,7 @@ Each database records its schema version in SQLite's `user_version`. When a proc
 - an older store fails with `runtime_schema_outdated`;
 - a store with tables but no version fails with `runtime_schema_shape_invalid`.
 
-KXM never upgrades a store in place, because the code would otherwise have to keep working against schema shapes it no longer tests. To cross a store version, stop the owner, back up if you need the history, delete the store with its `-wal` and `-shm` files, and let the owner recreate it: `kxm hub start` for `kxm.db`, and the Runtime for the registry and event stores. `kxm init` rebuilds no database. Legacy `.kxm/config/*.json` files are refused the same way.
+KXM does not upgrade hub stores or Runtime event stores in place, because the code would otherwise have to keep working against schema shapes it no longer tests. To cross one of those versions, stop the owner, back up if you need the history, delete the store with its `-wal` and `-shm` files, and let the owner recreate it: `kxm hub start` for `kxm.db`, and the Runtime for event stores. The Runtime registry is the exception: schema 1 opens as schema 2, and each existing row keeps its root with `lane_of` left empty. `kxm init` rebuilds no database. Legacy `.kxm/config/*.json` files are refused the same way.
 
 Every store opens in WAL mode with a 5-second busy timeout, `synchronous=NORMAL`, and foreign keys on. A database or sidecar that is a symbolic link is refused. [ADR-0003](../adr/ADR-0003-sqlite-only-store.md) records why SQLite is the only store.
 

package/docs/contracts/README.md

@@ -17,7 +17,7 @@
 | [Synchronization](synchronization.md) | Implemented for the default policy; custom policies and on-demand content transfer are not |
 | [Routing](routing.md) | Implemented: routing records, the dated price catalog, `kxm routing report` and `kxm improve` |
 | [Validation](validation.md) | Largely implemented: the restricted YAML loader, schema, reference and semantic checks, and permission diffs |
-| [Migration](migration.md) | Decided: there is no migration path and no `kxm migrate` command; legacy state is refused |
+| [Migration](migration.md) | Decided: no `kxm migrate` command; legacy state is refused. The Runtime registry schema 1 to 2 copy is the one in-place step |
 
 KXM is a convention-over-configuration, local-first orchestration and
 context platform. One local Runtime owns execution; an optional multi-project

package/docs/contracts/migration.md

@@ -14,7 +14,7 @@ one re-adds a compatibility lane by inference.
 | Project tree with legacy `.kxm/config` JSON | `loadKxmProject` fails closed with `legacy_state_unsupported`, one issue per legacy file. No receipt, plan, flag, or environment variable unlocks it. |
 | `kxm init` on such a tree | Reports `mode: "legacy"`, lists `legacyInputs`, performs **no writes**. Recovery is a fresh project directory plus the YAML definitions worth keeping. |
 | `kxm migrate` | Unknown command. It existed as `plan` / `apply` / `verify` for pre-KXM JSON and was deleted with this decision. |
-| SQLite store stamped with an older `user_version` | Refused with `runtime_schema_outdated`; the refusal never advances `user_version`, so the store stays identifiably old. Delete the state file and let the process that owns it recreate the store (`kxm hub start` for hub state, the Runtime for registry/event stores). `kxm init` is **project-only** and rebuilds no database. Forward-only stamping is prohibited — it turns a clean failure into a later query against a column that does not exist. |
+| SQLite store stamped with an older `user_version` | Hub stores and Runtime event stores are refused with `runtime_schema_outdated`. That refusal never advances `user_version`. Delete the state file and let the process that owns it recreate the store (`kxm hub start` for hub state, the Runtime for event stores). `kxm init` is **project-only** and rebuilds no database. The Runtime registry is the exception: schema 1 is copied to schema 2 in place, existing rows stay, and `lane_of` is null on those rows. Forward-only stamping of any other store is prohibited, because it turns a clean failure into a later query against a column that does not exist. |
 | Retired product and command names | Rejected by fail-closed brakes (lint + readiness tests), not aliased. |
 | Shared/off-scope Pi history | Never imported into a narrower run scope. A new physical session starts clean; durable facts come from Git, workflow evidence, artifacts, or promoted context. |
 | Historical run records | Never fabricated. Events whose real ordering was not observed stay absent rather than reconstructed into a finer-grained model. |
@@ -31,15 +31,19 @@ does exist:
   [Back up and restore KXM](../operations/backup-and-restore.md); a single `kxm.db`
   copy is not a backup.
 - **Out-of-range versions refuse without touching the file.** The stamp is read
-  before anything that can modify the store, so a database this build refuses —
-  older or newer — comes back byte-identical: neither its schema nor its
+  before anything that can modify the store, so a database this build refuses,
+  older or newer, comes back byte-identical: neither its schema nor its
   `user_version` changes, and it is not converted to WAL as a side effect of being
-  rejected. A store ahead of this build is refused without downgrade.
-- **Schema changes are additive-and-replace, not in-place.** Land the new
+  rejected. A store ahead of this build is refused without downgrade. The
+  registry schema 1 to 2 copy is not a refusal: that file is rewritten, and
+  every other older store is still refused untouched.
+- **Schema changes are additive-and-replace, not in-place,** except the
+  Runtime registry's `lane_of` column. For every other store, land the new
   definition, delete the local state, and let the process that owns each store
-  recreate it — `kxm hub start` for hub state, the Runtime for registry and
-  event stores. `kxm init` is project-only and rebuilds no database.
-  Nothing in the runtime may rewrite an existing store's shape.
+  recreate it. `kxm hub start` recreates hub state. The Runtime recreates event
+  stores. `kxm init` is project-only and rebuilds no database. Nothing else in
+  the runtime may rewrite an existing store's shape. Opening a schema 1
+  registry copies its rows into schema 2 and leaves `lane_of` null.
 
 ## If this ever changes
 

package/docs/contracts/routing.md

@@ -130,11 +130,11 @@ just accept /abs/task-dir <commit> /abs/writer-record /abs/arch-review /abs/cli-
 # optional observed PR/CI (direct script; the five-argument just recipe cannot forward them):
 # node scripts/assignment-run.mjs accept --task-dir /abs/task --commit <sha> --record-dir /abs/writer --critic /abs/arch --critic /abs/cli [--observed-pr <id>] [--observed-ci <id>]
 
-just plan-current /abs/task-dir /abs/plan.md <sha256> <base-commit> <expected-generation>
+kxm assign plan-current --task-dir /abs/task-dir --plan /abs/plan.md --sha256 <sha256> --base-commit <base-commit> --expected-generation <expected-generation>
 just change-report /abs/task-dir
 ```
 
-`just impl|plan|review-arch|review-cli` remain harness transport. They do not
+`kxm lane run` remain harness transport. They do not
 create assignment identity, witness receipts, or `accepted.json`.
 
 Distinctions the report and docs must keep:
@@ -161,7 +161,7 @@ learned policy and not a catalog feed. Phase 9 may use this report to
 Per-candidate acceptance requires an actual native writer, the fixed witness,
 and both designated native reviews. PR/CI/merge complete issue 127. This
 document does not assert those gates have passed. Low-level
-`just impl|plan|review-arch|review-cli` recipes remain harness transport.
+`kxm lane run` recipes remain harness transport.
 
 ## Implemented: v2 record
 

package/docs/contributing/assignment-runner.md

@@ -16,24 +16,25 @@ a KXM product feature.
 ## Before you begin
 
 - A clean control checkout of this repository whose `HEAD` is an ancestor of
-  `origin/main`. The runner loads `.kxm/roster.yaml` only from there.
+  `origin/main`. The runner loads `.kxm/roles/*.yaml` and `.kxm/models/*.yaml`
+  only from there.
 - A separate worktree for the writer. `kxm lane create <unit>` creates one from
   `origin/main`.
 - The harness CLIs the roster admits, installed and logged in.
   `node scripts/kxm.mjs harness list` shows which are. The loop below is
-  `kxm assign`. `just` still runs the transport recipes.
+  `kxm assign`. Transport is `kxm lane run <unit> --brief <file> --workflow implement-only`,
+  or the same command with `review-arch-only` or `review-cli-only`.
 - A task directory whose final path segment equals the task ID. Every path you
   pass to the runner must be absolute.
 
 ## Roles and routes
 
-The trusted roster policy in [`.kxm/roster.yaml`](../../.kxm/roster.yaml)
-(`kxm.developer-roster.v1`) admits each route for specific roles and
-permissions:
+The trusted roster policy in `.kxm/roles/*.yaml` and `.kxm/models/*.yaml`
+admits each route for specific roles and permissions:
 
 | Role | Admitted route (harness / model) | Vendor | Permission |
 |---|---|---|---|
-| `writer` | `grok` / `grok-4.7`; relief: `pi` / `openrouter/qwen/qwen3-coder-plus` | `xai`; `alibaba` | `edit` |
+| `writer` | `grok` / `grok-4.7`; relief: `pi` / `openrouter/qwen/qwen3-coder-plus`; `agy` / `gemini-3.8-flash-high` | `xai`; `alibaba`; `google` | `edit` |
 | `planner` | `claude` / `fable` | `anthropic` | `read-only` |
 | `reviewer-arch` | `claude` / `fable` | `anthropic` | `read-only` |
 | `reviewer-cli` | `codex` / `gpt-5.6-sol` | `openai` | `read-only` |
@@ -85,7 +86,7 @@ Use this slim loop for daily work and for docs. The 13-step `fix` workflow in
 > runner validates anything. The process environment is passed through as it
 > is. Export any variable you need before the command.
 
-The seven `just` assignment recipes remain available and will be removed after one real unit has been accepted through `kxm assign`; until then both forms are equivalent because both call `scripts/assignment-run.mjs` unchanged.
+Transport is `kxm lane run <unit> --brief <file> --workflow implement-only`, or the same command with `review-arch-only` or `review-cli-only`. The transport recipes are deleted.
 
 ### 1. Pin the current plan
 
@@ -314,17 +315,15 @@ It writes `recording-resolved.json` in the record directory. It never changes
 ## Transport-only recipes
 
 Drive a one-step workflow in a lane. Each command writes a drive receipt and
-the checkout fingerprint. `just impl`, `just plan`, `just review-arch`,
-`just review-cli`, and `just impl-bg` are retired in favor of these. The
-recipes stay in the justfile until one real unit has been driven this way.
+the checkout fingerprint.
 
 ```bash
-kxm lane run <unit> --workflow implement-only --brief <file>
-kxm lane run <unit> --workflow review-arch-only --brief <file>
-kxm lane run <unit> --workflow review-cli-only --brief <file>
+kxm lane run <unit> --brief <file> --workflow implement-only
+kxm lane run <unit> --brief <file> --workflow review-arch-only
+kxm lane run <unit> --brief <file> --workflow review-cli-only
 ```
 
-`just dispatch` still sends one `kxm.harness-request.v1` envelope through
+`scripts/harness-run.mjs` still accepts one `kxm.harness-request.v1` envelope through
 `scripts/harness-run.mjs` and prints a `kxm.harness-result.v2` envelope. It
 mints no assignment, witness or acceptance proof, so its output cannot be
 accepted. The retired recipes did the same.
@@ -430,4 +429,4 @@ gate-only workflows are supported. See the
 - [Develop KXM](development.md): the commit gate the witness runs
 - [CI and release](ci-and-release.md): what runs after you push
 - [Harness routing](../reference/harness-routing.md): harness and model pairing
-- [Configuration reference](../reference/config-reference.md#kxmrosteryaml-kxmdeveloper-rosterv1): the roster file
+- [Configuration reference](../reference/config-reference.md#developer-assignment-policy): the developer assignment policy

package/docs/contributing/development.md

@@ -13,8 +13,16 @@ extension, the Claude Code plugin, or the bundled skills.
 - Optional tools, needed only for the matching task:
   - [Pi](https://pi.dev) to load the extension from source.
   - The Claude Code CLI to validate the plugin manifests locally.
-  - [`just`](https://github.com/casey/just) for the
-    [assignment runner](assignment-runner.md).
+  - [`just`](https://github.com/casey/just) for the remaining
+    [assignment runner](assignment-runner.md) recipes only:
+    `assign`, `witness`, `accept`, `observe-cost`, `attribute`,
+    `change-report`, and `plan-current`. Those recipes are harness
+    transport for the issue 127 runner. They are not how a unit is
+    dispatched. Do not rename or delete them.
+  - `kxm lane run` to dispatch a unit. A writer unit uses
+    `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.
 
 ## Set up a checkout
@@ -116,7 +124,7 @@ excluded from the npm package.
 ├── .github/                CI, release, issue and PR templates (not shipped)
 ├── .claude/                Developer harness notes and commands (not shipped)
 ├── plans/                  Internal planning and tracking (not shipped)
-├── justfile                Developer recipes for the assignment runner
+├── justfile                Remaining issue 127 recipes (assign, witness, accept, observe-cost, attribute, change-report, plan-current)
 └── AGENTS.md, CLAUDE.md, GEMINI.md   Agent instructions with generated blocks
 ```
 
@@ -196,8 +204,14 @@ For what each skill covers, see [Agent skills](../guides/agent-skills.md).
 8. Push and open a pull request. The template asks for the slice issue and the
    `npm run verify` result.
 
-Maintainers who delegate work to coding agents use the
-[assignment runner](assignment-runner.md) for steps 2 to 7.
+Maintainers who delegate a unit dispatch it with
+`kxm lane run <unit> --brief <file> --workflow implement-only`.
+Read-only critics use the same command with `review-arch-only` or
+`review-cli-only`. The [assignment runner](assignment-runner.md)
+recipes (`assign`, `witness`, `accept`, `observe-cost`, `attribute`,
+`change-report`, `plan-current`) stay on `just`. They are harness
+transport for the issue 127 runner, not the unit transport, and they
+cover steps 2 to 7 after a lane run.
 
 ## Generated artifacts
 
@@ -235,10 +249,12 @@ It runs three scripts in order:
 
 | Step | Script | What it checks |
 |---|---|---|
-| 1 | `npm test` | Build, then `test/core/*.test.ts` and `packages/core/*/tests/unit/*.test.ts` |
+| 1 | `npm test` | Build, then `test/core/*.test.ts` and `packages/core/*/tests/unit/*.test.ts`. The script passes `--test-force-exit` so a finished run leaves the process even if a handle is still open; a failing test is still reported before that exit |
 | 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 |
 
+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:
 
 | Script | Use it for |

package/docs/contributing/harness-routing-internals.md

@@ -3,7 +3,7 @@
 This page records how the KXM repository applies [harness routing](../reference/harness-routing.md) to its own work: the routes this checkout admits, its writer roster, its price catalog, and the developer roster policy that `just assign` and the dev helper enforce. It is maintainer material. The snapshots were captured on 2026-09-23 on one operator machine, from a source checkout where `node scripts/kxm.mjs` is the same program as `kxm`; they change whenever an admission changes.
 
 > [!IMPORTANT]
-> The files are the authority, not this page: `.kxm/routes.yaml`, `.kxm/roles/`, `.kxm/roster.yaml` and `.kxm/prices.yaml`. Product routing decisions are recorded under Tracking → Decided in `plans/implementation-plan.md`.
+> The files are the authority, not this page: `.kxm/routes.yaml`, `.kxm/roles/*.yaml`, `.kxm/models/*.yaml`, and `.kxm/prices.yaml`. Product routing decisions are recorded under Tracking → Decided in `plans/implementation-plan.md`.
 
 ## This checkout's routes and roster
 
@@ -59,9 +59,9 @@ On the capture machine, `kxm harness list` showed `claude` detected but logged o
 
 `.kxm/prices.yaml` is dated `2026-09-16`, so every current run records `providerMetadata.priceCatalogStale: true` and no list estimate. The list prices below come from `.kxm/models/inventory.yaml`, fetched `2026-09-16T14:54:53Z`, in USD per 1M tokens. The checkout has no routing records yet, so none of the examples has recorded latency; for latency, run a bounded side-by-side experiment and compare p50 and p95 in `kxm routing report`.
 
-## The developer roster (`.kxm/roster.yaml`)
+## The developer roster
 
-The issue-127 runner (`just assign`, see the [assignment runner](assignment-runner.md)) uses its own policy file, [`kxm.developer-roster.v1`](../reference/config-reference.md#kxmrosteryaml-kxmdeveloper-rosterv1). Routes there name the harness, the model and the vendor explicitly:
+The issue-127 runner (`kxm assign`, see the [assignment runner](assignment-runner.md)) reads `.kxm/roles/*.yaml` and `.kxm/models/*.yaml` at `refs/remotes/origin/main`. See [Developer assignment policy](../reference/config-reference.md#developer-assignment-policy). Routes there name the harness, the model and the vendor explicitly:
 
 ```yaml
   grok-native:
@@ -100,7 +100,7 @@ The product brake, the dev helper and the roster policy now agree on the vendor
 
 ## Worked examples on this checkout
 
-These extend the generic examples on the reference page with this checkout's admissions, developer-roster routes, readiness on the capture machine, and inventory prices.
+These extend the generic examples on the reference page with this checkout's admissions, developer policy routes, readiness on the capture machine, and inventory prices.
 
 ### Grok 4.6
 
@@ -174,19 +174,19 @@ The developer runner is stricter. Its only Pi writer is `openrouter/qwen/qwen3-c
 
 | Symptom | Cause | Fix |
 |---|---|---|
-| `pi brake: xai has a native harness; refusing Pi impersonation` | A dev-helper request routed a native vendor through Pi. | Use the native harness recipe instead: `just impl`, `just plan`, `just review-arch` or `just review-cli`. |
-| `Roster policy refused: native vendor cannot use Pi` | A `.kxm/roster.yaml` Pi route names a native vendor, as in `openrouter/x-ai/…` or `nous-portal/anthropic/…`. | Remove the route. Only a native harness route is valid for that vendor. |
+| `pi brake: xai has a native harness; refusing Pi impersonation` | A dev-helper request routed a native vendor through Pi. | Use the native harness through `kxm lane run <unit> --brief <file> --workflow review-arch-only`. |
+| `Roster policy refused: native vendor cannot use Pi` | A Pi route in `.kxm/models/*.yaml` names a native vendor, as in `openrouter/x-ai/…` or `nous-portal/anthropic/…`. | Remove the route. Only a native harness route is valid for that vendor. |
 | The dev helper refuses a codex route. | `codex` is logged in with an API key. | Run `codex login` with the ChatGPT flow. |
 
 For example, the native writer recipe:
 
 ```bash
-just impl brief.md
+kxm lane run <unit> --brief <file> --workflow implement-only
 ```
 
 ## Related
 
 - [Harness routing](../reference/harness-routing.md): the rules, the decision procedure and the generic examples
 - [Assignment runner](assignment-runner.md): the loop that enforces the developer roster
-- [Configuration file reference](../reference/config-reference.md#kxmrosteryaml-kxmdeveloper-rosterv1): the `kxm.developer-roster.v1` fields
+- [Configuration file reference](../reference/config-reference.md#developer-assignment-policy): the developer assignment policy fields
 - [Routing and cost telemetry contract](../contracts/routing.md): the routing record, cost basis and dev-helper telemetry

package/docs/glossary.md

@@ -423,7 +423,7 @@ A `kxm.role.v2` definition in `.kxm/roles/`, managed with `kxm role`, that descr
 
 ### Roster
 
-A list of allowed models. It means either a [role](#role)'s roster, or the developer roster `.kxm/roster.yaml` that the [assignment runner](contributing/assignment-runner.md) trusts to choose writers and critics. Neither one admits a route; see [admission](#admission).
+A list of allowed models. It means either a [role](#role)'s roster, or the developer roster in `.kxm/roles/*.yaml` and `.kxm/models/*.yaml` that the [assignment runner](contributing/assignment-runner.md) trusts to choose writers and critics. Neither one admits a route; see [admission](#admission).
 
 ### Route
 

package/docs/guides/agent-skills.md

@@ -1,6 +1,6 @@
 # Agent skills
 
-KXM ships a suite of Agent Skills that teach a coding agent how to use the `kxm` CLI and the `kxm_*` tools safely: which command owns a task, which verbs exist, and which steps belong to a person. This page is for anyone running KXM from Claude Code, Pi or Codex, and for contributors who edit the skills. Skills document the CLI; they grant no permission, admit no writer and replace no trusted `.kxm/roster.yaml` policy.
+KXM ships a suite of Agent Skills that teach a coding agent how to use the `kxm` CLI and the `kxm_*` tools safely: which command owns a task, which verbs exist, and which steps belong to a person. This page is for anyone running KXM from Claude Code, Pi or Codex, and for contributors who edit the skills. Skills document the CLI; they grant no permission, admit no writer and replace no trusted policy in `.kxm/roles/*.yaml` and `.kxm/models/*.yaml`.
 
 Governed skills that your own runs produce are a separate lifecycle; see [Governed skills](governed-skills.md).
 

package/docs/operations/backup-and-restore.md

@@ -15,7 +15,7 @@ KXM spreads state over six roots. Some of them move with environment variables,
 ```mermaid
 flowchart TB
   subgraph R["$R checkout root: the Git checkout, never moves"]
-    R1["Project definition: .kxm/project.yaml, config.yaml, agents/, models/, workflows/, gates.yaml, roles/, roles, routes.yaml, roster.yaml, prices.yaml, repo/, project/env.yaml"]
+    R1["Project definition: .kxm/project.yaml, config.yaml, agents/, workflows/, gates.yaml, .kxm/roles/, .kxm/models/, routes.yaml, prices.yaml, repo/, project/env.yaml"]
     R2["Durable records: .kxm/memory/, skills/, goals/, tasks/, candidates/"]
   end
   subgraph D["$D workspace: KXM_WORKSPACE_DIR or --workspace, default $R/.kxm"]
@@ -31,7 +31,7 @@ flowchart TB
     S2["hub-env.json, hub-binding.json, update.yaml, projects/HASH/repository-bindings.json"]
   end
   subgraph C["$C user config: KXM_USER_CONFIG_DIR, default ~/.config/kxm"]
-    C1["config.yaml, roles/, workflows/, roles, session.token"]
+    C1["config.yaml, workflows/, session.token. Checkout routing lives in .kxm/roles/ and .kxm/models/"]
   end
   subgraph T["$T federated telemetry: XDG_CONFIG_HOME/kxm/telemetry"]
     T1["model-metrics.jsonl, not written by any command today"]
@@ -71,13 +71,13 @@ The Runtime registry and the other projects' event stores are shared by every pr
 | `$S/runtime/registry.db` | Runtime registry: projects, their roots and home Runtime, the supervisor identity and claim | Only with `--all-projects` (`registry`) |
 | `$S/projects/<hash>/repository-bindings.json`, `$S/update.yaml` | Member repository paths; updater settings | No |
 | `$S/hub-env.json`, `$S/hub-binding.json`, `$C/session.token` | Credentials and the machine's hub binding | No; prefer regenerating secrets to copying them |
-| `$R/.kxm/` definition files and durable records | Project, roles, routes, prices, roster, memory, skills, goals, tasks, candidates | No; commit them to Git or copy the checkout |
+| `$R/.kxm/` definition files and durable records | Project, `.kxm/roles/`, `.kxm/models/`, routes, prices, memory, skills, goals, tasks, candidates | No; commit them to Git or copy the checkout |
 | Each member repository's `.kxm/repo/*.yaml` | Member definition and environment | No; they live in the member's own checkout |
 | `$W/worker-*.json`, `$W/pi-sessions/` | Worker routing and recovery manifests; Pi model history | No; manifests are required for resumable workers, Pi history is optional |
 | `$D/assets/`, `$D/logs/` | Retrospectives and evidence; logs and local usage accounting (`telemetry.jsonl`) | No |
 | `$C` | User-level roles, workflows and settings | No |
 
-A restore without `roster.yaml`, `routes.yaml` or `prices.yaml` comes back healthy but with different admission and cost behavior, so treat them as part of the backup even though they are plain files. `kxm improve report --out-dir` can write candidates outside `$R/.kxm/candidates/`; include that directory if you use it.
+A restore without `.kxm/roles/`, `.kxm/models/`, `routes.yaml`, or `prices.yaml` comes back healthy but with different admission and cost behavior, so treat them as part of the backup even though they are plain files. `kxm improve report --out-dir` can write candidates outside `$R/.kxm/candidates/`; include that directory if you use it.
 
 These files are disposable and need no backup: `hub.pid`, `hub.stop`, `worker-*.pid`, `session-brief.json`, `update-check.json`, `runtime/supervisor.token`, `runtime/supervisor.error`.
 
@@ -237,14 +237,14 @@ It restores the registry and every project's event store and sidecar. Every chec
 
 ### Restore ceilings
 
-A backup newer than this build is refused with `runtime_schema_newer` before any file changes. KXM has no migrations: an older backup restores, but its store then refuses to open with `runtime_schema_outdated`. Restore an older backup with the release that wrote it; see [Upgrade KXM](upgrade.md#understand-schema-changes).
+A backup newer than this build is refused with `runtime_schema_newer` before any file changes. Hub and event stores are not migrated: an older backup of those restores, then the store refuses to open with `runtime_schema_outdated`. A registry backup at schema 1 opens in place: existing rows stay, and each gains an empty `lane_of` column. Restore any other older backup with the release that wrote it; see [Upgrade KXM](upgrade.md#understand-schema-changes).
 
 The ceilings come from `KXM_BACKUP_CEILINGS` in `plugins/kxm/src/database.ts` and match each store's own schema version:
 
 | Store id | Highest schema version restored |
 |---|---|
 | `hub-store` | 5 |
-| `registry` | 1 |
+| `registry` | 2 |
 | `events:<key>` | 7 |
 | `binding-store` | 1 (no current store uses it) |
 
@@ -280,7 +280,7 @@ Test a full restore on a spare machine before you rely on it, and repeat the tes
 | `backup_no_stores` | No `.kxm/state/kxm.db` under the checkout (or it was moved with `KXM_STATE_DIR` or `KXM_DATA_PATH`) and no event store for this checkout under the user state root | Run inside the checkout; copy a relocated database with the stopped-state procedure |
 | `Backup is incomplete (<n> omitted); not ok:`, exit 1 | A store or sidecar could not be copied, or appeared while the backup ran | Fix the source named after `omitted`, then run `kxm backup` again |
 | `restore_incomplete` | The manifest records `complete: false` | Restore a complete backup; the partial one is not restorable |
-| Runs are missing, or the Runtime refuses the project with `project_home_conflict`, after a restore | The checkout moved to another absolute path, and the registry still binds the project to the old one | Keep the checkout at its original path and restore there |
+| Runs are missing, or the Runtime refuses the project with `project_home_conflict`, after a restore | The checkout moved, and a live registration still points at the old directory. A missing directory is replaced on the next registration. A second live checkout that is not a worktree of the registered repository is still refused | Keep a live checkout at its original path. A worktree of that repository registers as a lane |
 | `restore_requires_all_projects` | The backup holds the Runtime registry or another project's event store: it was taken with `--all-projects`, or by a build from before backups were scoped | Pass `--all-projects` if rolling back every project is what you want; otherwise restore a backup taken without it |
 | `restore_runtime_running` | The Runtime supervisor is running | Run `kxm runtime stop`, pause whatever restarts it, then restore |
 | `restore_runtime_unverified` | `$S/runtime/registry.db` cannot be read, so restore cannot tell whether the supervisor is running | Stop the Runtime, move the registry aside, then restore; an `--all-projects` backup brings the registry back |

package/docs/operations/upgrade.md

@@ -84,7 +84,7 @@ kxm update pi --models             # refresh Pi model catalogs
 
 ## Understand schema changes
 
-Each store records a schema version, and KXM never upgrades a store in place.
+Each store records a schema version. Hub stores and Runtime event stores are never upgraded in place. The Runtime registry copies schema 1 forward to schema 2 and keeps every existing row.
 
 | Store | Location | Created by |
 |---|---|---|
@@ -93,7 +93,7 @@ Each store records a schema version, and KXM never upgrades a store in place.
 | Run event store | `runtime/projects/<key>/run-events.db` under the user state root | The Runtime supervisor |
 
 - A store **newer** than the running release refuses to open (`runtime_schema_newer`). Do not delete it; run the release that created it, or upgrade.
-- A store **older** than the running release also refuses to open (`runtime_schema_outdated`), and the error names the store. There is no migration.
+- A hub store or event store **older** than the running release also refuses to open (`runtime_schema_outdated`), and the error names the store. There is no migration for those stores. A registry at schema 1 opens, and its rows stay.
 
 When a release changes a schema, either stay on the old release, or accept a fresh store: stop the owner, move the old file aside (keep it with your backup), and start the owner, which re-creates it. `kxm init` rebuilds no database. A fresh hub store loses message and workflow history; a fresh Runtime store loses local run history. Check the changelog for schema changes before you upgrade.