@kontextmind/kxm 0.7.166 → 0.7.168

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

package/CHANGELOG.md

@@ -605,6 +605,24 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Fixed
 
+- **`kxm hub view` and `kxm hub bind` require a kxm hub body.** HTTP 200 HTML
+  (an Authentik login page) and 30x redirects are not healthy. The JSON
+  `health` field is `{ "error": "auth_proxy" }`, not the page. Bind refuses
+  with `hub_not_kxm` unless `--force` is set. A timeout or a dead host still
+  binds. `kxm hub view` names the key source that would supply the token
+  (`env:<NAME>` only when that variable is set, `op:<ref>`, `token-command`,
+  `hub-env`, or `missing`).
+- **A cloud bind no longer breaks a 0.7.159 Runtime supervisor.** Cloud fields
+  live in `hub-binding.cloud.json`. `hub-binding.json` stays a three-key local
+  record or is omitted, so the old reader falls back to the local hub instead
+  of throwing `malformed hub binding` and stopping sync. A newer schema is a
+  warning and `no_hub`, not a stalled tick. Restart the supervisor, hub, and
+  workers after upgrading and before `kxm hub bind --cloud`.
+- **`kxm update --kxm` downloads with curl when `gh` is missing**, and still
+  verifies the release sha256.
+- **The npm publish job waits until `npm view` shows the version** (bounded)
+  before it reports success. GitHub release log lines no longer say "published"
+  in a way that means the package is on npm.
 - **A one-shot outcome is the last top-level JSON object that ends the reply.** It is accepted only when the prefix before it leaves every string, object, and array closed (a naive state machine plus a container lexer over the last container openers). Anything ambiguous, truncated, or followed by prose fails closed. The authoring witness counts `HEAD`, so a writer that commits is credited.
 
 - **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.

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/contributing/ci-and-release.md

@@ -201,7 +201,12 @@ versions by hand.
 4. **Publish npm** runs in the protected `npm-publish` environment. It skips a
    version already on npm. Otherwise `scripts/kxm-publish-npm.mjs` confirms the
    GitHub release is published, downloads the asset, verifies its sha256
-   against the release digest, and runs `npm publish` on that exact file.
+   against the release digest, and runs `npm publish` on that exact file. The
+   job then polls `npm view @kontextmind/kxm@<version> version` (up to 20
+   minutes, `KXM_NPM_VISIBLE_WAIT_MS=0` skips the wait) and reports success
+   only after the registry shows that version. Log lines that say the GitHub
+   release is public are not an npm publish. The registry can lag the GitHub
+   release by many minutes.
 
 Every step is idempotent. Rerunning the Release workflow for a tag that is
 already published or already on npm reports it and changes nothing.

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/operations/runtime-sync.md

