@kontextmind/kxm 0.7.123 → 0.7.125

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

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

@@ -0,0 +1,20 @@
+schema: kxm.workflow.v1
+description: One implementer step with a drive receipt. Replaces just impl.
+coordinator: coordinator
+limits:
+  maxTransitions: 2
+steps:
+  - id: implement
+    kind: agent
+    agent: implementer
+    repositories:
+      control: write
+    maxAttempts: 1
+    timeoutMs: 3600000
+    on:
+      passed:
+        target: $terminal
+        terminalStatus: completed
+      failed:
+        target: $terminal
+        terminalStatus: failed

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

@@ -0,0 +1,20 @@
+schema: kxm.workflow.v1
+description: One read-only architecture critic step. Replaces just review-arch.
+coordinator: coordinator
+limits:
+  maxTransitions: 2
+steps:
+  - id: critic-arch
+    kind: agent
+    agent: critic-arch
+    repositories:
+      control: read
+    maxAttempts: 1
+    timeoutMs: 1800000
+    on:
+      passed:
+        target: $terminal
+        terminalStatus: completed
+      failed:
+        target: $terminal
+        terminalStatus: failed

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

@@ -0,0 +1,20 @@
+schema: kxm.workflow.v1
+description: One read-only CLI critic step. Replaces just review-cli.
+coordinator: coordinator
+limits:
+  maxTransitions: 2
+steps:
+  - id: critic-cli
+    kind: agent
+    agent: critic-cli
+    repositories:
+      control: read
+    maxAttempts: 1
+    timeoutMs: 1800000
+    on:
+      passed:
+        target: $terminal
+        terminalStatus: completed
+      failed:
+        target: $terminal
+        terminalStatus: failed

package/CHANGELOG.md

@@ -6,6 +6,23 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Added
 
