@kontextmind/kxm 0.6.0

package/docs/vnext/lifecycles.md

@@ -0,0 +1,235 @@
+# Durable lifecycles
+
+All transitions are append-only events. A projection may materialize the
+current state, but it cannot create a transition absent from the home Runtime's
+event sequence.
+
+## Event ordering
+
+Each run has a strictly increasing 1-based `sequence` assigned by its home
+Runtime. Repeating an idempotent command returns the prior result and does not
+append a duplicate semantic event. The hub deduplicates synchronized events by
+`{projectId, runId, sequence}`.
+
+UTC timestamps are audit/display data. Durations and timeouts use the Runtime's
+monotonic clock and persisted duration samples.
+
+## Run request
+
+A hub run request is coordination state, not execution state.
+
+```text
+queued → offered → accepted
+   │        │         └── creates one home-owned run
+   │        ├── declined
+   │        └── expired
+   └── cancelled
+```
+
+Acceptance is atomic with reserving a unique run ID and immutable
+`homeRuntimeId`. A repeated request key returns the existing acceptance.
+
+## Run
+
+```text
+created → preparing → running ↔ waiting
+                         │          │
+                         ├── blocked_uncertain
+                         ├── cancelling → cancelled
+                         ├── completed
+                         └── failed
+```
+
+| State | Meaning | Allowed exits |
+|---|---|---|
+| `created` | Identity, owner, and pinned revisions recorded | `preparing`, `cancelled`, `failed` |
+| `preparing` | Inputs, capabilities, workspaces, secrets, and models are being verified; the run plan pin is recorded here | `running`, `cancelled`, `failed` |
+| `running` | One top-level step is active | `waiting`, `blocked_uncertain`, `cancelling`, `completed`, `failed` |
+| `waiting` | No model/process compute is required; a declared signal, lease, or approval is pending | `running`, `blocked_uncertain`, `cancelling`, `completed`, `failed`, `cancelled` |
+| `blocked_uncertain` | An effect outcome cannot be proven | `running`, `cancelling`, `failed` |
+| `cancelling` | Cancellation has been durably requested and child processes are draining | `cancelled`, `blocked_uncertain`, `failed` |
+| `completed` | Declared success terminal reached | None |
+| `failed` | Declared failure or exhausted budget reached | None |
+| `cancelled` | Cancellation completed without unresolved owned effects | None |
+
+Operator `cancelled` from `created` or `preparing` requires a recorded
+`run.cancel_requested`. A compiled selected `terminalStatus=cancelled` may
+still complete from `running` without that operator event.
+
+A run cannot move to another Runtime by editing a projection or hub record.
+
+## Step and step attempt
+
+Only one top-level step is active. Entering a step creates a new positive
+`stepAttempt` number.
+
+```text
+pending → preparing → running ↔ waiting
+                         │          │
+                         ├── blocked_uncertain
+                         ├── passed
+                         ├── failed
+                         ├── skipped
+                         └── cancelled
+```
+
+A typed transition from a terminal step attempt selects the next step or a run
+terminal. A back-edge creates a fresh step attempt and fresh assignment set.
+`step.maxAttempts` bounds all entries/retries of that step for the run in
+addition to global and per-edge transition budgets. Evidence is attempt-bound
+unless its declaration explicitly allows reuse.
+
+`skipped` is legal only when a validated workflow declares the skip outcome and
+proves that no required approval or gate is bypassed.
+
+## Assignment
+
+An assignment is logical work and may have more than one physical attempt.
+
+```text
+created → accepted → dispatched → executing → result_recorded → terminal
+                 ▲                 │       │
+                 │                 ├── reattaching
+                 └── retry_pending─┘       └── blocked_uncertain
+```
+
+| State | Durable condition |
+|---|---|
+| `created` | Assignment identity, purpose, bounds, and requested evidence recorded |
+| `accepted` | Runtime has resolved policy, agent, model, repository, tools, secrets, and executor |
+| `dispatched` | Attempt identity and dispatch intent persisted before process start |
+| `executing` | Invocation admitted and the attempt capability is usable. This slice is in-process (no OS process identity yet); later recovery still requires exact process/session proof |
+| `reattaching` | Runtime is verifying the same process/session and event cursor |
+| `result_recorded` | Structured attempt result and referenced receipts are durably stored |
+| `retry_pending` | Policy permits another physical attempt after the prior attempt became terminal |
+| `blocked_uncertain` | A dependent effect cannot be reconciled safely |
+| `terminal` | The logical assignment outcome is final and immutable: passed, failed, or cancelled |
+
+`assignmentId` remains stable. A retry moves the nonterminal assignment through
+`retry_pending` to `accepted`, creates a new `attemptId`, and never rewrites or
+exits the previous attempt's terminal state. The effective
+`assignments.maxAttemptsPerAssignment` bounds physical attempts; the Runtime
+may retry only outcomes and effect classes declared safe by trusted policy.
+
+## Assignment attempt
+
+```text
+created → starting → executing → settling → terminal
+                       │    │
+                       │    ├── reattaching → executing
+                       │    └── blocked_uncertain
+                       └── connection_lost
+```
+
+Reattachment to the same attempt requires all of:
+
+- exact Runtime, run, assignment, and attempt identity;
+- exact physical process or harness session identity;
+- compatible executor/helper generation;
+- valid last durable event cursor;
+- no replacement process or attempt;
+- unchanged scope epoch and grants.
+
+If those facts cannot be proven, the Runtime either creates a new attempt after
+safe reconciliation or enters `blocked_uncertain`.
+
+## Dynamic assignment panel
+
+Every step has effective bounds:
+
+```text
+minimum ≤ target ≤ maximum
+maxParallel ≤ maximum
+```
+
+The coordinator may create assignments only until `maximum`. Every assignment,
+including one whose provider work began but failed to start fully, counts
+against the step attempt's maximum. Each assignment also has a compiled physical
+attempt ceiling; omitting a project override uses the step-kind default rather
+than an unbounded retry policy.
+
+Fail-closed compiled defaults:
+
+| Step kind | Step attempts | Assignments | Physical attempts per assignment | Join |
+|---|---:|---:|---:|---|
+| Single agent | 1 | Exactly 1 | 1 | `all` |
+| Deterministic gate | 1 | Exactly 1 | 1 | `all` |
+| Human approval | 1 | Exactly 1 authorized decision | 1 | `all` |
+| Wait | 1 | Exactly 1 signal | 1 | `all` |
+| MOA | 1 | Exactly 1 unless the step declares a panel | 1 | `all` |
+
+Current contract (`kxm.workflow.v1`): an omitted `assignments` block resolves for every kind to minimum 1, target = minimum, maximum = target, maxParallel = maximum, one physical attempt per assignment; an omitted `join` resolves to `all`. The loader checks these numbers and the compiler mirrors them exactly; the compiler never resolves a larger ceiling than the loader validated. A MOA step must declare its panel explicitly (see `fix.yaml`). The kind-level MOA default of target 3, minimum 2, maximum 3, all-settled with two valid completions is a Phase 7 change made to schema, loader, compiler, and this table in one change.
+
+Templates may materialize larger reviewed attempt ceilings. No omitted field ever
+means unlimited retries.
+`first-success` is valid only for an explicitly speculative, safely cancellable
+step. It is invalid for independent review.
+
+## Effect
+
+```text
+intent_recorded → dispatched → observed → receipt_recorded → settled
+                         │          │
+                         └──────────┴── blocked_uncertain
+```
+
+The intent, effect class, idempotency key, and expected receipt query are
+recorded before dispatch. See [Effects and recovery](effects-and-recovery.md).
+
+## Delivery
+
+A multi-repository delivery is explicitly non-atomic.
+
+```text
+planned → preparing → delivering → completed
+                         │    │
+                         │    ├── partial
+                         │    ├── blocked_uncertain
+                         │    └── failed
+                         └── cancelled
+```
+
+Each repository has its own result and receipt. `partial` is a delivery-panel
+state, not an individual assignment-result status. It never projects as
+`completed`; remediation or compensation is explicit. Conversely, a manifest
+with any `delivered` repository cannot project as `failed`, `cancelled`, or
+`blocked_uncertain`: it is `partial` until the delivered work is explicitly
+accounted for. Every `delivered` repository has at least one receipt.
+
+## Synchronization
+
+```text
+local_event → sync_transform → outbox_pending → acknowledged
+                    │                 │
+                    └── omitted       ├── retry_pending
+                                      └── rejected
+```
+
+`omitted` means the event contains no sync-worthy fields under policy. A
+schema-invalid or unsafe transformation never enters the outbox. `rejected`
+requires operator-visible diagnostics; the local run remains authoritative.
+
+## Session lifecycle
+
+A physical agent session is reusable only within one exact run and compatible
+scope epoch.
+
+```text
+created → active ↔ idle → closed
+             │       │
+             └── rotate_scope → closed + new scope epoch
+```
+
+Scope rotation occurs before an assignment with narrower or incompatible
+repository, secret, tool, model, executor, or disclosure scope is dispatched.
+
+## Recovery invariants
+
+1. No terminal state exits.
+2. No sequence number is reused.
+3. No new process inherits an old `attemptId`.
+4. No prior step-attempt evidence silently satisfies a later attempt.
+5. No coordinator command expands a compiled policy ceiling.
+6. No unknown effect is replayed automatically.
+7. No session crosses a run or incompatible scope epoch.
+8. No hub projection changes home-owned run state.