@@ -94,8 +94,9 @@ sync prj_a17d607765e144cd95b93a8715d360b6: blocked (pending 0, acked 1, refused
 | State | Meaning | Action |
 |---|---|---|
 | `ok` | Rows are being acknowledged | None |
-| `no_hub` | No hub is bound or set; rows are kept locally by design | Bind a hub if you want hub-side views |
+| `no_hub` | No hub is bound or set, or this build ignored a binding it does not understand; rows are kept locally by design | Bind a hub if you want hub-side views. A warning that names `hub-binding.json` means restart the supervisor after upgrading, then bind again |
 | `blocked` | Transport or credential failure; rows stay pending and the tick backs off, up to 5 minutes | Fix the cause; the next attempt resumes on its own |
+| `sync: the supervisor is running but did not answer /v1/sync/status` | The process is up, and `kxm runtime status` could not read `GET /v1/sync/status`. A hung supervisor, a token mismatch, or a supervisor started before an upgrade | `kxm runtime stop`, then `kxm runtime start`. Restart the hub and workers too after an upgrade and before a cloud bind |
 | `refusing` | The hub durably refused rows, or answered without a result for some | Fix the hub side, then run `kxm runtime sync-retry` |
 
 A project whose run store this release cannot open shows `blocked (its store is not readable by this build)` with the reason; see [Upgrade KXM](upgrade.md#understand-schema-changes). Right after the supervisor starts, the status can read `no project registered with this Runtime yet` until the first tick.

package/docs/operations/troubleshooting.md

@@ -89,6 +89,7 @@ If a malformed claim remains, read the exact `.pid` JSON in the state directory
 | `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-command` was passed without `--cloud`. `--token-env` and `--key-op` are key references and are valid on a local bind |
+| `hub_not_kxm` | The URL returned an HTML login page or a 30x redirect, not a kxm `/health` body. `https://hub.kxmd.dev` is an Authentik forward-auth page. Bind the SSH forward `http://127.0.0.1:17331`. `--force` records the URL anyway and does not make the proxy a hub |
 | 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
@@ -209,6 +210,9 @@ A gate step declares an outcome its `expect` value never produces. The message n
 | `runtime supervisor is not running` or `runtime_not_running` | The supervisor stopped | `kxm runtime start`; commands such as `kxm run` also start it on demand |
 | `runtime_supervisor_unreachable` | A live supervisor process does not answer its token probe | Check the PID from `kxm runtime status`, stop a hung process with your OS tools, then `kxm runtime start` |
 | `project_required` | The command ran outside a KXM project | Run it from the checkout, or run `kxm init` |
+| `project_home_conflict` | This checkout is not the registered home for that project id. A different repository already owns it, the home runtime is immutable, or the primary checkout is already the home row | Use the original checkout, or a worktree of that repository. Do not copy the project id into an unrelated clone, and do not delete the database |
+| `runtime_schema_newer` | The store was written by a newer release than this build | Upgrade KXM. Do not delete the database |
+| `sync: the supervisor is running but did not answer /v1/sync/status` | The supervisor process is up, and `GET /v1/sync/status` failed. A hung process, a token mismatch, or a supervisor started on an older release | `kxm runtime stop`, then `kxm runtime start`. After an upgrade, restart the hub and workers before a cloud bind. See [Check sync status](runtime-sync.md#check-sync-status) |
 | `producer_route_not_admitted` | A live drive uses a model route that is not admitted | `kxm routes admit --model <provider/model>`, or drive with `--simulated` |
 | A 429, timeout, or provider error fails the attempt on the first route | The role's `policy.fallback.onError` is empty, omits that class, or `maxSwitches` is already spent. Cancellation, policy refusal, and authentication do not walk | List the class on the role, admit the next route, and read `routing.route_switched` in the run events. `kxm routing report` prints Route switches |
 | `pi_not_authenticated: pi harness not detected (pi_native_impersonation_blocked)` | A Pi agent's model belongs to a vendor with its own harness | Set the agent's native `harness:`, or choose an admitted Pi route whose vendor has none |

package/docs/operations/upgrade.md

@@ -6,7 +6,7 @@ Move the `kxm` CLI, the hub, the Runtime, and the Claude Code or Pi integrations
 
 - Protected storage for a full backup; see [Back up and restore KXM](backup-and-restore.md).
 - A window in which the hub, the Runtime supervisor and long-lived workers may stop.
-- The GitHub CLI (`gh`, signed in) if you apply updates with `kxm update --kxm` from the default `github` source, which downloads the release tarball with it.
+- The GitHub CLI (`gh`, signed in) if you apply updates with `kxm update --kxm` from the default `github` source. When `gh` is not installed, that command downloads the same `kxm-<version>.tgz` with curl and still checks the release sha256 before installing. Without a working `kxm` either, use the curl commands in [Update the CLI without gh](#update-the-cli-without-gh).
 
 ## Check for an update
 
@@ -54,12 +54,27 @@ Use the path that matches how KXM was installed. `kxm update --kxm` applies an u
 | Project dependency | `npm install @kontextmind/kxm@latest` in that project |
 | Source checkout | `git pull`, then `npm ci` |
 
-`kxm update --kxm` refuses to install a GitHub release that does not publish a SHA-256 digest for its tarball (`release_digest_missing`) or whose download does not match it (`release_digest_mismatch`). Preview the steps first:
+`kxm update --kxm` refuses to install a GitHub release that does not publish a SHA-256 digest for its tarball (`release_digest_missing`) or whose download does not match it (`release_digest_mismatch`). When `gh --version` fails, the download step is `curl --fail --silent --show-error --location` against `https://github.com/kontextmind/kxm/releases/download/v<version>/kxm-<version>.tgz`, and the digest check is unchanged. Preview the steps first:
 
 ```bash
 kxm update --kxm --dry-run
 ```
 
+### Update the CLI without gh
+
+On a host that has neither `gh` nor a working `kxm`, download the release tarball and check the digest printed on the GitHub release before installing:
+
+```bash
+version=0.7.166
+curl --fail --silent --show-error --location \
+  --output "kxm-${version}.tgz" \
+  "https://github.com/kontextmind/kxm/releases/download/v${version}/kxm-${version}.tgz"
+sha256sum "kxm-${version}.tgz"
+npm install --global --omit=peer "./kxm-${version}.tgz"
+```
+
+Refuse a tarball whose sha256 does not match the release asset digest.
+
 ### Update harnesses and plugins
 
 Without `--check` or a lone `--kxm`, `kxm update` also runs the native updaters of detected harnesses. Narrow it with a harness id and one scope:
@@ -76,7 +91,7 @@ kxm update pi --models             # refresh Pi model catalogs
 
 ## Start and verify
 
-1. Start the hub (or its service), then the Runtime with `kxm runtime start`.
+1. Start the hub (or its service), then the Runtime with `kxm runtime start`. Restart workers too. Do this after the upgrade and again before `kxm hub bind --cloud`, so an older supervisor does not keep a binding it cannot read.
 2. Check `kxm hub view`, `/ready` and `/metrics`.
 3. Check `kxm runtime status` until every project reports `ok` or `no_hub`.
 4. Send one request between two agents and read one Runtime run with `kxm runs status <run-id>`.