+- **A live agent step uses a configurable one-shot timeout, and a cancelling run recovers when its child has already exited.**
+  The bound is the step `timeoutMs`, or the project `limits.agentStepTimeoutMs`
+  when the step omits it (minimum 60 seconds, default one hour). A wider step
+  is refused at prerequisites (`step_unsupported`, field `timeoutMs`). The
+  effective value is written on the one-shot evidence. A `cancelling` run whose
+  executing attempt's child already exited settles `executing_unrecorded`.
+  Admission is released when a drive closes with a handoff, so a later drive
+  is admitted, and `runs status` names the attempt. `implement-only`,
+  `review-arch-only`, and `review-cli-only` are one-step workflows, driven with
+  `kxm lane run <unit> --workflow <id> --brief <file>`. See
+  [kxm lane](docs/reference/cli-reference.md#kxm-lane),
+  [runs status](docs/reference/cli-reference.md#kxm-runs-status),
+  [project limits](docs/reference/config-reference.md#kxmprojectyaml-kxmprojectv1),
+  [step fields](docs/reference/config-reference.md#step-fields),
+  [developer workflows](docs/reference/workflow-catalog.md#repository-developer-workflows),
+  and the [transport recipes](docs/contributing/assignment-runner.md#transport-only-recipes).
+
 - **`kxm land` verifies, regenerates docs, and squash-merges the current branch.**
   The stages are `verify`, `docs`, `push`, `pr`, `rebase`, `unblock`, `merge`,
   `release`, and `milestone`. `npm run verify` is the first stage and is not
@@ -30,9 +47,9 @@ All notable user-facing changes are documented here. The project follows [Semant
   and `cancel`. The `just worktree` and `just worktree-drop` recipes now call
   those verbs. The refusals a user can see are `lane_exists`, `lane_missing`,
   `lane_base_unresolved`, `lane_dirty`, `lane_run_open`, `brief_unreadable` and
-  `brief_and_prompt`. A live writer step through `kxm lane run` is still
-  bounded by the Runtime's 120 second one-shot timeout until the configurable
-  limit lands. See the
+  `brief_and_prompt`. A live writer step through `kxm lane run` is bounded by
+  the step's `timeoutMs` or the project's `limits.agentStepTimeoutMs`, default
+  one hour. See the
   [CLI reference](docs/reference/cli-reference.md#kxm-lane).
 
 - **The tailnet docs site is built and served with `kxm docs build` and `kxm docs serve`.**
@@ -121,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
@@ -386,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/contributing/assignment-runner.md

@@ -313,10 +313,21 @@ It writes `recording-resolved.json` in the record directory. It never changes
 
 ## Transport-only recipes
 
-`just impl|plan|review-arch|review-cli` and `just dispatch` send one
-`kxm.harness-request.v1` envelope through `scripts/harness-run.mjs` and print a
-`kxm.harness-result.v2` envelope. They are harness transport only. They mint no
-assignment, witness or acceptance proof, so their output cannot be accepted.
+Drive a one-step workflow in a lane. Each command writes a drive receipt and
+the checkout fingerprint. `just impl`, `just plan`, `just review-arch`,
+`just review-cli`, and `just impl-bg` are retired in favor of these. The
+recipes stay in the justfile until one real unit has been driven this way.
+
+```bash
+kxm lane run <unit> --workflow implement-only --brief <file>
+kxm lane run <unit> --workflow review-arch-only --brief <file>
+kxm lane run <unit> --workflow review-cli-only --brief <file>
+```
+
+`just dispatch` still sends one `kxm.harness-request.v1` envelope through
+`scripts/harness-run.mjs` and prints a `kxm.harness-result.v2` envelope. It
+mints no assignment, witness or acceptance proof, so its output cannot be
+accepted. The retired recipes did the same.
 
 ### Preflight refusals
 

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
 
@@ -1431,7 +1432,7 @@ Refusals (exit 1): `lane_missing`, `lane_dirty`, `lane_run_open`, `lane_git_fail
 
 Creates the lane when the record is absent (same rules as `create`), refuses `lane_run_open` when the last run is not settled, then runs the same path as `kxm run --lane <unit> --brief <file>` and `kxm runs drive <runId> --lane <unit>`. `--wait` and `--timeout-ms` are passed through. The run id is stored on the record. Prints the run envelope and the drive result. That open-run check may start the Runtime supervisor; `--dry-run` only attaches to a supervisor that is already running. `kxm lane status` never starts the supervisor.
 
-`--brief` is required. `--workflow` defaults to the lane project's `defaultWorkflow`. `--base` applies only when the lane is created. A live writer step through this verb is subject to the Runtime's one-shot process timeout, which is 120 seconds until `limits.agentStepTimeoutMs` lands, so long implementation briefs should use `just impl-bg` until then (see section 4 of `plans/plan-lane-cli.md`).
+`--brief` is required. `--workflow` defaults to the lane project's `defaultWorkflow`. `--base` applies only when the lane is created. A live agent step uses the step `timeoutMs` when it is set, otherwise the project `limits.agentStepTimeoutMs` (default 3,600,000). This repository's `implement-only`, `review-arch-only`, and `review-cli-only` workflows are the lane forms of the retired transport recipes.
 
 Refusals (exit 1): `brief_unreadable`, `lane_unit_invalid`, `lane_exists`, `lane_base_unresolved`, `lane_run_open`, `lane_git_failed`, `lane_not_project`, `lanes_unreadable`.
 
@@ -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/docs/reference/config-reference.md

@@ -165,6 +165,7 @@ makes a directory a KXM project. Parser: `loadKxmProject` in
 | `limits.maxConcurrentRuns` | Integer, 1 to 128 | Optional, `1` | Runtime admission. A changed bound is refused (`scheduler_policy_conflict`) while admitted or queued runs still use the previous one. |
 | `limits.maxRunDurationMs` | Integer, 0 to 31,536,000,000 | Optional | Runtime. Combined with the workflow's own value; the smaller one wins. |
 | `limits.maxAgentTimeMs` | Integer, 0 to 31,536,000,000 | Optional | Runtime refuses to drive any run while it is set (`limit_unsupported`); leave it out |
+| `limits.agentStepTimeoutMs` | Integer, 60,000 to 31,536,000,000 | Optional, 3,600,000 | Wall clock for one live agent or moa step when the step omits `timeoutMs`. The supervisor passes it to the one-shot producer. A step `timeoutMs` narrower than this wins; a wider step value is refused (`step_unsupported`, field `timeoutMs`) |
 
 The Runtime binds one project `id` to one control root per state root, so a
 second checkout with the same ID is refused with `project_home_conflict`.
@@ -555,7 +556,7 @@ Duration budgets use the wall clock. `maxRunDurationMs` counts from the time the
 | `signal` | Identifier | Required for `wait` | Compiled and diffed; the Runtime does not match signals to wait steps yet |
 | `model` | Model selector | Optional | Intersected with each allowed agent's own model ceiling; an empty intersection is `model_selector_incompatible`. Live route resolution ignores it. The Runtime refuses it on gate steps. |
 | `maxAttempts` | Integer, 1 to 20 | Optional, `1` | Entering the step again after this many attempts fails the run (`budget_step_attempts`) |
-| `timeoutMs` | Integer, 0 to 31,536,000,000 | Optional | Not `0`. Gate steps: refused for `artifacts-exist` gates or below the gate's `timeoutMs`. Other kinds: unused; the producer times out at 120 s |
+| `timeoutMs` | Integer, 0 to 31,536,000,000 | Optional | Not `0`. Gate steps: refused for `artifacts-exist` gates or below the gate's `timeoutMs`. Agent and moa steps: the one-shot spawn uses this value when it is at most `limits.agentStepTimeoutMs`; a wider value is refused (`step_unsupported`, field `timeoutMs`). When the step omits it, the project limit applies (default 3,600,000). The process default of 120 seconds is only the last resort when neither is set |
 | `repositories` | Map of repository ID to `none`, `read`, or `write` | Optional | IDs must be declared (`repository_unknown`); may not exceed the agent's ceiling (`repository_scope_expansion`) |
 | `tools` | `{preset, allow, deny}` | Optional | Must keep the agent's preset and denials and allow only tools the agent allows (`tool_scope_expansion`). The Runtime refuses steps that declare `tools`. |
 | `secrets` | `[{ref, as, required}]` | Optional | Only refs the agent grants (`secret_scope_expansion`). The Runtime refuses steps that declare `secrets`. |

package/docs/reference/workflow-catalog.md

@@ -1090,6 +1090,16 @@ This cross-reference points each software and security workflow at the KXM pages
 
 `kxm run land --dry-run --json` may be refused by live prerequisites until gate-only workflows are supported. The command `kxm land` runs the same stages without a run receipt.
 
+## Repository developer workflows
+
+These three files live in this repository's `.kxm/workflows`. `kxm init` does not write them.
+
+| Workflow | Replaces |
+|---|---|
+| `implement-only` | `just impl`. The recipe is retired once this lands. |
+| `review-arch-only` | `just review-arch`. The recipe is retired once this lands. |
+| `review-cli-only` | `just review-cli`. The recipe is retired once this lands. |
+
 ## Related
 
 - [Workflow definitions](workflow-definitions.md): write a webhook or Runtime workflow for these stages

package/docs/reference/workflow-definitions.md

@@ -271,7 +271,7 @@ A Runtime workflow is a YAML file whose name is its ID. The [configuration file
 | Transitions | `on` is required on every step. `$terminal` needs `terminalStatus` (`completed`, `failed` or `cancelled`). Each back-edge needs its own `maxTransitions`, plus `limits.maxTransitions` | [Transitions and outcomes](config-reference.md#transitions-and-outcomes) |
 | Gate outcome keys | An `expect: pass` gate produces `passed` or `implementation-failure`; an `expect: fail` gate produces `passed` or `repro-missing`. Declare both produced outcomes | [Transitions and outcomes](config-reference.md#transitions-and-outcomes) |
 | `gate_outcome_impossible` | Refused at load when a gate step declares an outcome it never produces, such as `failed`, and omits one it produces. `gate_outcome_renamed` catches underscore spellings | [Transitions and outcomes](config-reference.md#transitions-and-outcomes) |
-| Agent steps | The model returns a JSON `outcome` from the step's declared keys; anything else becomes `failed`, so declare `failed` | [Transitions and outcomes](config-reference.md#transitions-and-outcomes) |
+| Agent steps | The model returns a JSON `outcome` from the step's declared keys; anything else becomes `failed`, so declare `failed`. `timeoutMs` bounds the one-shot spawn for `agent` and `moa` steps, and must not be wider than the project `limits.agentStepTimeoutMs` | [Step fields](config-reference.md#step-fields) |
 | Not executed yet | Some valid fields make the Runtime hand the run off (`step_unsupported`, `gate_unsupported`, `limit_unsupported`) instead of executing | [Steps the Runtime does not execute yet](config-reference.md#steps-the-runtime-does-not-execute-yet) |
 
 `kxm workflow add bug-fix --template implement-and-verify` writes a valid starting file; `dual-critic-review` and `spec-and-plan` are also available. IDs are flat filename-derived slugs, not catalog paths such as `software-engineering/bug-fix`. Installation validates YAML/schema/transitions before writing, including under `--dry-run`. `kxm run <workflow>` creates a run and reports live prerequisites and separate `runs drive/status/receipt` commands. Current live one-shot profiles are read-only, so a writer template can validate but cannot execute live; `task run` refuses incompatible work before creating a run or changing the task. Simulation remains explicitly available and is not proof of implementation. See [`kxm run`](cli-reference.md#kxm-run) and [`kxm runs`](cli-reference.md#kxm-runs).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.123",
+  "version": "0.7.125",
   "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.123",
+  "version": "0.7.125",
   "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

@@ -21375,13 +21375,16 @@ function objectValue3(value) {
 function kxmProjectAdmissionLimits(bundle) {
   const limits = objectValue3(bundle.project.value.limits);
   const maxConcurrentRuns = typeof limits?.maxConcurrentRuns === "number" && Number.isInteger(limits.maxConcurrentRuns) && limits.maxConcurrentRuns >= 1 ? limits.maxConcurrentRuns : 1;
+  const declared = limits?.agentStepTimeoutMs;
+  const agentStepTimeoutMs = typeof declared === "number" && Number.isInteger(declared) && declared >= KXM_MIN_AGENT_STEP_TIMEOUT_MS ? declared : KXM_DEFAULT_AGENT_STEP_TIMEOUT_MS;
   return {
     maxConcurrentRuns,
     ...typeof limits?.maxRunDurationMs === "number" ? { maxRunDurationMs: limits.maxRunDurationMs } : {},
-    ...typeof limits?.maxAgentTimeMs === "number" ? { maxAgentTimeMs: limits.maxAgentTimeMs } : {}
+    ...typeof limits?.maxAgentTimeMs === "number" ? { maxAgentTimeMs: limits.maxAgentTimeMs } : {},
+    agentStepTimeoutMs
   };
 }
-var RUNTIME_EPOCH_NS;
+var KXM_DEFAULT_AGENT_STEP_TIMEOUT_MS, KXM_MIN_AGENT_STEP_TIMEOUT_MS, RUNTIME_EPOCH_NS;
 var init_runtime_service = __esm({
   "plugins/kxm/src/runtime-service.ts"() {
     "use strict";
@@ -21391,6 +21394,8 @@ var init_runtime_service = __esm({
     init_engine_plan();
     init_runtime_owner();
     init_runtime_store();
+    KXM_DEFAULT_AGENT_STEP_TIMEOUT_MS = 36e5;
+    KXM_MIN_AGENT_STEP_TIMEOUT_MS = 6e4;
     RUNTIME_EPOCH_NS = process.hrtime.bigint();
   }
 });
@@ -21400,6 +21405,7 @@ var TEXT_LIMIT, ARGV_LIMIT, RECORD_LIMIT;
 var init_oneshot_evidence = __esm({
   "plugins/kxm/src/oneshot-evidence.ts"() {
     "use strict";
+    init_bindings();
     TEXT_LIMIT = 4 * 1024 * 1024;
     ARGV_LIMIT = 64 * 1024;
     RECORD_LIMIT = 16 * 1024 * 1024;
@@ -23195,6 +23201,15 @@ function resolveProducerRoute(projectRoot, step, agentId) {
   const model = selector.slice(slash + 1);
   return { provider, model, selector };
 }
+function unsupportedAgentStepTimeout(step, limitMs) {
+  if (step.kind !== "agent" && step.kind !== "moa") return void 0;
+  if (step.timeoutMs === void 0 || step.timeoutMs <= limitMs) return void 0;
+  return {
+    reason: "step_unsupported",
+    field: "timeoutMs",
+    detail: "step timeoutMs is wider than project limits.agentStepTimeoutMs"
+  };
+}
 function kxmLiveRunPrerequisites(bundle, workflowId, projectRoot) {
   const workflow = bundle.workflows.get(workflowId);
   if (!workflow) throw runtimeError("run_workflow_unknown", workflowId, `workflow ${workflowId} does not exist in this project`);
@@ -23213,7 +23228,8 @@ function kxmLiveRunPrerequisites(bundle, workflowId, projectRoot) {
     for (const transition2 of Object.values(step.transitions)) {
       if (transition2.to === "step") pending.push(transition2.target);
     }
-    const unsupported = step.kind === "gate" ? unsupportedGateStep(plan, step, envelope, { projectRoot }) ?? starterGatePrerequisite(step, envelope.gates, projectRoot) : unsupportedStep(plan, step, "oneshot");
+    const limitMs = envelope.projectLimits.agentStepTimeoutMs ?? KXM_DEFAULT_AGENT_STEP_TIMEOUT_MS;
+    const unsupported = step.kind === "gate" ? unsupportedGateStep(plan, step, envelope, { projectRoot }) ?? starterGatePrerequisite(step, envelope.gates, projectRoot) : unsupportedAgentStepTimeout(step, limitMs) ?? unsupportedStep(plan, step, "oneshot");
     if (unsupported) {
       prerequisites.push({ ...unsupported, stepId });
       continue;
@@ -23533,6 +23549,7 @@ var init_engine = __esm({
     init_context_packet();
     init_engine_compile();
     init_harness();
+    init_oneshot_evidence();
     init_engine_fold();
     init_engine_plan();
     init_dispatch_context();
@@ -23556,7 +23573,6 @@ var init_oneshot_producer = __esm({
   "plugins/kxm/src/oneshot-producer.ts"() {
     "use strict";
     init_oneshot_evidence();
-    init_bindings();
     init_oneshot_process();
     init_oneshot_process();
     init_harness();
@@ -26990,7 +27006,10 @@ function formatDriveStatusLine(runStatus, drive) {
 }
 function formatRunStatusLine(run, drive) {
   const reason = typeof drive?.receipt?.settlement?.reason === "string" ? drive.receipt.settlement.reason : "";
-  const statusLabel = run.status === "cancelled" ? formatCancelledStatus(reason) : run.status;
+  const handoff = drive?.receipt?.settlement?.handoff;
+  const attemptId = typeof handoff?.attemptId === "string" ? handoff.attemptId : "";
+  const handoffReason = typeof handoff?.reason === "string" ? handoff.reason : "";
+  const statusLabel = run.status === "cancelled" ? formatCancelledStatus(reason) : run.status === "cancelling" && attemptId.length > 0 && handoffReason.length > 0 ? `cancelling (attempt ${attemptId}, ${handoffReason})` : run.status;
   return `run ${run.runId}: ${statusLabel} (workflow ${run.workflowId}, updated ${run.updatedAt})`;
 }
 async function cmdKxmRunStatus(runtime, runId) {
@@ -37166,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");
@@ -51562,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;
@@ -51572,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) => {
@@ -51617,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 } : {}
     });
   });
@@ -52097,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) {
@@ -52141,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.123";
+var VERSION = "0.7.125";
 var CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();