@kontextmind/kxm 0.7.124 → 0.7.126

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

package/CHANGELOG.md

@@ -138,6 +138,11 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Changed
 
+- **Usage errors under `--json` print a `usage_error` envelope and exit 2.**
+  A missing required option, unknown command, or other Commander usage error
+  writes `kxm.cli-result.v1` to stdout with `command`, `error`, and `detail`.
+  Text mode still prints the Commander line on stderr.
+
 - **Windows Validate legs run again on GitHub-hosted `windows-latest`.** The PR gate
   still requires only `Validate (linux, Node 22.19.0)` and `Validate (linux, Node 24)`
   on ARC `kontextmind-doks`. Windows Node 22.19.0 and 24 report `validate:pr` but are
@@ -403,6 +408,14 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Fixed
 
+- **`kxm land` names the pull request from the first commit subject and matches the Release run by time.**
+  `--title` sets the title; otherwise the subject of the first commit on the
+  branch is used, and a missing subject refuses `land_pr_title_missing`. The
+  title is never the branch name. The squash commit title stays `<title> (#n)`.
+  After Auto-Release succeeds, the Release run is the first `release.yml` run
+  created after that Auto-Release run, with no title filter. Both run ids are
+  recorded and printed, and each wait logs one JSON line every two minutes.
+
 - **A local `kxm workflow add` writes only what the project loader accepts, where it reads
   it.** Local scope needs a KXM project (`project_not_found` outside one, creating nothing)
   and writes to the project root's `.kxm/workflows/` from any subdirectory. Before writing,

package/docs/README.md