package/docs/vnext/migration.md

@@ -0,0 +1,220 @@
+# Migration and compatibility matrix
+
+KXM vNext is introduced beside the current v0.5 transport/workflow surfaces.
+Presence of vNext documents does not activate new behavior.
+
+## Surface matrix
+
+| Current surface | vNext target | Migration rule |
+|---|---|---|
+| `.kxm/config/agents.json` aggregate roster | `.kxm/agents/<id>.yaml` individual definitions | Split records, infer ID from filename, preserve unrecognized fields in a migration report rather than silently dropping them |
+| `gates.json` descriptive records | Workflow step/gate references plus registered deterministic adapters | Map only implemented gates; report names with no runner |
+| `KXM_WEBHOOK_WORKFLOWS` inline JSON | `.kxm/workflows/<id>.yaml` | Materialize secret-free behavior; convert secret fields to references |
+| `KXM_WEBHOOK_WORKFLOWS_FILE` JSON array | Individual workflow YAML files | Split definitions and validate typed transitions |
+| `.kxm/config/workflows/*.json` including `/fix` | `.kxm/workflows/<id>.yaml` | Preserve typed transitions, immutable reproduction oracle, approved-plan hash, plan-hash requirements, producer policies, and attempt/transition budgets |
+| Hub-selected project from environment | Git project identity plus Runtime-local binding | Detect and ask on ambiguity; do not derive durable identity from directory basename |
+| Long-lived manually started Pi workers | Runtime-managed run-scoped sessions | Existing worker mode remains available during compatibility release |
+| Shared/off workflow Pi history | `{run, agent, instance, scopeEpoch}` sessions | Never import shared conversation history into a narrower run scope |
+| Hub-owned workflow state | Home Runtime event log with hub projection | Import completed history as legacy records; active-run cutover requires quiescence |
+| SQLite schema v3 `kxm.db` | Runtime registry, per-project event stores, hub registry/project stores | Copy through versioned migration; never mutate the only database in place |
+| Full peer message bodies in hub DB | Summary-first sync events | Existing bodies remain protected legacy data and are not re-emitted automatically |
+| Project tokens/manual environment auth | Runtime enrollment and scoped credentials | Preserve current mode until enrollment is confirmed; never copy tokens into Git |
+| `.kxm/config/env.example` | Built-in defaults plus optional scoped env YAML | Import only explicit portable differences; secrets become references |
+| Retired product-prefixed init (empty directories) | Unified `kxm init` create/join/migrate/repair | Removed; `kxm init` is the only entry and the old init command fails closed |
+| `kxm session start` manifest only | `kxm run` executable run | Do not reinterpret old session manifests as completed or active runs |
+| Existing context items and journal | Pinned memory revisions and candidates | Preserve provenance/authority floors; no automatic executable promotion |
+
+## Compatibility releases and activation
+
+Local Runtime support may ship publicly before hub vNext, but it remains beside
+existing hub contracts and stores. Old command names are not preserved. A project
+activates `kxm.*.v1` only by an explicit successful `kxm init`/migration receipt;
+file presence alone never activates it. Legacy hub runs continue on the legacy
+engine.
+
+When Phase 8 activates hub vNext, at least one hub transition release provides:
+
+- current `mesh_*` peer tools;
+- current hub APIs behind a compatibility adapter;
+- legacy JSON configuration read support while vNext writes only YAML;
+- current completed workflow history read/export support;
+- Runtime-managed vNext runs in new event stores with new identities;
+- CLI labels for legacy versus vNext state;
+- no implicit movement of active runs between engines.
+
+Before activation, a repository MUST NOT use legacy and vNext definitions with
+the same normalized identity. Validation reports the conflict and requires an
+explicit migration choice. After a migration receipt activates the vNext copy,
+the matching legacy definition is read-only compatibility input and cannot be
+selected for a new vNext run.
+
+## Migration commands
+
+```text
+kxm migrate plan
+kxm migrate apply [--decisions <file>] [--project-id <id>] [--name <name>]
+kxm migrate verify
+```
+
+`kxm init` invokes the planning flow when it detects legacy state.
+
+**Implementation status (Phase 1 slice):** the commands above are implemented
+for **configuration migration only** — legacy `agents.json`, `gates.json`, and
+workflow-definition JSON under `.kxm/config/`. Database/WAL migration,
+active-run cutover, session migration, and rollback orchestration remain
+later-phase work and are not performed by these commands.
+
+### Plan
+
+Produces a secret-free `kxm.migration-plan.v1` report containing:
+
+- detected source files with sha256 and byte counts plus a combined
+  `sourceDigest`;
+- target resource paths with their rendered content hashes;
+- deterministic ambiguities, each with a stable decision key and the allowed
+  values: terminal status for legacy `$terminal` edges, per-edge budgets for
+  unbounded back-edges, missing global transition budgets, evidence-policy
+  strengthening (`replied` → `passed`), foreign producer identities, secret
+  field drops, narrowed permission ceilings, and identity normalization;
+- unrecognized or unmappable fields preserved as hashed `unmapped` entries
+  (sensitive values are hashed, never copied);
+- old-to-new identity renames;
+- the resulting permission changes tied to their decision keys.
+
+It changes nothing: no writes, no locks, no staging, no local state.
+
+### Decisions
+
+`kxm migrate apply` requires every ambiguity to be resolved. Decisions are
+supplied either as a reviewed `kxm.migration-decision.v1` YAML file
+(`--decisions <file>`) binding the exact `projectId`, `projectName`, and
+`sourceDigest` of the plan, or programmatically. Unknown decision keys and
+values outside the plan's allowed set fail closed before any write.
+
+### Apply
+
+1. Acquire the project mutation lock.
+2. Recompute the plan and re-check the decision binding (project, source
+   digest, key set, allowed values).
+3. Validate every converted resource against its exact schema and the whole
+   bundle against semantic rules.
+4. Refuse to overwrite any existing target path.
+5. Install resources with durable writes (fsync + rename).
+6. Load and validate the complete installed bundle.
+7. Write a hash-linked `kxm.migration-receipt.v1` binding source hashes,
+   decision digest, target configuration revision, and installed resource
+   hashes; the receipt is self-hashed.
+8. Re-load the mixed tree: legacy inputs remain intact but receipt-pinned
+   read-only; `loadVnextProject` accepts coexistence only through the
+   verified receipt.
+
+Re-applying with the receipt present is an idempotent no-op
+(`already-migrated`). Editing a legacy source after the receipt makes both
+`loadVnextProject` and `kxm migrate verify` fail closed.
+
+### Verify
+
+`kxm migrate verify` reopens the target, re-checks the receipt self-hash,
+re-hashes legacy sources, and compares the target configuration revision and
+installed resource bytes against the receipt. It performs no writes.
+
+## Database migration
+
+Before any database operation:
+
+- verify SQLite `user_version`;
+- refuse a newer unknown version;
+- checkpoint WAL or copy using the SQLite backup API;
+- include `-wal` state correctly rather than copying only the main file;
+- verify backup integrity;
+- record source and target hashes.
+
+Current agents, messages, workflow runs, journal entries, and context items are
+imported as typed **legacy records**. They are not fabricated into fine-grained
+vNext run events whose original ordering was never observed.
+
+Completed legacy runs remain queryable. A legacy active run must either finish
+on the old engine or be explicitly cancelled/exported; it is not resumed as a
+vNext run.
+
+## Configuration migration
+
+The implemented converter:
+
+- reads legacy JSON with byte/depth/node bounds and token-level duplicate-key
+  rejection; linked files and linked `workflows/` directories are never
+  traversed for authoritative bytes;
+- normalizes case-insensitive identities, records explicit old-to-new renames,
+  and rejects case-fold collisions and destination-invalid names;
+- splits `agents.json` into `.kxm/agents/<id>.yaml` resources and emits one
+  `.kxm/models/<id>-primary.yaml` profile per agent whose legacy record pinned
+  a provider/model pair with a thinking level;
+- maps roster-only concepts (`ownership`, `host`, top-level `project`) into
+  hashed `unmapped` report entries rather than dropping them silently;
+- maps workflow stages to agent steps, preserves `reproOracle`, `planHash`,
+  `requirePlanHash`, typed transitions, immutable oracles, and global
+  transition budgets, and widens evidence-carrying steps into an explicit
+  assignment pool containing their producers;
+- converts legacy peer-reply evidence policies (`acceptedStatuses:
+  ["replied"]`) into vNext producer policies requiring `passed` only through
+  an explicit operator decision;
+- requires decisions for: every legacy `$terminal` edge's terminal status
+  (legacy completed the run even on failure outcomes), every unbounded
+  back-edge's per-edge budget, missing global budgets, foreign producer
+  identities, secret-field drops, unimplemented gates, and each narrowed
+  permission ceiling;
+- never copies secret values or environment indirections; webhook secret
+  fields are hashed into the report and dropped by explicit decision;
+- records template provenance only for files whose exact generated baseline is
+  known; migrated files carry no template provenance and are never
+  retroactively adopted;
+- validates the entire target project (exact schemas plus semantic rules)
+  before installation and shows the Git diff through normal review.
+
+Unknown data is preserved in the migration report, not placed into a generic
+runtime extension map.
+
+Legacy typed workflows have a global transition budget but may lack vNext
+per-back-edge caps. The migrator MUST NOT invent those caps silently. `migrate
+plan` lists every affected edge and a proposed bounded value; `migrate apply`
+requires the values in an operator-approved migration decision. The committed
+vNext `/fix` fixture is one reviewed resolution, not a generic automatic rule.
+
+Stage IDs, outcome keys, evidence keys, oracle references, plan-hash references,
+and eligible producer identities are preserved by default. Any unavoidable
+normalization appears as an explicit old-to-new mapping and rewrites all bound
+references atomically.
+
+## Session migration
+
+Old shared Pi histories may contain content from broader scopes. They remain
+archived under the old worker binding and are never selected for a vNext run.
+The first vNext physical session starts clean. Durable facts must come from Git,
+workflow evidence, artifacts, or promoted context rather than conversation
+history.
+
+## Rollback
+
+Rollback is supported until the operator accepts the migration receipt and
+starts a permission-expanding vNext-only run.
+
+Rollback:
+
+1. stop vNext writers;
+2. preserve vNext stores as diagnostic artifacts;
+3. restore the recorded legacy configuration selection and database path;
+4. restart only compatible legacy processes;
+5. verify legacy health and record rollback evidence.
+
+Events created only by vNext are not reverse-translated into fabricated legacy
+workflow history.
+
+## Removal gate
+
+Legacy readers and command aliases are removed only after:
+
+- at least one compatibility release;
+- migration telemetry shows no material unmapped cases;
+- package/install/Windows tests cover vNext;
+- operator documentation and rollback paths are proven;
+- removal is announced in the changelog.

