@kontextmind/kxm 0.7.119 → 0.7.121

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

@@ -415,28 +415,31 @@ export function resolveKxmRunTarget(
   runtime: Runtime,
   workflow: string | undefined,
   forTask = false,
+  envelope: Record<string, unknown> = {},
+  allowDefaultWorkflow = false,
 ): { projectRoot: string; workflowId: string; configRevision: string; defaultHarness: string; prerequisites: KxmRunHandoff[] } | number {
   if (runtime.workspaceFlag !== undefined) {
     print(runtime.io, runtime.json, {
       ok: false,
       command: "run",
       error: "workspace_option_unsupported",
+      ...envelope,
     }, "kxm run discovers the authoritative project from the current directory; --workspace is not supported");
     return 2;
   }
-  if (!workflow && !forTask) {
-    print(runtime.io, runtime.json, { ok: false, command: "run", error: "workflow_required" }, "usage: kxm run <workflow> [prompt]");
+  if (!workflow && !forTask && !allowDefaultWorkflow) {
+    print(runtime.io, runtime.json, { ok: false, command: "run", error: "workflow_required", ...envelope }, "usage: kxm run <workflow> [prompt]");
     return 2;
   }
   const projectRoot = discoverKxmProjectRoot(runtime.cwd);
   if (!projectRoot) {
-    print(runtime.io, runtime.json, { ok: false, command: "run", error: "project_required" }, "kxm run requires a KXM project (run kxm init first)");
+    print(runtime.io, runtime.json, { ok: false, command: "run", error: "project_required", ...envelope }, "kxm run requires a KXM project (run kxm init first)");
     return 1;
   }
   const bundle = loadKxmProject(projectRoot, {});
   const workflowId = workflow ?? String(bundle.project.value.defaultWorkflow ?? "default");
   if (!bundle.workflows.has(workflowId)) {
-    print(runtime.io, runtime.json, { ok: false, command: "run", error: "run_workflow_unknown", workflow: workflowId }, `workflow ${workflowId} does not exist in this project`);
+    print(runtime.io, runtime.json, { ok: false, command: "run", error: "run_workflow_unknown", workflow: workflowId, ...envelope }, `workflow ${workflowId} does not exist in this project`);
     return 1;
   }
   const defaultHarness = String(bundle.project.value.defaultHarness ?? "pi");
@@ -451,9 +454,16 @@ export function resolveKxmRunTarget(
   return { projectRoot, workflowId, configRevision: bundle.configRevision, defaultHarness, prerequisites };
 }
 
-export async function cmdKxmRun(runtime: Runtime, workflow: string | undefined, promptParts: string[], forTask = false): Promise<number> {
+export async function cmdKxmRun(
+  runtime: Runtime,
+  workflow: string | undefined,
+  promptParts: string[],
+  forTask = false,
+  call?: { brief?: string; prompt?: string; runIdOut?: { runId?: string }; allowDefaultWorkflow?: boolean },
+): Promise<number> {
+  const envelope = call?.brief !== undefined ? { brief: call.brief } : {};
   try {
-    const target = resolveKxmRunTarget(runtime, workflow, forTask);
+    const target = resolveKxmRunTarget(runtime, workflow, forTask, envelope, call?.allowDefaultWorkflow === true);
     if (typeof target === "number") return target;
     const { projectRoot } = target;
     if (runtime.dryRun) {
@@ -461,21 +471,24 @@ export async function cmdKxmRun(runtime: Runtime, workflow: string | undefined,
         ok: true,
         command: "run",
         dryRun: true,
+        ...envelope,
         ...target,
       }, `run plan: workflow ${target.workflowId} at ${target.configRevision.slice(0, 19)}… (no run created)`);
       return 0;
     }
     const supervisor = await (kxmDriveCliSeams.ensureSupervisor ?? ensureKxmSupervisor)({ env: runtime.env });
-    const prompt = promptParts.join(" ").trim();
+    const prompt = call?.prompt !== undefined ? call.prompt : promptParts.join(" ").trim();
     const acceptance = await (kxmDriveCliSeams.runtimeRequest ?? kxmRuntimeRequest)(supervisor, "POST", "/v1/runs", {
       projectRoot,
       workflowId: target.workflowId,
       prompt,
     });
     const run = acceptance.run as { runId: string; homeRuntimeId: string; status: string; configRevision: string };
+    if (call?.runIdOut) call.runIdOut.runId = run.runId;
     print(runtime.io, runtime.json, {
       ok: true,
       command: "run",
+      ...envelope,
       execution: {
         status: "not_started",
         mode: "live",
@@ -496,10 +509,10 @@ export async function cmdKxmRun(runtime: Runtime, workflow: string | undefined,
     return 0;
   } catch (error) {
     if (error instanceof KxmConfigError) {
-      print(runtime.io, runtime.json, { ok: false, command: "run", error: "run_failed", issues: error.issues }, `run failed: ${error.message}`);
+      print(runtime.io, runtime.json, { ok: false, command: "run", error: "run_failed", issues: error.issues, ...envelope }, `run failed: ${error.message}`);
       return 1;
     }
-    print(runtime.io, runtime.json, { ok: false, command: "run", error: "run_io_failed" }, "run failed because a local operation did not complete");
+    print(runtime.io, runtime.json, { ok: false, command: "run", error: "run_io_failed", ...envelope }, "run failed because a local operation did not complete");
     return 1;
   }
 }

package/plugins/kxm/src/cli.ts

@@ -104,7 +104,6 @@ import {
 cmdBackup,
   cmdRestore,
   cmdKxmTrust,
-  cmdKxmRun,
   cmdKxmRunStatus,
   cmdKxmRunDrive,
   cmdKxmRunReceipt,
@@ -122,6 +121,18 @@ cmdBackup,
 
 import { cmdPluginInstall } from "./cli/plugins.ts";
 
+import {
+  applyLane,
+  cmdKxmRunCli,
+  cmdLaneCreate,
+  cmdLaneDrop,
+  cmdLaneList,
+  cmdLaneRun,
+  cmdLaneStatus,
+} from "./cli/lanes.ts";
+
+import { cmdLand } from "./cli/land.ts";
+
 import {
   cmdStatus,
   cmdDash,
@@ -187,6 +198,8 @@ const USAGE_ERROR_CODES = new Set([
  */
 const DRY_RUN_COMMANDS: ReadonlySet<string> = new Set([
   "init", "backup", "restore", "run", "explain", "suggest", "update", "dash", "completion", "completion install",
+  "lane create", "lane list", "lane status", "lane drop", "lane run",
+  "land",
   "plugin install", "plugin",
   "runs status", "runs drive", "runs receipt", "runs cancel", "runs list",
   "tenant status", "models inventory-refresh", "harness list", "auth token",
@@ -435,26 +448,88 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
       result.code = await cmdRestore(runtimeFrom(ctx, this), manifest, options);
     });
 
+  const laneCmd = addGlobalOptions(program.command("lane").description("Manage one git worktree per unit of work"));
+  laneCmd.helpCommand("help", "Show lane help");
+  addGlobalOptions(laneCmd.command("create").description("Create a worktree lane from a base ref (default origin/main)"))
+    .argument("<unit>", "Lane unit name")
+    .option("--base <ref>", "Base ref to resolve before adding the worktree (default origin/main)")
+    .action(async function laneCreateAction(this: Command, unit: string, options: { base?: string }) {
+      result.code = await cmdLaneCreate(runtimeFrom(ctx, this), unit, options);
+    });
+  addGlobalOptions(laneCmd.command("list").description("List lanes with dirty, ahead, and behind counts"))
+    .action(async function laneListAction(this: Command) {
+      result.code = await cmdLaneList(runtimeFrom(ctx, this));
+    });
+  addGlobalOptions(laneCmd.command("status").description("Show one lane and the projected status of its last run"))
+    .argument("<unit>", "Lane unit name")
+    .action(async function laneStatusAction(this: Command, unit: string) {
+      result.code = await cmdLaneStatus(runtimeFrom(ctx, this), unit);
+    });
+  addGlobalOptions(laneCmd.command("drop").description("Remove a lane worktree and its record without deleting the branch"))
+    .argument("<unit>", "Lane unit name")
+    .option("--force", "Remove a dirty lane or one whose last run is still open")
+    .action(async function laneDropAction(this: Command, unit: string, options: { force?: boolean }) {
+      result.code = await cmdLaneDrop(runtimeFrom(ctx, this), unit, { force: options.force === true });
+    });
+  addGlobalOptions(laneCmd.command("run").description("Create the lane if needed, start a run from a brief, and drive it"))
+    .argument("<unit>", "Lane unit name")
+    .requiredOption("--brief <file>", "Read the run prompt from a file")
+    .option("--workflow <id>", "Workflow id (default: the project default)")
+    .option("--base <ref>", "Base ref when the lane does not exist yet (default origin/main)")
+    .option("--wait", "Wait until a drive receipt is recorded")
+    .option("--timeout-ms <n>", "Wait timeout in milliseconds (default 60000, max 600000)")
+    .action(async function laneRunAction(this: Command, unit: string, options: { brief?: string; workflow?: string; base?: string; wait?: boolean; timeoutMs?: string }) {
+      result.code = await cmdLaneRun(runtimeFrom(ctx, this), unit, {
+        ...(options.brief !== undefined ? { brief: options.brief } : {}),
+        ...(options.workflow !== undefined ? { workflow: options.workflow } : {}),
+        ...(options.base !== undefined ? { base: options.base } : {}),
+        wait: options.wait === true,
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+      });
+    });
+
+  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("--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 }) {
+      result.code = await cmdLand(runtimeFrom(ctx, this), {
+        ...(options.pr !== undefined ? { pr: options.pr } : {}),
+        ...(options.stage !== undefined ? { stage: options.stage } : {}),
+        ...(options.bodyFile !== undefined ? { bodyFile: options.bodyFile } : {}),
+      });
+    });
+
   addGlobalOptions(program.command("run").description("Create a KXM run without executing steps; follow its prerequisites, then kxm runs drive <runId> --wait")
     .argument("[workflow]", "Workflow id to run")
     .argument("[prompt...]", "Run prompt (events keep its hash; the full text is kept in a local 0600 sidecar file)")
-    .action(async function runAction(this: Command, workflow: string | undefined, promptParts: string[]) {
-      result.code = await cmdKxmRun(runtimeFrom(ctx, this), workflow, promptParts);
+    .option("--brief <file>", "Read the run prompt from a file instead of the positional prompt")
+    .option("--lane <unit>", "Discover the project from this lane's worktree")
+    .action(async function runAction(this: Command, workflow: string | undefined, promptParts: string[], options: { brief?: string; lane?: string }) {
+      result.code = await cmdKxmRunCli(runtimeFrom(ctx, this), workflow, promptParts, options);
     }));
   const runCmd = addGlobalOptions(program.command("runs").description("Inspect KXM runs"));
   runCmd.helpCommand("help", "Show runs help");
   addGlobalOptions(runCmd.command("status").description("Show the projected status of a run, including durable drive receipt state (open / receipt verified / unsettled / orphaned)"))
     .argument("<runId>", "Run id")
-    .action(async function runStatusAction(this: Command, runId: string) {
-      result.code = await cmdKxmRunStatus(runtimeFrom(ctx, this), runId);
+    .option("--lane <unit>", "Discover the project from this lane's worktree")
+    .action(async function runStatusAction(this: Command, runId: string, options: { lane?: string }) {
+      const runtime = applyLane(runtimeFrom(ctx, this), options.lane, "runs status");
+      result.code = typeof runtime === "number" ? runtime : await cmdKxmRunStatus(runtime, runId);
     });
   addGlobalOptions(runCmd.command("drive").description("Drive a run with live harness calls, or with the model-free simulation when --simulated is passed"))
     .argument("<runId>", "Run id")
     .option("--simulated", "Use the model-free simulation producer instead of a live model")
     .option("--wait", "Wait until a drive receipt is recorded; exits 0 only for a VERIFIED COMPLETED settlement")
     .option("--timeout-ms <n>", "Wait timeout in milliseconds (default 60000, max 600000)")
-    .action(async function runDriveAction(this: Command, runId: string, options: { simulated?: boolean; wait?: boolean; timeoutMs?: string }) {
-      result.code = await cmdKxmRunDrive(runtimeFrom(ctx, this), runId, options.simulated === true, {
+    .option("--lane <unit>", "Discover the project from this lane's worktree")
+    .action(async function runDriveAction(this: Command, runId: string, options: { simulated?: boolean; wait?: boolean; timeoutMs?: string; lane?: string }) {
+      const runtime = applyLane(runtimeFrom(ctx, this), options.lane, "runs drive");
+      if (typeof runtime === "number") {
+        result.code = runtime;
+        return;
+      }
+      result.code = await cmdKxmRunDrive(runtime, runId, options.simulated === true, {
         wait: options.wait === true,
         ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
       });
@@ -462,13 +537,17 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
   addGlobalOptions(runCmd.command("receipt").description("Print the newest drive receipt for a run"))
     .argument("<runId>", "Run id")
     .option("--all", "Print the capped receipt list for the run")
-    .action(async function runReceiptAction(this: Command, runId: string, options: { all?: boolean }) {
-      result.code = await cmdKxmRunReceipt(runtimeFrom(ctx, this), runId, { all: options.all === true });
+    .option("--lane <unit>", "Discover the project from this lane's worktree")
+    .action(async function runReceiptAction(this: Command, runId: string, options: { all?: boolean; lane?: string }) {
+      const runtime = applyLane(runtimeFrom(ctx, this), options.lane, "runs receipt");
+      result.code = typeof runtime === "number" ? runtime : await cmdKxmRunReceipt(runtime, runId, { all: options.all === true });
     });
   addGlobalOptions(runCmd.command("cancel").description("Durably request cancellation of a run"))
     .argument("<runId>", "Run id")
-    .action(async function runCancelAction(this: Command, runId: string) {
-      result.code = await cmdKxmRunCancel(runtimeFrom(ctx, this), runId);
+    .option("--lane <unit>", "Discover the project from this lane's worktree")
+    .action(async function runCancelAction(this: Command, runId: string, options: { lane?: string }) {
+      const runtime = applyLane(runtimeFrom(ctx, this), options.lane, "runs cancel");
+      result.code = typeof runtime === "number" ? runtime : await cmdKxmRunCancel(runtime, runId);
     });
   addGlobalOptions(runCmd.command("list").description("List recent runs for the current project"))
     .action(async function runListAction(this: Command) {

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.119";
+const VERSION = "0.7.121";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();

package/schemas/README.md

@@ -13,6 +13,7 @@ Runtime-local records, and JSON events/results for the planned KXM contract.
 | `workflow.schema.json` | `kxm.workflow.v1` |
 | `template-provenance.schema.json` | `kxm.template-provenance.v1` |
 | `local-repository-bindings.schema.json` | `kxm.local-repository-bindings.v1` |
+| `lanes.schema.json` | `kxm.lanes.v1` |
 | `init-operation.schema.json` | `kxm.init-operation.v1` |
 | `permission-diff.schema.json` | `kxm.permission-diff.v1` |
 | `run-event.schema.json` | `kxm.run-event.v1` |

package/schemas/lanes.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kxm.dev/lanes.schema.json",
+  "title": "KXM worktree lanes",
+  "type": "object",
+  "required": ["schema", "lanes"],
+  "additionalProperties": false,
+  "properties": {
+    "schema": {
+      "const": "kxm.lanes.v1"
+    },
+    "lanes": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 64,
+        "pattern": "^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$"
+      },
+      "patternProperties": {
+        "^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$": {
+          "$ref": "#/$defs/lane"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "$defs": {
+    "lane": {
+      "type": "object",
+      "required": ["path", "branch", "baseRef", "baseSha", "createdAt"],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "branch": {
+          "type": "string",
+          "minLength": 1
+        },
+        "baseRef": {
+          "type": "string",
+          "minLength": 1
+        },
+        "baseSha": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{40,64}$"
+        },
+        "createdAt": {
+          "type": "string",
+          "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]{1,9})?Z$"
+        },
+        "lastRunId": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    }
+  }
+}

package/scripts/pr-land.d.mts

@@ -0,0 +1,2 @@
+export function unionChangelogUnreleased(ours: string, theirs: string): string;
+export function unionLandedTracker(ours: string, theirs: string): string;