@kontextmind/kxm 0.7.165 → 0.7.167

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

package/CHANGELOG.md

@@ -6,6 +6,22 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Added
 
+- **Hub project identity and its access key live in `.kxm/config.yaml`.**
+  `hub.local` and `hub.cloud` hold the URL, the project id to present, and a
+  key reference (`key.op` is an `op://` reference, `key.env` is an environment
+  variable name). A literal token is refused. `op read` runs at use time and
+  the resolved value is not saved. The same order is used everywhere: flag,
+  `KXM_PROJECT`, the active mode's config project, `.kxm/project.yaml`, the
+  package name, then the directory name. `kxm hub bind` and
+  `kxm hub bind --cloud` write the non-secret fields, and `kxm hub view`
+  prints the mode, URL, project id, and key source. The hub's
+  `hub.projects` map uses the same references. `KXM_PROJECT_TOKENS` still
+  replaces that map. Setups whose hub map is keyed by the package name should
+  set `hub.local.project` or `hub.cloud.project` to that name, or keep passing
+  `KXM_PROJECT`: a checkout with `.kxm/project.yaml` otherwise sends that id
+  and gets `project_token_missing`. See
+  [Operate a KXM hub](docs/operations.md#hub-identity-in-config).
+
 - **`kxm hub bind --cloud` attaches a client to a remote hub reached through a loopback forward.**
   The binding records `--token-env` and/or `--token-command` and never the token.
   Later commands, including the environment for a Pi worker, use that source and

package/docs/README.md

@@ -117,6 +117,7 @@ KXM connects coding agents through a durable, authenticated [hub](glossary.md#hu
 | [KXM terminal components](contributing/tui-components.md) | Maintainers, integrators | The panel kit behind `kxm dash` |
 | [Repository work delivery skill](contributing/repo-work-delivery.md) | Contributors | The repository-local skill for delivering a change |
 | [Operating rules](contributing/operating-rules.md) | Agents, maintainers | The operator's standing instructions, dated, and where each is enforced |
+| [Decisions](contributing/decisions.md) | Agents, maintainers | Medium-or-higher decisions from automated work, with weights and evidence |
 | [Learnings](contributing/learnings.md) | Agents, maintainers | Durable lessons from running the writer, landing, and docs loops |
 | [Artifact templates](templates/README.md) | Workflow authors | Document templates and where workflows use them |
 

package/docs/architecture/hosted-direction.md

@@ -2,8 +2,11 @@
 
 Target. This page is a direction, not a live deployment.
 
-Read from `plans/plan-per-tenant-hosting.md`. `plans/plan-greenfield-infra.md`
-is not in this checkout.
+Read from `plans/plan-per-tenant-hosting.md`.
+`plans/plan-greenfield-infra.md` is in this checkout as a `kxm.doc.v1`
+stub (status draft, authority instruction): the long-form proposal was
+never committed, and the canonical facts below come from the
+implementation-plan greenfield bullets.
 
 ```mermaid
 flowchart LR
@@ -44,8 +47,10 @@ roadmap question. The tracker wins.
 
 ## Greenfield infra plan
 
-`plans/plan-greenfield-infra.md` is not observed from this checkout. Its
-`status` and `blocked_by` are not observed from this checkout.
+`plans/plan-greenfield-infra.md` is observed from this checkout as a
+`kxm.doc.v1` stub (status draft, authority instruction, updated
+2026-09-28). Its delivery position is unchanged: none of the delivery is
+scheduled there.
 
 The tracker names that file. The sentences that can be repeated without a
 hostname, an account name, or a secret are: a first move is recorded as

package/docs/architecture/inventory.md

@@ -12,6 +12,7 @@ Read from `plugins/kxm/src/cli.ts`, `scripts/kxm-hub.mjs`, `plugins/kxm/src/hub.
 | `kxm` CLI | `node scripts/kxm.mjs` or the installed bin | no listener | none | `plugins/kxm/src/cli.ts` |
 | 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` |
+| Hub cloud binding | `kxm hub bind <url> --cloud --token-env/--token-command` | no listener; writes the binding record and never stores the token | binding record; token stays in the named env or command | `plugins/kxm/src/cli/hub.ts` |
 | Runtime supervisor | `kxm runtime` / `scripts/kxm-runtime-supervisor.mjs` | `127.0.0.1` and the requested port, or ephemeral | registry and event stores below | `plugins/kxm/src/runtime-supervisor.ts` |
 | Runtime registry | opened by the supervisor | `runtime/registry.db` under the user state root | `registry.db`. A lane worktree registers under its project: same project id, its own control root, `lane_of` set. A registering root is the primary worktree when its git common dir is `<root>/.git`; if that primary registers while the live home row is not primary, the primary becomes the home row and every other live row of that repository becomes its lane. | `plugins/kxm/src/runtime-paths.ts` |
 | Runtime event store | opened by the supervisor | `runtime/projects/<key>/run-events.db` | `run-events.db` | `plugins/kxm/src/runtime-paths.ts` |

package/docs/concepts/trust-model.md

@@ -56,7 +56,7 @@ flowchart LR
 - **Claude Code plugin.** The MCP server uses the plugin's `auth_token` setting, else the project token the hub saved for this project. It never falls back to the saved admin token; without a project token, its tools report that and do nothing.
 - **SessionStart hook.** It reads local state read-only. It mints no token, writes no file, and never prints a token.
 - **Pi extension.** It uses `KXM_AUTH_TOKEN`, else the project token the hub saved for this project. It never uses the saved admin token, nor the one a hub it auto-started generated; without a project token it reports the fix and stays offline.
-- **`kxm peer` and `kxm workflow` agent commands.** They act as a peer agent, so they choose a token as the Pi extension does, and exit 2 with `project_token_missing` when none resolves.
+- **`kxm peer` and `kxm workflow` agent commands.** They act as a peer agent, so they choose a token as the Pi extension does, and exit 2 with `project_token_missing` when none resolves. The message names the project id that was sent and where it came from.
 - **Dashboard and Runtime supervisor.** Operator tools use `KXM_AUTH_TOKEN`, else the saved project token, else the saved admin token.
 
 ## Project isolation

package/docs/contributing/decisions.md

@@ -0,0 +1,153 @@
+---
+title: "Decisions"
+description: "Decisions of medium significance or higher made by automated KXM work in this repository. One entry per decision: the options evaluated with their weights, and why the selected option won. Recorded the turn the decision is taken."
+audience: "agents and maintainers"
+updated: "2026-09-27"
+---
+
+# Decisions
+
+Automated work records here every decision of medium significance or
+higher: the options it evaluated, the weight each option scored against
+the criteria that mattered, and why the selected option won. Weights are
+the session's own 0-to-1 scores, not measurements. A decision that was
+made directly by the operator is recorded only when executing it required
+a choice.
+
+Entries run oldest first. Retention: this file keeps the last 50 entries. When one more would exceed
+the cap, the oldest entries rotate to
+`docs/contributing/decisions-archive.jsonl` as `kxm.decision-archive.v1`
+lines (date, title, area, options with weights, selected, why, evidence),
+oldest first. The archive is append-only cold storage; the md stays the
+working set.
+
+## 2026-09-26 — P2 critic transport while the engine was schema-blocked (dispatch)
+
+- Context: installed 0.7.130 refused the P2 lane's new agent schemas, so
+  `kxm run`, drive, cancel, and receipt all answered 400. Both critics
+  still had to review the unit, and loop-dispatch wanted engine attempts.
+- Options:
+  - Wait until #343 ships, then run critics through the engine — weight
+    0.2. Highest purity, but it stalls the unit for a release cycle and
+    the reviewers' context goes cold.
+  - Run a second runtime supervisor from the branch code — weight 0.1. It
+    would load the lane, but it mutates machine-global runtime state with
+    unreleased code and risks the exact registry corruption S24 just
+    fixed.
+  - Dispatch both critics through the harness runner with briefs copied
+    into the lane sandbox — weight 0.9. The documented relief for schema
+    cutover lanes, proven twice the same morning by the writer repairs;
+    costs only the improve-report attempt rows.
+- Selected: harness runner. Fastest safe path; the engine-attempt proof
+  was deliberately deferred to the next unit rather than falsified.
+Evidence: Evidence: the P2 lane store (bae17379) held the settled attempts while the control-root report read zero, and the 0.7.131 update plus runtime restart left the lane loadable with a verified simulated receipt.
+
+## 2026-09-26 — Supervisor cadence interpretation (operations)
+
+- Context: the operator ordered the schedule task changed to 30 minutes.
+  The improvement loop was anchored to wall-clock ("every sixth tick,
+  about 30 minutes"), which a longer tick would silently stretch to three
+  hours.
+- Options:
+  - Keep "every sixth tick" literally — weight 0.3. Preserves the prompt's
+    letter, breaks the documented ~30-minute wall-clock cadence the
+    parenthetical pins.
+  - Improvement loop every tick — weight 0.8. Preserves both documented
+    wall-clock behaviours; the tick count stops appearing anywhere.
+- Selected: every tick. The operator's order named the tick cadence; the
+  improvement loop's anchor was always the half hour. Stated in the report
+  so it can be flipped back with one word.
+Evidence: Evidence: plans/kxm-roadmap/supervisor-prompt.md and the operator order of 2026-09-26.
+
+## 2026-09-27 — Authoring witness misses committed work (engine)
+
+- Context: the engine failed two writer runs (P2 morning, vision port)
+  with `authoringWitness: unchanged` while both lanes held the writer's
+  commit. `captureWorktreeWitness` fingerprints porcelain, unstaged, and
+  staged diffs but not HEAD, so a writer that fully commits reads as
+  unchanged and a `passed` write step is flipped to `failed`.
+- Options:
+  - Add `git rev-parse HEAD` to the fingerprint — weight 0.9. One term in
+    one string; catches commits, resets, and branch switches, which are
+    all authoring-relevant moves of a lone-writer checkout.
+  - A separate commit-witness field with its own failure class — weight
+    0.6. Finer attribution (commit versus dirty edit) but a larger
+    surface for a distinction nothing consumes today.
+  - Trust the producer's `authored` metadata — weight 0.1. The module
+    documents that metadata is set here, not trusted from the producer.
+- Selected: HEAD in the fingerprint, one named test (committed-only
+  change keeps `passed` with `authored: true`), shipped before any more
+  engine-driven write steps.
+Evidence: Evidence: test/core/worktree-witness.test.ts (real temp git repositories), and the two failed lane runs run_fe3061b3 (vision) and run_f7a21c84 (P2) whose lanes held the writer commits.
+
+## 2026-09-27 — Open PR queue: draft handling and landing order (landing)
+
+- Context: six open PRs after #343. Two were drafts, one conflicted
+  against the restructured CLI, three were clean and non-draft. The
+  standing rule says every PR is landed without asking.
+- Options:
+  - Land everything including drafts — weight 0.2. A draft is the
+    author's own hold signal; overriding it defeats the state and risks
+    landing half-work.
+  - Land only clean non-drafts now, defer the conflicted one to a port,
+    leave drafts — weight 0.9. Honours both the autonomy rule and the
+    draft semantics; the queue drains in one session.
+  - Ask the operator per PR — weight 0.1. The standing rule explicitly
+    removes this ask for open PRs.
+- Selected: land non-drafts oldest-first (#341, #344, #346), leave
+  #325 and #342 as drafts, dispatch #345 as a port.
+Evidence: Evidence: gh pr list on 2026-09-27 (six open: two drafts, one conflicting, three clean).
+
+## 2026-09-27 — Outcome parser rejects real model output (engine)
+
+- Context: the one-shot producer appends a "return a final JSON object
+  with an outcome field" contract to every prompt, and `determineOutcome`
+  requires the model's entire output to parse as that bare JSON. Both real
+  writers and critics answer with the brief's own review format instead
+  (grok prose, fable markdown), so every substantive engine-driven step
+  settles `failed` even when the transport and witness are clean.
+- Options:
+  - Extract the last balanced JSON object in the text and apply the same
+    strict checks (object, string `outcome`, member of allowed outcomes;
+    anything else stays `failed`) — weight 0.9. Tolerates the prose
+    models actually produce; no path to success without a truthful
+    outcome token.
+  - Repeat the JSON contract as the first and last line of the prompt —
+    weight 0.3. Prompt engineering against measured behaviour; the brief's
+    own output section still wins.
+  - Per-harness structured output modes — weight 0.5. The durable fix but
+    a per-adapter surface change; too broad for the ship cycle this needs
+    to ride.
+- Selected: last-JSON-object extraction, same strict checks, same
+  fail-closed default. Shipped with the witness fix in one release so the
+  engine can drive real steps at all.
+- Addendum (2026-09-27, after two more real failures): the shipped rule
+  required the object alone on the final line; real critics write the
+  object inline after their summary prose and fail anyway. The rule is
+  now "the last top-level object of the reply, extending to the end of
+  the trimmed text": forward scan, depth- and string-aware, so trailing
+  prose, mid-text objects, and inner objects of a truncated outer object
+  all still fail, while the real inline-at-end shape passes.
+Evidence: Evidence: test/core/oneshot-producer.test.ts (real reviewer shapes), runs run_79bd2d13 and run_041dfb8e on the vision lane, and the shipped forward pass in #368.
+
+## 2026-09-27 — PR #345: rebase, close, or port (dispatch)
+
+- Context: #345 adds `kxm vision assert`, but its base predates the CLI
+  restructure that deleted `plugins/kxm/src/cli/vnext.ts`; GitHub reports
+  DIRTY/CONFLICTING. The gate module `vision-gate.ts` already exists on
+  main; only the command surface is missing.
+- Options:
+  - Force the rebase and hand-resolve inside the land pipeline — weight
+    0.3. The land rebase stage resolves only three union classes; a
+    deleted-file port is none of them, so it fails mid-pipeline anyway.
+  - Close #345 as superseded — weight 0.2. Discards reviewed intent
+    (skill gate-step wording, fail-closed exit contract) that is still
+    wanted.
+  - Port the four pieces (handler, registration, test, skill wording)
+    onto the current CLI structure through a writer lane — weight 0.9.
+    Small surface, the PR stays open until the port lands, and the
+    dispatch is the first engine-driven unit on 0.7.131, feeding
+    loop-dispatch.
+- Selected: port through the engine lane `vision-assert-port`; the PR is
+  closed by its replacement landing, not by hand.
+Evidence: Evidence: merge-base 77beda4 predates the CLI restructure; merge-tree showed cli/vnext.ts deleted on main; vision-gate.ts already on main.

package/docs/contributing/learnings.md

@@ -13,6 +13,16 @@ entry whose fix has landed is deleted, not archived.
 
 ## Dispatch and lanes
 
+- **A "no retired names anywhere" rule must exclude the history pages.**
+  The P2 brief asked that retired recipe names appear nowhere in docs; the
+  writer then rewrote dated lessons and rules on this page and on
+  `operating-rules.md` into nonsense ("applies to `kxm lane run` and
+  `kxm lane run`") and hand-edited generated roadmap pages. Sweeps like
+  that exclude `docs/contributing/learnings.md`, `operating-rules.md`,
+  `plans/`, and `CHANGELOG.md`, and the planner reverts any edit to them.
+  Evidence: omp-align-p2, 2026-09-26. Applies to: every brief with a
+  "returns nothing" grep.
+
 - **Branch every lane from the current `origin/main`, and rebase before
   review, not after.** Three branches cut before #330 and #331 landed each
   needed a hand rebase with the same additive conflicts (`cli.ts`
@@ -31,11 +41,14 @@ entry whose fix has landed is deleted, not archived.
   supervisor tick and any batch of writers finishing together.
 - **The transport's stdin read can fail with `EAGAIN` under concurrent
   detached dispatch.** Retry once; the request itself is fine. Evidence:
-  two occurrences on 2026-09-26 (backlog S18). Applies to: `just impl-bg`
-  and `just review-cli` until they retire.
+  two occurrences on 2026-09-26 (backlog S18). Applies to:
+  `scripts/harness-run.mjs` dispatches, which outlive the retired just
+  recipes.
 - **Do not launch a writer under the Bash tool's ten-minute background
-  cap.** It kills the harness mid-run. Use the detached recipe or
-  `kxm lane run`. Evidence: the first lane-cli dispatch, 2026-09-26.
+  cap.** It kills the harness mid-run. Give the dispatch call an unbounded
+  timeout, use the detached runner, or `kxm lane run`. Evidence: the first
+  lane-cli dispatch, 2026-09-26; omp-align-p2 repairs ran 15 to 36 minutes
+  in 2026-09-26 background jobs with an unbounded timeout and survived.
 - **Do not run a standalone `npm run verify` on a branch that `kxm land`
   will land.** The `verify` stage runs it again, so the standalone run
   only spends one of the two verify slots twice. Run the critics on the
@@ -44,63 +57,47 @@ entry whose fix has landed is deleted, not archived.
 
 ## Engine and runtime
 
-- **A lane that changes `.kxm` schemas cannot be observed or re-driven by
-  the installed runtime until that change ships.** The runtime revalidates
-  the lane's project config on every request with the installed code, so
-  once the P1 writer rewrote the role files to v2, `kxm runs status`,
-  `cancel`, and a second `kxm lane run` all refused with
-  `schema_identity_mismatch`. Watch such a writer by process and tree, and
-  dispatch its repair through the harness runner. Evidence: omp-align-p1,
-  2026-09-26. Applies to: any schema or config-identity cutover.
-
-- **One control root per project id in the Runtime registry.** A lane
-  worktree carries the same `.kxm/project.yaml` id as the main checkout, so
-  the second root that posts a run is refused with `project_home_conflict`,
-  and a lane that was removed leaves a dead row behind. Until backlog S24
-  lands: stop the runtime, delete the dead row from `registry.db` under the
-  user state root, restart, redispatch. Never delete a row whose root still
-  exists. Evidence: omp-align-p1 dispatch, 2026-09-26. Applies to:
-  `kxm lane run` and `kxm run --lane`.
+- **A lane whose `.kxm` schemas are ahead of the installed runtime cannot
+  be driven, observed, or cancelled by the engine.** Every run-scoped
+  request (status, drive, cancel, receipt) answers 400
+  `schema_additionalProperties`, because `loadKxmProject` validates the
+  project before the route: installed 0.7.130 refuses the P2 lane's
+  `role:` on `.kxm/agents/*.yaml` while the branch's own loader validates
+  clean. The morning `implement-only` run executed before the writer
+  rewrote the agent files (c352285 landed mid-run), then settled `failed`
+  with `authored: false` and witness unchanged, and the lane now refuses
+  new runs with `lane_run_open` because that run cannot be cancelled.
+  Until the branch ships, `kxm update --kxm` runs, and the runtime
+  supervisor restarts, dispatch repairs and critics through the harness
+  transport. Resolved for this lane by 0.7.131: after the update and a
+  runtime restart, the lane loads clean, the stuck run cancelled
+  idempotently, and a simulated drive returned a verified receipt.
+  Evidence: omp-align-p2 lane, 2026-09-26. Applies to: every
+  dispatch whose lane changes schemas.
 
-- **The improvement loop is blind while writers bypass `kxm run`.** Every
-  writer this week ran through the harness runner (`just impl-bg` and the
-  critic recipes), which records no engine events, so `kxm improve report`
-  and `kxm routing report` both return zero records and no candidates.
-  Evidence: both reports on 2026-09-26 at 08:14 UTC list the engine store as
-  absent and telemetry as empty. Applies to: dispatch. Once the one-step
-  workflows land, dispatch through `kxm lane run --workflow implement-only`
-  so attempts land in the run-events store; until then the sixth-tick
-  improvement loop reports nothing by design.
-  The reports read the store of the control root they run in, so a lane's
-  attempts show up only when the report runs inside that lane, or once the
-  lane is registered under the project (backlog S24).
+- **The improvement reports read only the control root's own store.**
+  `kxm improve report` and `kxm routing report` read the run-events store
+  of the checkout they run in, so a registered lane's attempts are
+  invisible from the parent (backlog S30): on 2026-09-26 the control-root
+  report read 0 records while the lane store held the settled attempts.
+  Run the reports inside the lane, or dispatch through the engine from the
+  root you report on. Evidence: both reports on the P2 control root
+  (0 records) versus the same reports inside the omp-align-p2 and
+  docs-cadence lanes (settled attempts). Applies to: the supervisor's
+  improvement loop and any report run from a parent checkout.
 
-- **A live agent step had a hard 120 second timeout with no configuration
-  path.** The supervisor built the one-shot producer without a timeout.
-  Fixed on the run-driver-timeouts branch (step `timeoutMs`, project
-  `limits.agentStepTimeoutMs`, default one hour). Delete this entry when
-  that lands.
-- **A run with an unreconciled executing attempt could not be cancelled or
-  driven again**, and that survived a supervisor restart; deleting the
-  lane's Runtime project store was the only recovery. Fixed on the same
-  branch (`executing_unrecorded`, admission released on a handoff receipt).
-  Delete when it lands.
-- **The engine sends `--reasoning-effort low` on a first attempt regardless
-  of the role's effort.** `engine.ts` hard-codes it. Open; covered by the
-  role alignment plan P2 and P6.
 - **Template provenance is refused when the installed kxm moves ahead of
   the stamped revision, and a project without the file validates as
   ready.** Deleting the file is the sanctioned state until `kxm init` can
-  re-stamp. Evidence: every fresh lane on 2026-09-26 until #330 removed it.
+  re-stamp. Evidence: backlog S3 (still open; the re-stamp decision is
+  unmade) and the live check at `plugins/kxm/src/project-config.ts`.
+  Applies to: every fresh lane.
 
 ## `kxm land`
 
 - **Auto-merge cannot be enabled on a PR that is already `CLEAN`**; the
   mutation answers "clean status" and the REST squash merge is the path.
   While CI is paused every PR is clean, so this is the normal path.
-- **The Release workflow's run is titled `Release`, never the PR title.**
-  Match it by time after the Auto-Release run. Fixed on kxm-land-followup;
-  delete when it lands.
 - **A verify failure inside `kxm land` shows only the child's last output
   line.** Re-run verify by hand to see the cause until backlog S19 lands.
 
@@ -110,9 +107,13 @@ entry whose fix has landed is deleted, not archived.
   main's later additions as deletions.** Say the base commit in the brief
   and tell the critic to review against it. Evidence: docs-site review,
   two of five findings were base artifacts.
-- **Usage errors are Commander prose even under `--json` in every group.**
-  Repo-wide, one fix in `mapCommanderError`; on kxm-land-followup. Delete
-  when it lands.
+- **Read-only critics cannot leave their lane sandbox.** The architecture
+  critic three times could not read a brief under the main checkout's
+  `.kxm/briefs/` and reviewed against the question list alone, once
+  re-flagging a decision the brief had already settled. Copy the brief
+  into the lane's gitignored `.kxm/logs/` and dispatch from that path.
+  Evidence: omp-align-p2 passes 1 to 3, 2026-09-26. Applies to: every
+  read-only critic dispatch.
 
 ## omp research, kept for the alignment plan
 

package/docs/contributing/operating-rules.md

@@ -30,7 +30,8 @@ replacement.
   merge, and follow through to the auto-release tag and the npm publish.
   Report the outcome; do not stop to ask for the merge. Enforced by
   `kxm land` (verify, docs, push, pr, rebase, unblock, merge, release,
-  milestone) and, until every stage is proven, by hand. (2026-09-26.)
+  milestone); every stage ran green end to end on #338 with kxm 0.7.126,
+  so hand landing is the exception, not the rule. (2026-09-26.)
 - **Documentation is regenerated after a green pipeline and before the
   merge.** The `docs` stage of `kxm land` runs the roadmap generator and
   commits the regenerated pages on the branch. (2026-09-26.)
@@ -54,9 +55,14 @@ replacement.
   entry point is a `kxm` command: a group under `plugins/kxm/src/cli/`,
   registered in `cli.ts`, owned by a bundled skill so `check:generated`
   passes, documented in the CLI reference. Existing recipes retire as their
-  `kxm` verbs land; the transport recipes (`impl`, `plan`, `review-*`,
-  `impl-bg`) retire last, after one real unit has run through the one-step
-  workflows. (2026-09-26.)
+  `kxm` verbs land; the transport recipes (`impl`, `plan`, `review-arch`,
+  `review-cli`, `impl-bg`, `dispatch`) retired in #343, so units dispatch
+  through `kxm lane run <unit> --brief <file> --workflow implement-only`
+  and the read-only critic workflows `review-arch-only` and
+  `review-cli-only`. `just` keeps only the assignment-runner recipes
+  (`assign`, `witness`, `accept`, `observe-cost`, `attribute`,
+  `change-report`, `plan-current`), which are harness transport for the
+  issue 127 runner. (2026-09-26.)
 
 ## Accounts
 
@@ -72,6 +78,13 @@ replacement.
 
 ## Decisions and debt
 
+- **Automated KXM work records every medium-or-higher decision it makes in
+  `docs/contributing/decisions.md`** for its working project: the options
+  evaluated, the weight each option scored and against what, and why the
+  selected option won. Recorded the turn the decision is taken, not at
+  session end. The doc keeps the last 50 entries; older ones rotate to
+  `docs/contributing/decisions-archive.jsonl` as `kxm.decision-archive.v1`
+  lines. (2026-09-27.)
 - **Every option comes with pros and cons and two recommendations**, the
   solid-product answer and the interim answer. (2026-09-26.)
 - **Every shortcut goes on the backlog the same turn it is taken**, as an
@@ -102,10 +115,10 @@ refusals, and the two roadmap skills. (2026-09-26.)
   form: `[{lane}/{agent}]: {phrase}. {No action|Review needed}. -
   {E}e|{D}d ({M}m{S}s)`. Routine lines are not echoed back in chat.
   (2026-09-26, formatter at `~/.claude/scripts/evt-monitor.sh`.)
-- **A supervisor tick runs every five minutes** while a session is open:
+- **A supervisor tick runs every thirty minutes** while a session is open:
   sweep the lanes, act on "Review needed", cap concurrent verifies at two,
   regenerate the roadmap after a merge, and run the improvement loop every
-  sixth tick. Its prompt is checked in at
+  tick. Its prompt is checked in at
   `plans/kxm-roadmap/supervisor-prompt.md`; a tick that finds the schedule
   missing or expiring recreates it from that file in the same chat session,
   never a new one, so the loop continues under the same task. (2026-09-26.)

package/docs/glossary.md

@@ -104,7 +104,7 @@ Another [agent](#agent) in the same [project](#project). `kxm_list` and `kxm pee
 
 ### Project
 
-The authentication and discovery namespace on the hub. Every command resolves it the same way: `--project` or `KXM_PROJECT`, then the [project ID](#project-id) in `.kxm/project.yaml`, then the `package.json` name, then the directory name. Its key in the hub's `KXM_PROJECT_TOKENS` holds its token. Agents see only peers in the same project.
+The authentication and discovery namespace on the hub. Every command resolves it the same way: `--project` or `KXM_PROJECT`, then the active mode's `project` in `.kxm/config.yaml`, then the [project ID](#project-id) in `.kxm/project.yaml`, then the `package.json` name, then the directory name. Its token is a key reference in that config, or the matching key in the hub's `KXM_PROJECT_TOKENS`. Agents see only peers in the same project.
 
 ### Project ID
 
@@ -112,7 +112,7 @@ The stable `prj_` identifier in `.kxm/project.yaml`. It is the hub [project](#pr
 
 ### Project token
 
-The credential that the agents of one [project](#project) use. The operator sets it in the hub's `KXM_PROJECT_TOKENS` JSON map, and agents receive it as `KXM_AUTH_TOKEN` or the plugin's `auth_token`. Setting `KXM_PROJECT_TOKENS` replaces the hub's saved map, so list every project each time.
+The credential that the agents of one [project](#project) use. The operator points config at it with `key.op` (`op://vault/item/field`) or `key.env` (an environment variable name), or sets the hub's `KXM_PROJECT_TOKENS` JSON map. The config file never holds the token. Agents receive the resolved value as `KXM_AUTH_TOKEN` or the plugin's `auth_token`. Setting `KXM_PROJECT_TOKENS` replaces the hub's saved map, so list every project each time. A config `hub.projects` map is resolved in memory and is not saved.
 
 ### Session token
 

package/docs/operations/troubleshooting.md

@@ -88,7 +88,7 @@ If a malformed claim remains, read the exact `.pid` JSON in the state directory
 | `hub_bind_unauthenticated` | The URL is remote and this machine has no token for the project; export it and bind again |
 | `hub_credential_unreadable` | Repair or remove `hub-env.json` under the user state root |
 | `cloud_token_missing` | A `--cloud` binding's variable is empty and it has no working command. Export the variable or fix `--token-command`. This machine's hub-env token is not sent |
-| `cloud_flag_required` | `--token-env` or `--token-command` was passed without `--cloud` |
+| `cloud_flag_required` | `--token-command` was passed without `--cloud`. `--token-env` and `--key-op` are key references and are valid on a local bind |
 | 401 after binding a loopback forward | The bind was not `--cloud`, so the client sent the local hub-env token. See [Cross-box peer attach](../operations.md#cross-box-peer-attach) |
 
 ## Claude Code plugin and MCP
@@ -99,7 +99,7 @@ The [plugin troubleshooting guide](../../plugins/kxm/README.md#troubleshooting)
 |---|---|
 | `kxm_*` tools do not appear | Check `/mcp` for the `kxm` server, check `node --version`, run `/reload-plugins`, and confirm `claude plugin list` shows `kxm@kxm` enabled |
 | `KXM hub unreachable at <url>` | Start the hub, or correct `server_url` with `/plugin configure kxm@kxm` |
-| `no project token for project <p>` | Enter the project token at `/plugin configure kxm@kxm`, or add `<p>` to the hub's full `KXM_PROJECT_TOKENS` map and restart the hub |
+| `kxm has no project token for project <p>` | The message names where `<p>` came from. Set `hub.local.project` or `hub.cloud.project` and a key reference in `.kxm/config.yaml`, or add `<p>` to the hub's full `KXM_PROJECT_TOKENS` map and restart the hub. Never paste the token into the file |
 | `KXM hub rejected the project token for project <p>` | Enter the token the hub holds for `<p>` |
 | `tool_policy_denied: Session token on disk is malformed or expired` | Run `kxm session token --clear` |
 | Pushed requests never arrive | Start Claude Code with `claude --dangerously-load-development-channels plugin:kxm@kxm` and accept the trust prompt, or use `kxm_inbox` and `kxm_reply` |

package/docs/operations.md

@@ -92,7 +92,7 @@ Expected output:
 
 ```text
 bound hub http://127.0.0.1:17331 · remote · health=on · token is not stored
-hub health=true ready=true · remote hub
+hub health=true ready=true · remote hub · mode=cloud project=prj_example (.kxm/config.yaml hub.cloud.project) key=env:KXMD_HUB_TOKEN
 ```
 
 `--token-env` and `--token-command` can be combined. A non-empty variable wins.
@@ -115,8 +115,8 @@ kxm hub view
 |---|---|---|
 | Loopback URL | Scope `loopback`. No credential required | Scope `remote`, including an SSH forward |
 | Token stored in `hub-binding.json` | No | No. The file names `tokenEnv` and/or `tokenCommand` |
-| Credential later commands send | `KXM_AUTH_TOKEN`, then this machine's hub-env | The named source only. Hub-env is not a fallback |
-| Missing source | Agent commands report `project_token_missing` | `cloud_token_missing` or `cloud_token_command_failed`. The local admin token is not sent |
+| Credential later commands send | `KXM_AUTH_TOKEN`, then the active mode's key reference in `.kxm/config.yaml`, then this machine's hub-env | The active mode's key reference, then the binding's named source. Hub-env is not a fallback |
+| Missing source | Agent commands report `project_token_missing` and name the project id that was sent | `cloud_token_missing` or `cloud_token_command_failed`. The local admin token is not sent |
 | `kxm hub start` from an extension | May start a local hub | Does not start a local hub when the forward is down (`cloud_hub_unreachable`) |
 
 `kxm hub view`, `kxm tenant status`, `kxm peer`, `kxm workflow` agent commands,
@@ -124,9 +124,60 @@ kxm hub view
 all use that source. `kxm agent worker` puts `KXM_AUTH_TOKEN` in the child
 process environment only. It does not write the token to disk.
 
-The hub project id is the same value for peer commands and `kxm tenant status`:
-`--project` or `KXM_PROJECT`, then the `id` in `.kxm/project.yaml`, then
-`package.json` `name`, then the directory name.
+The hub project id is the same value everywhere: `--project` or `KXM_PROJECT`,
+then the active mode's `project` in `.kxm/config.yaml`, then the `id` in
+`.kxm/project.yaml`, then `package.json` `name`, then the directory name.
+
+### Hub identity in config
+
+Hub URL, mode, project id, and key reference live in `.kxm/config.yaml`
+(`kxm.config.v1`), the same file as `hub.autoStart`. `.kxm/project.yaml` stays
+the stable project id. The project file wins over
+`~/.config/kxm/config.yaml`. `KXM_PROJECT` and `KXM_SERVER_URL` select the
+live connection for one process. They do not rewrite the file.
+
+```yaml
+hub:
+  autoStart: background
+  mode: local                 # local | cloud
+  local:
+    url: http://127.0.0.1:7331
+    project: prj_example      # optional; defaults to the project.yaml id
+    key:
+      op: op://Private/kxm/local-project-token
+      env: KXM_LOCAL_PROJECT_TOKEN
+  cloud:
+    url: https://hub.kxmd.dev
+    project: prj_example
+    key:
+      op: op://Private/kxmd/project-token
+      env: KXMD_HUB_TOKEN
+  projects:                   # hub process map; references only
+    prj_example:
+      op: op://Private/kxm/local-project-token
+      env: KXM_LOCAL_PROJECT_TOKEN
+```
+
+`key.op` is an `op://vault/item/field` reference. `key.env` is an environment
+variable name. A non-empty variable wins; otherwise `op read` runs when the
+client or the hub needs the token. The resolved value is not written to
+config, `hub-binding.json`, or `hub-env.json`. A literal token is refused
+with `hub_config_invalid`.
+
+`kxm hub bind` and `kxm hub bind --cloud` write the mode, URL, project id, and
+key reference. `--key-op` is the `op://` reference for either mode.
+`--token-env` names the variable for either mode. `--token-command` stays
+cloud-only. `kxm hub view` prints the mode, URL, project id, and key source.
+It does not print the token. `kxm hub unbind` removes the binding and
+`hub.mode`, and leaves the `local` and `cloud` blocks in place.
+
+On the hub, `hub.projects` is that same kind of map. `KXM_PROJECT_TOKENS`
+still replaces the map and is saved. A config map is resolved in memory and
+does not replace the saved file.
+
+A setup whose hub map is still keyed by the package name should set
+`hub.local.project` or `hub.cloud.project` to that name. Otherwise clients
+send the `.kxm/project.yaml` id and the hub has no token for it.
 
 ### Remove the binding
 
@@ -134,8 +185,10 @@ The hub project id is the same value for peer commands and `kxm tenant status`:
 kxm hub unbind
 ```
 
-Unbind deletes `hub-binding.json`. It does not delete hub-env, and it does not
-close the SSH forward. Stop the forward by ending the `ssh -N` session.
+Unbind deletes `hub-binding.json` and clears `hub.mode` in `.kxm/config.yaml`.
+The `local` and `cloud` blocks stay, so the next bind can switch mode again.
+It does not delete hub-env, and it does not close the SSH forward. Stop the
+forward by ending the `ssh -N` session.
 
 ## Troubleshooting
 
@@ -143,6 +196,7 @@ close the SSH forward. Stop the forward by ending the `ssh -N` session.
 |---|---|---|
 | 401 `invalid_auth` after binding `127.0.0.1:17331` | The bind was not `--cloud`, so the client sent this machine's hub-env admin token | Bind again with `--cloud` and a token source that holds the remote hub's token. Unset a stale `KXM_AUTH_TOKEN` that points at the local hub |
 | `cloud_token_missing` | `KXMD_HUB_TOKEN` (or the variable you named) is unset or empty, and no command is configured | Export the variable or pass `--token-command`. The local hub-env token is intentionally unused |
+| `project_token_missing` | The project id sent to the hub has no agent token. The message names that id and where it came from | Set `hub.local.project` or `hub.cloud.project` in `.kxm/config.yaml` to the id the hub already knows, and point `key.op` or `key.env` at the token. `KXM_PROJECT` or `--project` overrides the id for one command. Do not paste the token into the file |
 | `cloud_token_command_failed` | `op` exited non-zero, timed out, or printed more than one line | Run the same command in a terminal and sign in to 1Password. Do not paste the token into the binding |
 | Clients through one SSH host get locked out together | The hub rate-limits by agent id, otherwise by source address. Every forward from one SSH session shares `127.0.0.1` on the hub. `sshd` `MaxStartups` and `MaxSessions` can refuse new forwards first | Give each long-lived agent its own name. Raise the SSH limits on that host if many people share one jump host. Do not point two tenants at one hub |
 | `kxm hub view` says `loopback` for the forward | `--cloud` was omitted | Bind again with `--cloud`. `KXM_SERVER_URL` overrides the binding URL and is labeled on its own |