@@ -114,6 +114,8 @@ KXM connects coding agents through a durable, authenticated [hub](glossary.md#hu
 | [Packages and workspaces](contributing/packages.md) | Maintainers | Workspace layout, Nx targets, Bun task running and the layer gate |
 | [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 |
+| [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 |
 
 The templates: [feature](templates/feature.md) · [bug fix](templates/bug-fix.md) · [ADR](templates/adr.md) · [architecture](templates/architecture.md) · [research](templates/research.md) · [review](templates/review.md) · [test plan](templates/test-plan.md) · [test report](templates/test-report.md) · [runbook](templates/runbook.md) · [postmortem](templates/postmortem.md) · [handoff](templates/handoff.md).

package/docs/architecture/inventory.md

@@ -23,6 +23,10 @@ Read from `plugins/kxm/src/cli.ts`, `scripts/kxm-hub.mjs`, `plugins/kxm/src/hub.
 | Workspace logs | `workspaceDirs` | `.kxm/logs`, or `KXM_LOGS_DIR` | log files | `plugins/kxm/src/cli/types.ts` |
 | Workspace assets | `workspaceDirs` | `.kxm/assets`, or `KXM_ASSETS_DIR` | asset files | `plugins/kxm/src/cli/types.ts` |
 | Workspace state | `workspaceDirs` | `.kxm/state`, or `KXM_STATE_DIR` | `kxm.db` when the hub uses this directory | `plugins/kxm/src/cli/types.ts` |
+| Lane registry | `kxm lane create` | no listener | `lanes.json` under the workspace state dir | `plugins/kxm/src/cli/lanes.ts` |
+| Landing | `kxm land` via `scripts/pr-land.mjs` | no listener | `land-release-context.json` and `land-phases-before.json` under `.kxm/logs` | `scripts/pr-land.mjs` |
+| Assignment runner entry | `kxm assign <verb>` | no listener | none; the runner writes task records | `plugins/kxm/src/cli/assign.ts` |
+| Docs site | `kxm docs serve` via `ops/docs-site/serve.py` | the tailnet IPv4 from `tailscale ip -4` and one port; refuses any other address | none; serves the built `site/` | `ops/docs-site/serve.py` |
 
 On macOS the user state root is `Library/Application Support/KXM` under the
 home directory (`kxmUserStateRoot` in `plugins/kxm/src/bindings.ts`). Windows

package/docs/contributing/learnings.md

@@ -0,0 +1,105 @@
+---
+title: "Learnings"
+description: "Durable lessons from running the writer, critic, and landing loop on this repository. One entry per lesson, with the evidence and where it applies. Pruned when a lesson stops being true."
+audience: "agents and maintainers"
+updated: "2026-09-26"
+---
+
+# Learnings
+
+A lesson earns a line here when it would save a future session more than a
+few minutes. Each entry: the lesson, the evidence, where it applies. An
+entry whose fix has landed is deleted, not archived.
+
+## Dispatch and lanes
+
+- **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`
+  registrations, skill ownership lists, skill mirrors, changelog, dist).
+  Evidence: kxm-assign, docs-site, run-driver-timeouts on 2026-09-26.
+  Applies to: every brief; `kxm land`'s rebase stage only knows three
+  conflict unions.
+- **After an additive rebase, check the skill frontmatter and heading
+  spacing.** Keeping both sides doubled a `description:` key in a SKILL.md
+  (strict-YAML test) and butted two `##` headings together (MD022).
+  Evidence: kxm-assign verify failures, 2026-09-26. Applies to: any
+  hand-resolved conflict in `plugins/kxm/skills/` or the CLI reference.
+- **Never run more than two `npm run verify` at once on this machine.**
+  Six concurrent runs stretched a seven-minute gate past thirty minutes and
+  starved a landing. Evidence: 2026-09-26, 02:10 to 02:40. Applies to: the
+  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.
+- **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.
+- **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
+  writer's own verify evidence, then go straight to `kxm land`. Evidence:
+  docs-site, 2026-09-26. Applies to: every lane after its writer finishes.
+
+## Engine and runtime
+
+- **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.
+
+- **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.
+
+## `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.
+
+## Reviews
+
+- **A CLI critic reviewing a branch cut from an older base will report
+  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.
+
+## omp research, kept for the alignment plan
+
+- **omp's roster is `modelRoles` plus `retry.fallbackChains`**, walked on
+  provider errors with a revert policy; KXM's roster is a membership test
+  and never rotates. The passive `kxm.role.v2` draft already has the
+  better shape (routes with status and fallbacks); activate it rather than
+  invent a new v2. Source: `plans/research-omp-config-schema.md`.
+- **omp has no workflow file.** Its `workflowz` is a prompt contract over
+  an eval kernel. Nothing to port; KXM's workflow file is the stronger
+  model.

package/docs/contributing/operating-rules.md

@@ -0,0 +1,107 @@
+---
+title: "Operating rules"
+description: "Standing instructions from the operator that every agent session on this repository follows, with the date each was given. Read before planning, dispatching, landing, or editing the roadmap."
+audience: "agents and maintainers"
+updated: "2026-09-26"
+---
+
+# Operating rules
+
+These are the operator's standing instructions, recorded so a session does
+not have to be told twice. Each rule names the date it was given and where
+it is enforced. A rule that is retired is deleted, not kept beside its
+replacement.
+
+## Roles and routes
+
+- **The planner does not write product code.** Claude plans, reviews, and
+  lands. The default writer is the native Grok CLI (`grok-4.7`), a starting
+  rotation rather than a sole writer. If Grok is logged out, use a relief
+  route the tracker admits or stop and say what was hit. (`CLAUDE.md`,
+  standing.)
+- **One writer per checkout.** Each unit of work runs in its own lane
+  worktree (`kxm lane create <unit>`). Two writers in one tree clobber each
+  other. (2026-09-25.)
+
+## Landing
+
+- **Every PR is landed without asking.** Once a PR is open: monitor it,
+  rebase onto `main` when it falls behind, resolve conflicts and blockers,
+  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.)
+- **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.)
+- **After every phase or milestone, the intense pass runs, not the
+  refresh.** `/reanalyze-roadmap` (the `kxm-roadmap-review` skill with its
+  read-only critic), triggered by the `milestone` stage reporting
+  `deep_review_required`. (2026-09-26.)
+- **`npm run verify` stays the pre-push gate.** It is the first stage of
+  landing and is never replaced by it. CI's validate leg runs the same
+  script. (2026-09-26.)
+- **After every publish, the workflow runs on the improvements it just
+  landed.** `kxm update --kxm`, then `kxm update --extensions`, then
+  `kxm plugin install --all`, so the CLI and the kxm plugin in pi, omp, and
+  Claude Code are current; the Claude Code session then needs
+  `/reload-plugins`, which only the operator can run. The supervisor tick
+  does this after any `PUBLISHED` line. (2026-09-26.)
+
+## Entry points
+
+- **No new just recipes.** The repository is migrating off `just`. A needed
+  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.)
+
+## Decisions and debt
+
+- **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
+  item in `plans/backlog-shortcuts.md` with what was skipped and the proper
+  fix. (2026-09-26.)
+
+## Roadmap and plan content
+
+- **No stale data.** A fact that no longer holds is replaced, never kept
+  beside its replacement.
+- **History is brief.** One short line per material change, capped by the
+  generator; never a running narrative.
+- **No stale contacts.** A contact carries a role and a confirmation date;
+  unconfirmed past 90 days is dropped. Empty is fine.
+- **Present and upcoming only.** Superseded material leaves the roadmap.
+- **Progressive detail.** A far-off phase or task is brief but complete
+  (goal, scope, done criterion, evidence needed) and gains detail as it
+  nears implementation. A task cannot be `ready` without a template and a
+  source.
+- **Tasks use the artifact templates** under `docs/templates/`.
+
+All six enforced by the `kxm.roadmap.v1` schema, the generator's semantic
+refusals, and the two roadmap skills. (2026-09-26.)
+
+## Monitoring
+
+- **Background monitors emit progress, not only results**, in this line
+  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:
+  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
+  `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.)
+
+## Where the same rules live for agents
+
+The session memory under `~/.claude/projects/…/memory/` mirrors these as
+`pr-landing-autonomy`, `pipeline-docs-then-merge`, `no-just-prefer-kxm-cli`,
+`decisions-pros-cons-backlog`, `roadmap-editorial-rules`, and
+`monitor-progress-events`. This page is the checked-in copy; when the two
+disagree, this page is updated and the memory follows.

package/docs/reference/cli-reference.md

@@ -86,6 +86,7 @@ kxm -V
 ### JSON results
 
 - Every JSON result carries a `schema` field. Most commands print `kxm.cli-result.v1` with `ok` and `command` fields plus command-specific keys.
+- A usage error under `--json` (unknown command or option, missing argument, or missing required option) prints one `kxm.cli-result.v1` object on stdout and exits 2. `ok` is false, `error` is `usage_error`, `command` is the command path, and `detail` is the Commander message. Text mode still prints that message on stderr.
 - Gate-style commands print a `kxm.worker-result.v1` envelope, which adds `worker`, `createdAt`, `outcome` (`passed`, `warning`, or `failed`), and `summary`: `gate validate`, `gate artifacts-exist`, `gate degrade`, `gate signal`, `workflow signal`, `gate github watch`, and `agent worker --dry-run`. Outside `--dry-run`, the `gate` subcommands and `workflow signal` also append the envelope to `.kxm/logs/telemetry.jsonl`.
 - `session brief` prints `kxm.session-brief.v1` and `tenant status` prints `kxm.tenant-status.v1`.
 - The `command` field is not always the words you typed: `hub stop` and `session stop` report `stop`, `session token` reports `auth token`, `routes admit` and `routes disable` report `routes admitted` and `routes disabled`, `models inventory-refresh` reports `models inventory refresh`, `workflow export` reports `retrospective export`, `gate degrade` reports `workflow degrade`, `gate signal` and `workflow signal` report `signal`, `gate github watch` reports `github watch`, `agent worker` reports `worker`, and `improve report` reports `improve`.
@@ -135,7 +136,7 @@ For this page, 63 `--dry-run` invocations (every command in the first list, the
 
 Exit 1 covers an `ok: false` result, an unreachable hub for `hub view`, permission expansions for `trust check`, a stopped supervisor for `runtime status`, missing local state, and a planning-only `init`.
 
-Exit 2 covers an unknown command or option, a missing argument or required option, a value KXM rejects before acting, `--workspace` where unsupported, conflicting flags, a group run without a subcommand, a removed command (`removed_command`), and `--dry-run` on a command that cannot plan (`dry_run_unsupported`).
+Exit 2 covers an unknown command or option, a missing argument or required option, a value KXM rejects before acting, `--workspace` where unsupported, conflicting flags, a group run without a subcommand, a removed command (`removed_command`), and `--dry-run` on a command that cannot plan (`dry_run_unsupported`). With `--json`, Commander usage errors are `usage_error` envelopes on stdout and exit 2.
 
 ## Where commands read and write
 
@@ -1440,7 +1441,7 @@ Refusals (exit 1): `brief_unreadable`, `lane_unit_invalid`, `lane_exists`, `lane
 Land the current branch. `npm run verify` is the first stage and is not replaced. The command spawns `scripts/pr-land.mjs` from the project root and streams one JSON line per stage. With no `--stage`, the stages run in order and stop at the first refusal. `--dry-run` prints each stage's plan and does not mutate. Squash is the only merge. A required review is reported and not bypassed.
 
 ```text
-kxm land [--pr <n>] [--stage <name>] [--body-file <path>]
+kxm land [--pr <n>] [--stage <name>] [--title <text>] [--body-file <path>]
 ```
 
 ```bash
@@ -1451,6 +1452,7 @@ kxm land --stage verify --dry-run
 |---|---|---|---|
 | `--pr` | `<n>` | the open pull request for this branch | Pull request number to reuse |
 | `--stage` | `<name>` | all stages | One of `verify`, `docs`, `push`, `pr`, `rebase`, `unblock`, `merge`, `release`, `milestone` |
+| `--title` | `<text>` | subject of the first commit on the branch | Pull request title passed to `gh pr create`. Never the branch name |
 | `--body-file` | `<path>` | none | Body file for `gh pr create`. Required when creating a pull request |
 
 Outside a KXM project the command refuses `project_required` (exit 1). Unknown arguments and an unknown stage exit 2.
@@ -1462,14 +1464,16 @@ Outside a KXM project the command refuses `project_required` (exit 1). Unknown a
 | `verify` | Refuses `land_dirty_tree` unless `git status --porcelain` is empty. Skips when `.kxm/logs/land-verify-<tree>.json` for `HEAD^{tree}` is younger than 30 minutes. Otherwise runs `npm run verify` and writes that receipt. |
 | `docs` | Runs `plans/kxm-roadmap/update-dashboard.mjs` when that file exists. Commits changes under `docs/roadmap/`, `plans/kxm-roadmap/`, or `docs/architecture/` as `docs(roadmap): regenerate after verify`. Any other path, including `state.json`, is `land_docs_failed`. When the generator is absent the stage passes with `docs: skipped (generator absent)`. |
 | `push` | `git push -u origin <branch>`. After a rebase in this run, the push uses `--force-with-lease`. |
-| `pr` | Reuses the branch's open pull request, or creates one with `gh pr create --body-file`. |
+| `pr` | Reuses the branch's open pull request, or creates one with `gh pr create --body-file`. The title is `--title` when that option is set; otherwise it is the subject of the first commit (`git log --reverse --format=%s origin/main..HEAD`). `--dry-run` prints that title. |
 | `rebase` | When `mergeStateStatus` is `BEHIND` or `DIRTY`: fetch, rebase onto `origin/main`, and resolve only three conflicts (take `plugins/kxm/dist` from main and rebuild; union CHANGELOG Unreleased bullets, ours first; union the tracker "Landed in this tree" list, newest first). Runs `docs` again when the tree changed, re-verifies unless `git merge-tree --write-tree origin/main HEAD` was clean, and pushes with the lease. Five rounds, then `land_conflict_manual`. |
 | `unblock` | Reads `statusCheckRollup` and `reviewDecision`. Reruns one failed check with `gh run rerun --failed`. A second failure or `REVIEW_REQUIRED` is `land_blocked`. |
 | `merge` | Enables auto-merge with `enablePullRequestAutoMerge` and `mergeMethod: SQUASH`. When the response contains "clean status", squash-merges with `PUT /repos/{owner}/{repo}/pulls/{n}/merge` and commit title `<title> (#n)`. Polls `gh pr view --json state` every 30 seconds for up to 20 minutes. |
-| `release` | Records the newest `v*` tag before the merge, waits for the Auto-Release run whose title contains the pull request title, requires a newer tag from `git ls-remote --tags origin`, waits for the Release run created after the merge, then polls `npm view @kontextmind/kxm@<version> version` every 30 seconds for 10 minutes. The success detail is `PUBLISHED <version>`. |
+| `release` | Records the newest `v*` tag before the merge, waits for the Auto-Release run whose title contains the pull request title, requires a newer tag from `git ls-remote --tags origin`, then waits for the first `release.yml` run whose `createdAt` is after that Auto-Release run, with no title filter. Both run ids are written to `.kxm/logs/land-release-context.json` and printed in the stage detail (`PUBLISHED <version> auto-release <id> release <id>`). Each wait prints one JSON line every 2 minutes (`waiting auto-release.yml 4m`). The npm poll is `npm view @kontextmind/kxm@<version> version` every 30 seconds for 10 minutes. |
 | `milestone` | Compares `plans/kxm-roadmap/state.json` from before and after `docs`. When a phase goes from an open task to all tasks `done`, or the pull request body contains a `Milestone:` line, prints `deep_review_required: true` and exits 0. The review is the `/reanalyze-roadmap` skill, not this command. An absent state file passes with skipped. |
 
-Refusals (exit 1): `project_required`, `land_dirty_tree`, `land_verify_failed`, `land_docs_failed`, `land_push_rejected`, `land_pr_body_missing`, `land_conflict_manual`, `land_blocked`, `land_merge_failed`, `land_release_failed`, `land_publish_timeout`, `land_milestone_failed`.
+Refusals (exit 1): `project_required`, `land_dirty_tree`, `land_verify_failed`, `land_docs_failed`, `land_push_rejected`, `land_pr_body_missing`, `land_pr_title_missing`, `land_conflict_manual`, `land_blocked`, `land_merge_failed`, `land_release_failed`, `land_publish_timeout`, `land_milestone_failed`.
+
+`land_pr_title_missing`: the `pr` stage was not given `--title`, and the first commit subject on `origin/main..HEAD` is empty.
 
 ## `kxm assign`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.124",
+  "version": "0.7.126",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",

package/plugins/kxm/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "kxm",
   "displayName": "KXM",
-  "version": "0.7.124",
+  "version": "0.7.126",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",

package/plugins/kxm/dist/cli.js

@@ -37185,6 +37185,7 @@ function cmdLand(runtime, options = {}) {
   const args = [script];
   if (options.pr) args.push("--pr", options.pr);
   if (options.stage) args.push("--stage", options.stage);
+  if (options.title) args.push("--title", options.title);
   if (options.bodyFile) args.push("--body-file", options.bodyFile);
   if (runtime.json) args.push("--json");
   if (runtime.dryRun) args.push("--dry-run");
@@ -51581,7 +51582,7 @@ async function dispatchAgentCliCommand(runtime, toolName, rawArgs) {
     }
   }
 }