package/docs/vnext/routing.md

@@ -0,0 +1,184 @@
+# Routing and cost telemetry
+
+> **Status.** `kxm.routing-record.v1` is parse-only for legacy records.
+> `kxm.routing-record.v2` is **implemented and active**: emitted at engine
+> attempt settlement (`routing.attempt.recorded` event in `plugins/kxm/src/vnext-engine.ts`),
+> enforced with fail-closed `costBasis` requirement. Price catalog `.kxm/prices.yaml`
+> (`kxm.prices.v1`) is implemented, dated, and hashed. `kxm routing report`
+> is implemented (`plugins/kxm/src/routing.ts`) and ranks routes quality-first,
+> then cost per accepted attempt, never ranking unknown cost cheapest and
+> reporting metered, unmetered, and unknown populations separately. Dev-helper
+> telemetry (`scripts/harness-run.mjs`) and the issue 127 assignment runner
+> (`scripts/assignment-run.mjs`, `just assign`) are implemented developer tools.
+
+This document describes what the tree does today versus what Tracking still
+plans. It does not invent prices or close product enums.
+
+## Implemented: v1 record
+
+Schema id: `kxm.routing-record.v1` (`plugins/kxm/src/routing.ts`).
+
+Always present or defaulted by `parseRoutingRecord`: `schema`,
+`behavioralHashVersion`, `behavioralSha256`, `skills` (default `[]`),
+`contextItemIds` (default `[]`), `retries` / `transitions` /
+`humanInterventions` (default `0`).
+
+Optional when present and valid: `workflowRunId`, `stageId`, `attempt`,
+`requestedModel`, `effectiveModel`, `reasoningEffort`, `agentRole`,
+`rolePromptSha256`, `contextPolicyVersion`, `toolPolicyVersion`,
+`workflowDefinitionSha256`, `verifierConfigSha256`, `tokensIn`, `tokensOut`,
+`cacheReadTokens`, `costUsd`, `verifierOutcome`, `finalOutcome`, bounded
+`providerMetadata`.
+
+The behavioral hash covers the configuration tuple (normalized models, role,
+prompt/skill/tool/workflow/verifier hashes). Outcome telemetry (tokens, cost,
+retries, outcomes) is outside the hash.
+
+**No built-in product producer.** The worker envelope validates a `routing`
+field when present. Nothing in `plugins/kxm/src` or `scripts/kxm-worker.mjs`
+writes a record. Repo records are test-built. External JSONL can be ingested.
+
+v1 has **no dedicated fields** for harness, provider, latency, cost basis,
+cache-write tokens, or context occupancy. Bounded `providerMetadata` may
+carry extra keys (at most 32; values are strings, numbers, or booleans;
+`prompt`/`body`/`content`/`message` keys are rejected), but those keys are
+**not standardized** and `kxm routing report` does not read them.
+
+`kxm routing report` reads `telemetry.jsonl`, groups by behavioral hash, sorts
+by run count (then hash), and sums missing `costUsd` as **zero**. That silent
+underquote is why the report is **not** a ranking source.
+
+## Implemented: dev helper telemetry
+
+`scripts/harness-run.mjs` emits `kxm.harness-result.v2` after a
+`kxm.harness-request.v1`. It is not a Phase 11 adapter and is not persisted as
+a routing record. Helper `status` is transport-only (`completed`, `failed`,
+`interrupted`) and must not be read as product `routing-record.v1`
+`finalOutcome`. Obsolete `kxm.harness-result.v1` files are diagnosed (file,
+observed known schema or `unrecognized`, obsolete schema id) and left
+untouched; there is no v1 parser or upgrade lane. Public result fields are
+a closed allowlist with type checks (no arbitrary objects in scalar
+positions); raw model/stdio text is not copied into metadata.
+
+Observed normalization (not an invoice; none of these paths reconcile
+against an invoice or usage API):
+
+- Token basis is `cumulative`. Context occupancy is always `unknown`.
+  Values above the routing v1 int cap stay in metadata and are not clamped.
+- Helper cost-basis labels are `provider-reported`, `list`, `unmetered`, and
+  `unknown`. `billed` is reserved for invoice provenance and is **not**
+  emitted here. `just runs` can still print a `billed` label if a v2 file
+  already has that string.
+- Claude/Grok (`normalizeClaudeOrGrok`): when the payload has a provider
+  cost, that number is copied into **both** `costUsd` and
+  `providerReportedCostUsd`. Explicit `modelUsage` `costBasis: "list"` stays
+  `list`. Grok `total_cost_usd` without that list basis is
+  `provider-reported`. After parse, subscription Claude
+  (`authStatus.method === "claude.ai"`) sets `costBasis` to `unmetered` and
+  **clears `costUsd`**, leaving `providerReportedCostUsd` when it was present.
+- Pi (`normalizePi`): sums `usage.cost.total` from assistant
+  `message_end` events into `costUsd` only. Basis is `list` when that
+  aggregate exists, otherwise `unknown`. There is **no**
+  `providerReportedCostUsd` field on this path.
+- Codex (`normalizeCodex`): emits `costBasis: "unmetered"` (empty payload
+  is `unknown`). Root-verified helper auth preflight permits Codex
+  **ChatGPT only** (`scripts/harness-run.mjs` ChatGPT login parse). The
+  post-normalize ChatGPT branch also clears `costUsd`. Do not invent an
+  API-key billing path here; B3 inventory of other Codex surfaces is a
+  **separate** product/inventory question, not this helper.
+- Formatter `formatRunCost` still prints `billed $…` when a listing file
+  already has `costBasis: "billed"`. The helper itself does not emit that
+  label. That is display of a supplied label, not invoice reconciliation.
+
+Do not relabel provider-reported or list-basis amounts as billed. Partial
+usage after failure or interruption is kept and marked `usagePartial`;
+missing counters stay absent, not zero.
+
+## Implemented/unreleased: assignment runner (issue 127)
+
+`scripts/assignment-run.mjs` is the normal **dev** entry. It is not `kxm run`
+and does not replace Phase 3/4 gates.
+
+Working commands (absolute paths; flags from the script, not invented):
+
+```text
+just assign /abs/manifest.json
+# node scripts/assignment-run.mjs run --manifest /abs/manifest.json
+
+just witness /abs/record-dir
+# witness --record-dir /abs/record-dir
+
+just attribute /abs/task-dir /abs/record-dir orchestration /abs/note.txt
+# attribute --task-dir --record-dir --class --explanation-file
+
+just observe-cost /abs/task-dir /abs/observation.json
+# observe-cost --task-dir --input
+
+just accept /abs/task-dir <commit> /abs/writer-record /abs/arch-review /abs/cli-review
+# accept --task-dir --commit --record-dir --critic --critic
+# 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>
+just change-report /abs/task-dir
+```
+
+`just impl|plan|review-arch|review-cli` remain harness transport. They do not
+create assignment identity, witness receipts, or `accepted.json`.
+
+Distinctions the report and docs must keep:
+
+- **Manifest / current plan / gate / acceptance / cost** are different
+  records. Completions are not acceptance. Witness receipts are not critic
+  PASS. `attribute` history does not edit `completion.json`. Cost-only
+  imports never gain witness or acceptance eligibility.
+- `change-report` separates provider-reported sums, list estimates,
+  unmetered, unknown, not-dispatched (`provider_calls` 0), and partial
+  markers. Missing is not `0`. Unmetered is not free. Cumulative tokens are
+  not context occupancy. True elapsed time is separate from summed latency
+  and summed witness duration. The effort table is descriptive, not a
+  ranking. Orchestration/root usage is unavailable unless imported.
+- Observed PR/CI identifiers are unvalidated observations.
+- Private handoff notes live in `attribute` explanations and private model
+  summaries; the report references them and does not print the prose.
+
+Evidence-informed **effort defaults** for transport recipes and operator
+manifests: medium implementation/planning/architecture, low CLI review. Not a
+learned policy and not a catalog feed. Phase 9 may use this report to
+**propose** harness or model changes; activation still requires Git review.
+
+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.
+
+## Implemented: v2 record
+
+Schema id: `kxm.routing-record.v2` (`plugins/kxm/src/routing.ts`).
+
+Fields carried on `RoutingRecordV2`:
+
+- Identity & scoping: `schema`, `recordedAt`, `project`, `runId`, `stepId`, `assignmentId`, `attemptId`.
+- Routing configuration: `harness`, `provider`, `requestedModel`, `effectiveModel`, optional `thinking`, optional `agentRole`, `behavioralSha256`.
+- Execution metrics: `latencyMs`, `contextTokens`, `tokensIn`, `tokensOut`, `cacheReadTokens`, `cacheWriteTokens`.
+- Outcomes: `verifierOutcome` (`passed` | `warning` | `failed`), `finalOutcome` (`accepted` | `blocked` | `failed` | `pending`), `retries`, optional `transitions`, optional `humanInterventions`, optional `providerMetadata`.
+- Cost accounting: `costBasis` (`"metered" | "unmetered" | "unknown"`), `costUsd` (required when metered), optional `priceRef`.
+
+The vNext engine settle transaction appends a `routing.attempt.recorded` event carrying the v2 record and refuses to settle without a valid `costBasis`. Attempt dispatch enforces `limits.maxModelCost` against metered cost before invocation (`budget_model_cost`).
+
+## Implemented: report and price catalog
+
+- **Price catalog:** `.kxm/prices.yaml` (`kxm.prices.v1`, dated and hashed) defines input, output, cache-read, cache-write rates, and context tiers for active models. Missing rows or uncataloged models evaluate to `costBasis: "unknown"`.
+- **Ranked report:** `kxm routing report` (`plugins/kxm/src/routing.ts`, CLI command `kxm routing report`) groups records by `(harness, model, thinking, role)`.
+- **Ranking order:** Quality first (`verifyPassRate` descending, then `reworkRate` ascending where rework measures back-edge re-entries `transitions > 0`), followed by `costPerAcceptedUsd` ascending.
+- **Underquote prevention:** Routes with unknown cost are flagged (`*`) and **never ranked cheapest**, eliminating silent underquoting.
+- **Population separation:** Reports metered cost, unmetered attempt counts, unknown-cost attempt counts, and quota-exhausted attempt counts as separate metrics rather than a single misleading total.
+- **List prices flag:** Supports `--equivalent-list-cost` / `--list-prices` to display estimated list rates for comparison alongside actual recorded spend.
+- **Post-MVP:** Dynamic catalog price feeds (`kxm update --models`), budget roll-over, and automated promotion of repeat successes into workflow gates.
+
+## Precedence
+
+[AGENTS.md](../../AGENTS.md) and
+[Tracking](../../plans/implementation-plan.md#tracking-working-tree-not-a-release)
+win where they differ from historical 2026-09-04 reviews.
+Issue 86 stays open for later-phase remainder (see Tracking).