-function createProgram(ctx, result) {
+function createProgram(ctx, result, argv) {
   const bind = (action) => {
     return async function commandAction(...args) {
       const command = args.at(-1) instanceof Command ? args.at(-1) : this;
@@ -51591,7 +51592,11 @@ function createProgram(ctx, result) {
   const program2 = new Command(CLI_NAME2);
   program2.description("KXM local-first orchestration CLI").version(readInstalledKxmVersion(findKxmRepoRoot(import.meta.url)), "-V, --version", "Print the installed kxm version").exitOverride().configureOutput({
     writeOut: (text) => ctx.io.stdout(text),
-    writeErr: (text) => ctx.io.stderr(text)
+    // Subcommands inherit this object by reference (copyInheritedSettings).
+    writeErr: (text) => {
+      if (hasJsonFlag(argv)) return;
+      ctx.io.stderr(text);
+    }
   }).helpCommand("help", "Show help");
   addGlobalOptions(program2);
   program2.hook("preAction", (_program, actionCommand) => {
@@ -51636,10 +51641,11 @@ function createProgram(ctx, result) {
       ...options.timeoutMs !== void 0 ? { timeoutMs: options.timeoutMs } : {}
     });
   });
-  addGlobalOptions(program2.command("land").description("Land the current branch: verify, regenerate docs, push, pull request, rebase, unblock, squash-merge, release, and milestone")).option("--pr <n>", "Existing pull request number").option("--stage <name>", "Run one stage: verify, docs, push, pr, rebase, unblock, merge, release, or milestone").option("--body-file <path>", "Pull request body file used when creating a pull request").action(async function landAction(options) {
+  addGlobalOptions(program2.command("land").description("Land the current branch: verify, regenerate docs, push, pull request, rebase, unblock, squash-merge, release, and milestone")).option("--pr <n>", "Existing pull request number").option("--stage <name>", "Run one stage: verify, docs, push, pr, rebase, unblock, merge, release, or milestone").option("--title <text>", "Pull request title. Default is the subject of the first commit on the branch").option("--body-file <path>", "Pull request body file used when creating a pull request").action(async function landAction(options) {
     result.code = await cmdLand(runtimeFrom(ctx, this), {
       ...options.pr !== void 0 ? { pr: options.pr } : {},
       ...options.stage !== void 0 ? { stage: options.stage } : {},
+      ...options.title !== void 0 ? { title: options.title } : {},
       ...options.bodyFile !== void 0 ? { bodyFile: options.bodyFile } : {}
     });
   });
@@ -52116,10 +52122,55 @@ function createProgram(ctx, result) {
   });
   return program2;
 }
-function mapCommanderError(error) {
+function hasJsonFlag(argv) {
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--") break;
+    if (arg === "--json") return true;
+  }
+  return false;
+}
+function commandWords(argv) {
+  const words = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--") break;
+    if (!arg.startsWith("-")) {
+      words.push(arg);
+      continue;
+    }
+    if (arg.includes("=") || arg === "--json" || arg === "--dry-run" || arg === "-h" || arg === "--help" || arg === "-V" || arg === "--version") continue;
+    const next = argv[index + 1];
+    if (next !== void 0 && !next.startsWith("-")) index += 1;
+  }
+  return words;
+}
+function commandPathFromArgv(program2, argv) {
+  const names3 = [];
+  let current = program2;
+  for (const word of commandWords(argv)) {
+    const next = current.commands.find((command) => command.name() === word || command.aliases().includes(word));
+    if (!next) break;
+    names3.push(next.name());
+    current = next;
+  }
+  return names3.join(" ");
+}
+function mapCommanderError(error, argv, program2, io) {
   if (error.exitCode === 0) return 0;
-  if (USAGE_ERROR_CODES.has(error.code)) return 2;
-  return error.exitCode || 1;
+  const code = USAGE_ERROR_CODES.has(error.code) ? 2 : error.exitCode || 1;
+  if (code === 2 && hasJsonFlag(argv)) {
+    const command = commandPathFromArgv(program2, argv);
+    io.stdout(`${JSON.stringify({
+      schema: CLI_RESULT_SCHEMA,
+      ok: false,
+      command: command || "kxm",
+      error: "usage_error",
+      detail: error.message
+    })}
+`);
+  }
+  return code;
 }
 var MESH_REMOVED_TEXT = "kxm mesh was removed. Use kxm init, kxm hub start|view|stop, and node scripts/smoke-multi-pi.mjs (KXM_SMOKE=1).";
 function removedMeshInvocation(argv) {
@@ -52160,12 +52211,12 @@ async function runCli(argv, env = process.env, io = { stdout: (text) => process.
     return 2;
   }
   const result = { code: 0 };
-  const program2 = createProgram({ env, io, cwd }, result);
+  const program2 = createProgram({ env, io, cwd }, result, argv);
   try {
     await program2.parseAsync(argv, { from: "user" });
     return result.code;
   } catch (error) {
-    if (error instanceof CommanderError) return mapCommanderError(error);
+    if (error instanceof CommanderError) return mapCommanderError(error, argv, program2, io);
     if (error instanceof DryRunRefused) return error.code;
     throw error;
   }

package/plugins/kxm/dist/mcp-server.js

@@ -17313,7 +17313,7 @@ function sessionTokenFixHint(policy) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.124";
+var VERSION = "0.7.126";
 var CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.124",
+  "version": "0.7.126",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/src/cli/land.ts

@@ -7,6 +7,7 @@ import { print, type Runtime } from "./types.ts";
 export interface LandOptions {
   pr?: string;
   stage?: string;
+  title?: string;
   bodyFile?: string;
 }
 
@@ -35,6 +36,7 @@ export function cmdLand(runtime: Runtime, options: LandOptions = {}): Promise<nu
   const args = [script];
   if (options.pr) args.push("--pr", options.pr);
   if (options.stage) args.push("--stage", options.stage);
+  if (options.title) args.push("--title", options.title);
   if (options.bodyFile) args.push("--body-file", options.bodyFile);
   if (runtime.json) args.push("--json");
   if (runtime.dryRun) args.push("--dry-run");

package/plugins/kxm/src/cli.ts

@@ -31,6 +31,7 @@ import { projectRuntimeOwnsRun } from "./runtime-store.ts";
 
 // Submodule imports
 import {
+  CLI_RESULT_SCHEMA,
   print,
   refuseDryRun,
   runtimeFrom,
@@ -400,7 +401,7 @@ async function dispatchAgentCliCommand(
   }
 }
 
-function createProgram(ctx: CliContext, result: { code: number }): Command {
+function createProgram(ctx: CliContext, result: { code: number }, argv: readonly string[]): Command {
   const bind = (action: (runtime: Runtime, ...args: never[]) => Promise<number>) => {
     return async function commandAction(this: Command, ...args: unknown[]) {
       const command = args.at(-1) instanceof Command ? args.at(-1) as Command : this;
@@ -415,7 +416,11 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
     .exitOverride()
     .configureOutput({
       writeOut: (text) => ctx.io.stdout(text),
-      writeErr: (text) => ctx.io.stderr(text),
+      // Subcommands inherit this object by reference (copyInheritedSettings).
+      writeErr: (text) => {
+        if (hasJsonFlag(argv)) return;
+        ctx.io.stderr(text);
+      },
     })
     .helpCommand("help", "Show help");
   addGlobalOptions(program);
@@ -496,11 +501,13 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
   addGlobalOptions(program.command("land").description("Land the current branch: verify, regenerate docs, push, pull request, rebase, unblock, squash-merge, release, and milestone"))
     .option("--pr <n>", "Existing pull request number")
     .option("--stage <name>", "Run one stage: verify, docs, push, pr, rebase, unblock, merge, release, or milestone")
+    .option("--title <text>", "Pull request title. Default is the subject of the first commit on the branch")
     .option("--body-file <path>", "Pull request body file used when creating a pull request")
-    .action(async function landAction(this: Command, options: { pr?: string; stage?: string; bodyFile?: string }) {
+    .action(async function landAction(this: Command, options: { pr?: string; stage?: string; title?: string; bodyFile?: string }) {
       result.code = await cmdLand(runtimeFrom(ctx, this), {
         ...(options.pr !== undefined ? { pr: options.pr } : {}),
         ...(options.stage !== undefined ? { stage: options.stage } : {}),
+        ...(options.title !== undefined ? { title: options.title } : {}),
         ...(options.bodyFile !== undefined ? { bodyFile: options.bodyFile } : {}),
       });
     });
@@ -1434,10 +1441,57 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
   return program;
 }
 
-function mapCommanderError(error: CommanderError): number {
+function hasJsonFlag(argv: readonly string[]): boolean {
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]!;
+    if (arg === "--") break;
+    if (arg === "--json") return true;
+  }
+  return false;
+}
+
+function commandWords(argv: readonly string[]): string[] {
+  const words: string[] = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]!;
+    if (arg === "--") break;
+    if (!arg.startsWith("-")) {
+      words.push(arg);
+      continue;
+    }
+    if (arg.includes("=") || arg === "--json" || arg === "--dry-run" || arg === "-h" || arg === "--help" || arg === "-V" || arg === "--version") continue;
+    const next = argv[index + 1];
+    if (next !== undefined && !next.startsWith("-")) index += 1;
+  }
+  return words;
+}
+
+function commandPathFromArgv(program: Command, argv: readonly string[]): string {
+  const names: string[] = [];
+  let current: Command = program;
+  for (const word of commandWords(argv)) {
+    const next = current.commands.find((command) => command.name() === word || command.aliases().includes(word));
+    if (!next) break;
+    names.push(next.name());
+    current = next;
+  }
+  return names.join(" ");
+}
+
+function mapCommanderError(error: CommanderError, argv: readonly string[], program: Command, io: CliIo): number {
   if (error.exitCode === 0) return 0;
-  if (USAGE_ERROR_CODES.has(error.code)) return 2;
-  return error.exitCode || 1;
+  const code = USAGE_ERROR_CODES.has(error.code) ? 2 : (error.exitCode || 1);
+  if (code === 2 && hasJsonFlag(argv)) {
+    const command = commandPathFromArgv(program, argv);
+    io.stdout(`${JSON.stringify({
+      schema: CLI_RESULT_SCHEMA,
+      ok: false,
+      command: command || "kxm",
+      error: "usage_error",
+      detail: error.message,
+    })}\n`);
+  }
+  return code;
 }
 
 const MESH_REMOVED_TEXT = "kxm mesh was removed. Use kxm init, kxm hub start|view|stop, and node scripts/smoke-multi-pi.mjs (KXM_SMOKE=1).";
@@ -1486,12 +1540,12 @@ export async function runCli(
     return 2;
   }
   const result = { code: 0 };
-  const program = createProgram({ env, io, cwd }, result);
+  const program = createProgram({ env, io, cwd }, result, argv);
   try {
     await program.parseAsync(argv, { from: "user" });
     return result.code;
   } catch (error) {
-    if (error instanceof CommanderError) return mapCommanderError(error);
+    if (error instanceof CommanderError) return mapCommanderError(error, argv, program, io);
     if (error instanceof DryRunRefused) return error.code;
     throw error;
   }

package/plugins/kxm/src/mcp-server.ts

@@ -11,7 +11,7 @@ import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 import { sessionTokenFixHint } from "./session-token-hint.ts";
 
-const VERSION = "0.7.124";
+const VERSION = "0.7.126";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();

package/scripts/pr-land.mjs

@@ -28,6 +28,7 @@ const REBASE_ROUNDS = 5;
 const POLL_MS = positiveInt(process.env.KXM_LAND_POLL_MS, 30_000);
 const MERGE_WAIT_MS = 20 * 60 * 1000;
 const RELEASE_WAIT_MS = 20 * 60 * 1000;
+const RELEASE_PROGRESS_MS = 2 * 60 * 1000;
 const PUBLISH_WAIT_MS = 10 * 60 * 1000;
 const DOCS_COMMIT = "docs(roadmap): regenerate after verify";
 const GENERATOR = "plans/kxm-roadmap/update-dashboard.mjs";
@@ -40,6 +41,7 @@ const UNRELEASED_HEADING = "## Unreleased";
 const root = process.cwd();
 let dryRun = false;
 let bodyFile;
+let requestedTitle;
 let prNumber;
 let forceLease = false;
 let phasesSnapshotted = false;
@@ -198,13 +200,14 @@ function parseArgs(argv) {
       options.help = true;
       continue;
     }
-    if (arg === "--pr" || arg === "--body-file" || arg === "--stage") {
+    if (arg === "--pr" || arg === "--body-file" || arg === "--stage" || arg === "--title") {
       const value = argv[index + 1];
       if (value === undefined || value.startsWith("--")) return { error: `${arg} requires a value` };
       index += 1;
       if (arg === "--pr") options.pr = value;
       if (arg === "--body-file") options.bodyFile = value;
       if (arg === "--stage") options.stage = value;
+      if (arg === "--title") options.title = value;
       continue;
     }
     return { error: `unknown argument ${arg}` };
@@ -324,12 +327,24 @@ function pushStage() {
   return pass("push", { detail: forceLease ? "pushed with lease" : "pushed" });
 }
 
+function pullRequestTitle() {
+  const explicit = String(requestedTitle ?? "").trim();
+  if (explicit) return { ok: true, text: explicit };
+  const logged = run("git", ["log", "--reverse", "--format=%s", "origin/main..HEAD"]);
+  if (logged.status !== 0) return { ok: false, detail: "no commit subject on origin/main..HEAD" };
+  const subject = logged.stdout.split("\n").map((line) => line.trim()).find(Boolean) ?? "";
+  if (!subject) return { ok: false, detail: "no commit subject on origin/main..HEAD" };
+  return { ok: true, text: subject };
+}
+
 function prStage() {
+  const titled = pullRequestTitle();
   if (dryRun) {
+    if (!titled.ok) return refuse("pr", "land_pr_title_missing", titled.detail);
     return plan("pr", [
       "gh pr list --head <branch> --state open --json number,title",
-      "gh pr create --body-file <path>",
-    ]);
+      `gh pr create --title ${titled.text} --body-file <path>`,
+    ], titled.text);
   }
   const found = ensurePr();
   if (!found.ok) return refuse("pr", "land_pr_body_missing", found.detail);
@@ -337,12 +352,13 @@ function prStage() {
     prNumber = String(found.pr.number);
     return pass("pr", { detail: `reused #${prNumber}` });
   }
+  if (!titled.ok) return refuse("pr", "land_pr_title_missing", titled.detail);
   if (!bodyFile) return refuse("pr", "land_pr_body_missing", "creating a pull request requires --body-file");
   if (!existsSync(bodyFile.startsWith("/") ? bodyFile : join(root, bodyFile))) {
     return refuse("pr", "land_pr_body_missing", `body file not found: ${bodyFile}`);
   }
   const branch = found.branch || branchName();
-  const created = gh(["pr", "create", "--head", branch, "--title", branch, "--body-file", bodyFile]);
+  const created = gh(["pr", "create", "--head", branch, "--title", titled.text, "--body-file", bodyFile]);
   if (created.status !== 0) return refuse("pr", "land_pr_body_missing", created.stderr || created.stdout);
   const again = ensurePr();
   if (!again.ok || !again.pr?.number) return refuse("pr", "land_pr_body_missing", "pull request was not created");
@@ -782,27 +798,54 @@ function mergeStage() {
   return pass("merge", { detail: `squashed #${prNumber}` });
 }
 
-function selectRun(runs, title, after) {
+function selectRun(runs, title, after, earliest = false) {
   if (!Array.isArray(runs)) return undefined;
   const matches = runs.filter((runRow) => {
     if (!runRow || typeof runRow !== "object") return false;
     const display = String(runRow.displayTitle ?? "");
-    if (title && !display.includes(title)) return false;
+    if (!earliest && title && !display.includes(title)) return false;
     const created = Date.parse(String(runRow.createdAt ?? ""));
-    if (Number.isFinite(after) && Number.isFinite(created) && created < after) return false;
+    if (earliest) {
+      if (!Number.isFinite(after) || !Number.isFinite(created) || created <= after) return false;
+    } else if (Number.isFinite(after) && Number.isFinite(created) && created < after) {
+      return false;
+    }
     return true;
   });
-  matches.sort((left, right) => Date.parse(String(right.createdAt ?? "")) - Date.parse(String(left.createdAt ?? "")));
+  matches.sort((left, right) => {
+    const delta = Date.parse(String(left.createdAt ?? "")) - Date.parse(String(right.createdAt ?? ""));
+    return earliest ? delta : -delta;
+  });
   return matches[0];
 }
 
-function waitForWorkflow(workflow, title, after) {
+function workflowRunId(run) {
+  if (!run || typeof run !== "object" || run.databaseId === undefined || run.databaseId === null) return "";
+  return String(run.databaseId);
+}
+
+function noteReleaseWait(workflow, started, logged) {
+  const minutes = Math.floor((Date.now() - started) / RELEASE_PROGRESS_MS) * 2;
+  if (minutes < 2 || minutes <= logged.minutes) return;
+  logged.minutes = minutes;
+  emit({ stage: "release", ok: true, detail: `waiting ${workflow} ${minutes}m` });
+}
+
+function waitForWorkflow(workflow, title, after, earliest = false) {
+  const started = Date.now();
+  const logged = { minutes: 0 };
   let failure = "";
   const polled = poll(RELEASE_WAIT_MS, () => {
-    const listed = ghJson(["run", "list", `--workflow=${workflow}`, "--json", "status,conclusion,displayTitle,createdAt"]);
-    if (!listed.ok) return { done: false, detail: listed.result.stderr || listed.result.stdout };
-    const match = selectRun(listed.value, title, after);
-    if (!match) return { done: false };
+    const listed = ghJson(["run", "list", `--workflow=${workflow}`, "--json", "databaseId,status,conclusion,displayTitle,createdAt"]);
+    if (!listed.ok) {
+      noteReleaseWait(workflow, started, logged);
+      return { done: false, detail: listed.result.stderr || listed.result.stdout };
+    }
+    const match = selectRun(listed.value, title, after, earliest);
+    if (!match) {
+      noteReleaseWait(workflow, started, logged);
+      return { done: false };
+    }
     const conclusion = String(match.conclusion ?? "").toLowerCase();
     const status = String(match.status ?? "").toLowerCase();
     if (conclusion === "success") return { done: true, run: match };
@@ -810,6 +853,7 @@ function waitForWorkflow(workflow, title, after) {
       failure = `${workflow} concluded ${conclusion}`;
       return { done: true, failed: true };
     }
+    noteReleaseWait(workflow, started, logged);
     return { done: false };
   });
   if (polled.failed) return { ok: false, detail: failure };
@@ -820,11 +864,11 @@ function waitForWorkflow(workflow, title, after) {
 function releaseStage() {
   if (dryRun) {
     return plan("release", [
-      "gh run list --workflow=auto-release.yml --json status,conclusion,displayTitle,createdAt",
+      "gh run list --workflow=auto-release.yml --json databaseId,status,conclusion,displayTitle,createdAt",
       "git ls-remote --tags origin",
-      "gh run list --workflow=release.yml --json status,conclusion,displayTitle,createdAt",
+      "gh run list --workflow=release.yml --json databaseId,status,conclusion,displayTitle,createdAt",
       "npm view @kontextmind/kxm@<version> version",
-    ], "npm poll is 10 minutes");
+    ], "npm poll is 10 minutes; Release is matched by time after Auto-Release");
   }
   const context = readReleaseContext();
   const found = ensurePr();
@@ -838,8 +882,12 @@ function releaseStage() {
   if (!tags.tag || (previous && versionCompare(tags.tag, previous) <= 0)) {
     return refuse("release", "land_release_failed", `tag ${tags.tag || "(none)"} is not newer than ${previous || "(none)"}`);
   }
-  const release = waitForWorkflow("release.yml", title, after);
+  const autoCreated = Date.parse(String(auto.run?.createdAt ?? ""));
+  const release = waitForWorkflow("release.yml", "", autoCreated, true);
   if (!release.ok) return refuse("release", "land_release_failed", release.detail);
+  const autoReleaseRunId = workflowRunId(auto.run);
+  const releaseRunId = workflowRunId(release.run);
+  writeReleaseContext({ autoReleaseRunId, releaseRunId });
   const version = tags.tag.replace(/^v/, "");
   const published = poll(PUBLISH_WAIT_MS, () => {
     const viewed = run("npm", ["view", `@kontextmind/kxm@${version}`, "version"]);
@@ -847,7 +895,7 @@ function releaseStage() {
     return { done: false };
   });
   if (!published.version) return refuse("release", "land_publish_timeout", `npm view @kontextmind/kxm@${version} version`);
-  return pass("release", { detail: `PUBLISHED ${published.version}` });
+  return pass("release", { detail: `PUBLISHED ${published.version} auto-release ${autoReleaseRunId} release ${releaseRunId}` });
 }
 
 function taskStatuses(tasks) {
@@ -950,12 +998,13 @@ function main() {
     emit({
       stage: "usage",
       ok: true,
-      detail: "node scripts/pr-land.mjs [--pr <n>] [--body-file <path>] [--stage <name>] [--json] [--dry-run]",
+      detail: "node scripts/pr-land.mjs [--pr <n>] [--title <text>] [--body-file <path>] [--stage <name>] [--json] [--dry-run]",
     });
     return 0;
   }
   dryRun = parsed.options.dryRun;
   bodyFile = parsed.options.bodyFile;
+  requestedTitle = parsed.options.title;
   prNumber = parsed.options.pr;
   const names = parsed.options.stage ? [parsed.options.stage] : STAGES;
   for (const name of names) {