@kontextmind/kxm 0.7.104 → 0.7.105

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

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

package/plugins/kxm/dist/runtime-supervisor.js

@@ -16015,7 +16015,7 @@ function probeEntry(entry, runCommand, timeoutMs, platform, probe = {}) {
   return {
     id: entry.id,
     label: entry.label,
-    default: entry.default,
+    default: entry.id === (probe.defaultHarness ?? DEFAULT_HARNESS),
     mode: entry.mode,
     detected,
     authenticated,

package/plugins/kxm/dist/runtime.js

@@ -16017,7 +16017,7 @@ function probeEntry(entry, runCommand, timeoutMs, platform, probe = {}) {
   return {
     id: entry.id,
     label: entry.label,
-    default: entry.default,
+    default: entry.id === (probe.defaultHarness ?? DEFAULT_HARNESS),
     mode: entry.mode,
     detected,
     authenticated,
@@ -16038,7 +16038,7 @@ function probeHarnesses(options = {}) {
   const runCommand = options.runCommand ?? defaultRunner(options.env ?? process.env);
   const platform = options.platform ?? process.platform;
   return {
-    defaultHarness: DEFAULT_HARNESS,
+    defaultHarness: options.defaultHarness ?? DEFAULT_HARNESS,
     harnesses: BUILTIN_HARNESSES.map((entry) => probeEntry(entry, runCommand, timeoutMs, platform, options))
   };
 }
@@ -16449,7 +16449,7 @@ function formatHarnessInventory(inventory) {
     ].join(" ");
   });
   return [
-    `default harness: ${inventory.defaultHarness} (omit agent harness: to use headless Pi)`,
+    `default harness: ${inventory.defaultHarness} (used when an agent omits harness:)`,
     "enable/disable = Git YAML (.kxm/agents, .kxm/models) or the harness's own plugin CLI",
     "governed kxm skills are not auto-updated",
     header,

package/plugins/kxm/package.json

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

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

@@ -16,6 +16,7 @@ import { initializeKxmProject } from "../init.ts";
 import { diffKxmProjectAgainstRevision, formatKxmPermissionDiff } from "../permission.ts";
 import { readKxmLocalBindings, kxmUserStateRoot } from "../bindings.ts";
 import { loadKxmProject } from "../project-config.ts";
+import { kxmLiveRunPrerequisites, type KxmRunHandoff } from "../engine.ts";
 import {
   attachKxmSupervisor,
   ensureKxmSupervisor,
@@ -115,6 +116,13 @@ export async function cmdKxmInit(
       localStateRoot: kxmUserStateRoot({ env: runtime.env }),
       dryRun: runtime.dryRun,
     });
+    const starterGuidance = initialized.action === "created" || (initialized.action === "planned" && initialized.plan.mode === "create")
+      ? [
+          "defaultHarness: pi and the npm test gate are generic starter settings, not repository detection.",
+          "For Claude, set defaultHarness: claude in .kxm/project.yaml, update any explicit harness overrides in .kxm/agents/*.yaml, and configure compatible agent models.",
+          "For .NET or other non-npm repositories, set gates.test.argv in .kxm/gates.yaml to the repository's actual test runner before driving a workflow.",
+        ]
+      : [];
     const payload = {
       ok: initialized.action !== "planned" || runtime.dryRun,
       command: "init",
@@ -128,9 +136,10 @@ export async function cmdKxmInit(
       ...(initialized.resumePending === undefined ? {} : { resumePending: initialized.resumePending }),
       ...(initialized.transactionKind === undefined ? {} : { transactionKind: initialized.transactionKind }),
       plannedOnly: initialized.action === "planned",
+      ...(starterGuidance.length > 0 ? { guidance: starterGuidance } : {}),
     };
     const finishInit = (code: number, text: string): number => {
-      print(runtime.io, runtime.json, payload, text);
+      print(runtime.io, runtime.json, payload, [text, ...starterGuidance].join("\n"));
       return code;
     };
     if (initialized.action === "created") {
@@ -388,11 +397,16 @@ async function readSupervisor(runtime: Runtime, command: string): Promise<Awaite
   return attached ?? refuseDryRun(runtime.io, runtime.json, command, "the Runtime supervisor is not running and --dry-run will not start it");
 }
 
-export const RUN_ENGINE_PHASE = "pre-3a";
-
-/** The next step `kxm run` prints for the run it just created. */
-export function runEngineNotice(runId: string): string {
-  return `drive it model-free: kxm runs drive ${runId} --simulated --wait (or cancel: kxm runs cancel ${runId})`;
+/** Creation is not execution; local runs are driven and inspected in the runs namespace. */
+export function runEngineNotice(runId: string, defaultHarness: string, prerequisites: readonly KxmRunHandoff[]): string {
+  return [
+    `No steps executed. Project default harness: ${defaultHarness}; per-agent harness settings take precedence.`,
+    ...prerequisites.map((item) => `Live prerequisite${item.stepId ? ` (${item.stepId})` : ""}: ${item.detail}`),
+    "Live execution uses one-shot harness calls; no hub or Pi worker is required. Check installation/authentication with kxm harness list.",
+    `${prerequisites.length > 0 ? "Resolve the prerequisites above, then execute" : "Execute"}: kxm runs drive ${runId} --wait`,
+    `Inspect: kxm runs status ${runId} --json; receipt: kxm runs receipt ${runId} --json; cancel: kxm runs cancel ${runId}`,
+    "These are local Runtime runs, not webhook workflows; use kxm runs, not kxm workflow get.",
+  ].join("\n");
 }
 
 /** Where `kxm run <workflow>` would create its run, or the exit code of the
@@ -400,7 +414,8 @@ export function runEngineNotice(runId: string): string {
 export function resolveKxmRunTarget(
   runtime: Runtime,
   workflow: string | undefined,
-): { projectRoot: string; workflowId: string; configRevision: string } | number {
+  forTask = false,
+): { projectRoot: string; workflowId: string; configRevision: string; defaultHarness: string; prerequisites: KxmRunHandoff[] } | number {
   if (runtime.workspaceFlag !== undefined) {
     print(runtime.io, runtime.json, {
       ok: false,
@@ -409,7 +424,7 @@ export function resolveKxmRunTarget(
     }, "kxm run discovers the authoritative project from the current directory; --workspace is not supported");
     return 2;
   }
-  if (!workflow) {
+  if (!workflow && !forTask) {
     print(runtime.io, runtime.json, { ok: false, command: "run", error: "workflow_required" }, "usage: kxm run <workflow> [prompt]");
     return 2;
   }
@@ -419,16 +434,26 @@ export function resolveKxmRunTarget(
     return 1;
   }
   const bundle = loadKxmProject(projectRoot, {});
-  if (!bundle.workflows.has(workflow)) {
-    print(runtime.io, runtime.json, { ok: false, command: "run", error: "run_workflow_unknown", workflow }, `workflow ${workflow} does not exist in this project`);
+  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`);
+    return 1;
+  }
+  const defaultHarness = String(bundle.project.value.defaultHarness ?? "pi");
+  const prerequisites = kxmLiveRunPrerequisites(bundle, workflowId, projectRoot);
+  if (forTask && prerequisites.length > 0) {
+    print(runtime.io, runtime.json, {
+      ok: false, command: "task run", error: "run_execution_unavailable", workflowId, defaultHarness,
+      execution: { status: "not_started", mode: "live", prerequisites },
+    }, `task run refused; no run created or task changed (default harness: ${defaultHarness}).\n${prerequisites.map((item) => `${item.stepId ?? workflowId}: ${item.detail}`).join("\n")}`);
     return 1;
   }
-  return { projectRoot, workflowId: workflow, configRevision: bundle.configRevision };
+  return { projectRoot, workflowId, configRevision: bundle.configRevision, defaultHarness, prerequisites };
 }
 
-export async function cmdKxmRun(runtime: Runtime, workflow: string | undefined, promptParts: string[]): Promise<number> {
+export async function cmdKxmRun(runtime: Runtime, workflow: string | undefined, promptParts: string[], forTask = false): Promise<number> {
   try {
-    const target = resolveKxmRunTarget(runtime, workflow);
+    const target = resolveKxmRunTarget(runtime, workflow, forTask);
     if (typeof target === "number") return target;
     const { projectRoot } = target;
     if (runtime.dryRun) {
@@ -451,11 +476,23 @@ export async function cmdKxmRun(runtime: Runtime, workflow: string | undefined,
     print(runtime.io, runtime.json, {
       ok: true,
       command: "run",
-      phase: RUN_ENGINE_PHASE,
+      execution: {
+        status: "not_started",
+        mode: "live",
+        defaultHarness: target.defaultHarness,
+        authentication: "not_checked",
+        prerequisites: target.prerequisites,
+        nextSteps: {
+          harnesses: "kxm harness list",
+          drive: `kxm runs drive ${run.runId} --wait`,
+          status: `kxm runs status ${run.runId} --json`,
+          receipt: `kxm runs receipt ${run.runId} --json`,
+        },
+      },
       idempotent: acceptance.idempotent === true,
       run,
       supervisor: { runtimeId: supervisor.runtimeId, port: supervisor.port, started: supervisor.started },
-    }, `run ${run.status}: ${run.runId} (home ${run.homeRuntimeId.slice(0, 12)}…, config ${run.configRevision.slice(0, 19)}…)\n${runEngineNotice(run.runId)}`);
+    }, `run ${run.status}: ${run.runId} (home ${run.homeRuntimeId.slice(0, 12)}…, config ${run.configRevision.slice(0, 19)}…)\n${runEngineNotice(run.runId, target.defaultHarness, target.prerequisites)}`);
     return 0;
   } catch (error) {
     if (error instanceof KxmConfigError) {
@@ -782,9 +819,20 @@ export async function cmdTenantStatus(runtime: Runtime): Promise<number> {
 }
 
 export async function cmdHarnessList(runtime: Runtime): Promise<number> {
-  const inventory = await probeHarnessesAsync({ env: runtime.env });
-  print(runtime.io, runtime.json, { ok: true, command: "harness list", ...inventory }, formatHarnessInventory(inventory));
-  return 0;
+  try {
+    const projectRoot = discoverKxmProjectRoot(runtime.cwd);
+    const defaultHarness = projectRoot ? String(loadKxmProject(projectRoot).project.value.defaultHarness ?? "pi") : undefined;
+    const inventory = await probeHarnessesAsync({ env: runtime.env, defaultHarness });
+    print(runtime.io, runtime.json, { ok: true, command: "harness list", ...inventory }, formatHarnessInventory(inventory));
+    return 0;
+  } catch (error) {
+    if (error instanceof KxmConfigError) {
+      print(runtime.io, runtime.json, { ok: false, command: "harness list", error: "harness_list_failed", issues: error.issues }, `harness list failed: ${error.message}`);
+      return 1;
+    }
+    print(runtime.io, runtime.json, { ok: false, command: "harness list", error: "harness_list_io_failed" }, "harness list failed because a local operation did not complete");
+    return 1;
+  }
 }
 
 export async function selectInventoryModel(runtime: Runtime, requested?: string | undefined): Promise<string | undefined> {

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

@@ -2,10 +2,12 @@ import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { join, resolve } from "node:path";
+import { basename, extname, join, resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { verifyArtifactExists } from "../artifacts-exist.ts";
 import { parseWorkflowDefinitions } from "../workflow.ts";
+import { KxmConfigError, KxmSchemaRegistry, parseRestrictedYaml } from "../project-config.ts";
+import { compileKxmWorkflow } from "../engine-compile.ts";
 import { redactSecrets } from "../redact.ts";
 import {
   telemetryPath,
@@ -478,6 +480,22 @@ export async function cmdValidate(runtime: Runtime, fileFlag?: string | undefine
   }
   try {
     const raw = file ? readFileSync(file, "utf8") : inline!;
+    // Local workflow mappings use the runner's restricted YAML/schema/compiler.
+    // Webhook sources remain JSON arrays with their existing secret checks.
+    if (explicitFile && file && !raw.trimStart().startsWith("[")) {
+      const value = parseRestrictedYaml(raw, file);
+      const issues = new KxmSchemaRegistry().validate("workflow", value, file);
+      if (issues.length > 0) throw new KxmConfigError(issues);
+      const id = basename(file, extname(file));
+      compileKxmWorkflow({ id, value, logicalPath: file });
+      printWorker(
+        runtime,
+        worker,
+        { ok: true, command: "validate", source: "file", file, workflows: [{ id, schema: value.schema }], warnings: [] },
+        `validated local workflow ${id} (schema and transitions); kxm init validates project references`,
+      );
+      return 0;
+    }
     const warnings: string[] = [];
     const definitions = parseWorkflowDefinitions(raw, runtime.env, (message) => warnings.push(message));
     const secretEnvs = definitions.map((definition) => ({

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

@@ -9,7 +9,6 @@ import {
   listGoals,
   listTasks,
   getTask,
-  updateTaskStatus,
   syncTaskWithTracker,
   goalFilePath,
   taskFilePath,
@@ -27,40 +26,71 @@ import { readSessionTokenFromDisk } from "../commands.ts";
 import { print, printPlan, type Runtime } from "./types.ts";
 import { cmdKxmRun, resolveKxmRunTarget } from "./project.ts";
 
-export async function cmdSuggest(runtime: Runtime, promptParts: string[]): Promise<number> {
+export async function cmdSuggest(
+  runtime: Runtime,
+  promptParts: string[],
+  probeHarnesses = probeHarnessesAsync,
+): Promise<number> {
   try {
     const prompt = promptParts.join(" ").trim();
     if (!prompt) {
-      runtime.io.stderr("prompt must be non-empty\n");
+      print(runtime.io, runtime.json, { ok: false, command: "suggest", error: "prompt_required" }, "prompt must be non-empty");
       return 2;
     }
-    const inventory = await probeHarnessesAsync({ env: runtime.env });
-    const availableHarnesses = inventory.harnesses.map((h) => ({
-      harness: h.id,
-      auth: h.authenticated === true ? "authenticated" : "unauthenticated",
-    }));
-    const suggestion = suggestWorkflowAndRoles(prompt, { availableHarnesses });
-
+    // Native authentication probes may initialize state. A dry run must not invoke them.
+    const inventory = runtime.dryRun ? undefined : await probeHarnesses({ env: runtime.env });
+    const suggestion = suggestWorkflowAndRoles(prompt, { availableHarnesses: inventory?.harnesses });
+    if (suggestion.execution.supported && [".yaml", ".yml"].some((extension) =>
+      existsSync(join(runtime.cwd, ".kxm", "workflows", `${suggestion.workflowId}${extension}`)))) {
+      suggestion.roles = [];
+      suggestion.execution = {
+        supported: false,
+        error: "workflow_already_exists",
+        reason: `Workflow ${suggestion.workflowId} already exists; its agents and permissions may differ from the recommended template.`,
+        nextSteps: ["Review the existing definition and every agent's harness/model before running it, or install the recommended template under a fresh flat ID. No existing workflow is overwritten or recommended for execution."],
+      };
+    }
+    const execution = suggestion.execution;
     const text = [
       `Suggested Workflow: ${suggestion.workflowId} (${suggestion.area})`,
+      `Template: ${suggestion.template}`,
       `Confidence: ${(suggestion.confidence * 100).toFixed(0)}%`,
       `Reasons: ${suggestion.reasons.join("; ")}`,
       `Suggested Skills: ${suggestion.suggestedSkills.join(", ") || "none"}`,
-      `Roles:`,
-      `  Planner:     ${suggestion.roles.planner.harness} (${suggestion.roles.planner.model})`,
-      `  Writer:      ${suggestion.roles.writer.harness} (${suggestion.roles.writer.model})`,
-      `  Critics:     ${suggestion.roles.critics.map((c) => `${c.harness}:${c.model}`).join(", ")}`,
-      `  Verifier:    ${suggestion.roles.verifier.command}`,
-      ``,
-      `Execute with:`,
+      "",
+      "Install definition only (requires kxm init; does not execute):",
       `  ${suggestion.suggestedCommand}`,
+      "",
+      ...(execution.supported ? [
+        "Suggested agent routing (not applied):",
+        ...suggestion.roles.map((role) => `  ${role.agent}: ${role.harness} (${role.role}; use a configured compatible model)`),
+        "Prerequisites:",
+        ...execution.prerequisites.map((step) => `  ${step}`),
+        `Create a run only (${execution.shell}; does not execute steps):`,
+        `  ${execution.createCommand}`,
+        "Then drive the returned run ID with live calls and inspect its result:",
+        `  ${execution.driveCommand}`,
+        `  ${execution.statusCommand}`,
+        `  ${execution.receiptCommand}`,
+      ] : [
+        `Execution unavailable: ${execution.reason}`,
+        ...execution.nextSteps.map((step) => `  ${step}`),
+        ...(runtime.dryRun ? ["Harness authentication was not probed during --dry-run."] : []),
+      ]),
     ].join("\n");
 
-    print(runtime.io, runtime.json, { ok: true, command: "suggest", prompt, ...suggestion }, text);
-    return 0;
+    print(runtime.io, runtime.json, {
+      ok: execution.supported,
+      command: "suggest",
+      prompt,
+      ...suggestion,
+      ...(runtime.dryRun ? { dryRun: true } : {}),
+      ...(!execution.supported ? { error: execution.error } : {}),
+    }, text);
+    return execution.supported ? 0 : 1;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    runtime.io.stderr(`suggest failed: ${message}\n`);
+    print(runtime.io, runtime.json, { ok: false, command: "suggest", error: "suggest_failed", detail: message }, `suggest failed: ${message}`);
     return 1;
   }
 }
@@ -196,27 +226,21 @@ export async function cmdTaskRun(runtime: Runtime, taskId: string): Promise<numb
       runtime.io.stderr(`Task ${taskId} not found\n`);
       return 1;
     }
-    const workflow = task.assignedWorkflow ?? "default";
+    const workflow = task.assignedWorkflow;
     if (runtime.dryRun) {
-      const target = resolveKxmRunTarget(runtime, workflow);
+      const target = resolveKxmRunTarget(runtime, workflow, true);
       if (typeof target === "number") return target;
-      const started = updateTaskStatus(runtime.cwd, taskId, "in_progress", { dryRun: true });
       printPlan(
         runtime,
-        { command: "task run", taskId, ...target, status: started.status },
+        { command: "task run", taskId, ...target, status: task.status, execution: { status: "not_started", mode: "live" } },
         [
           { action: "request", target: "POST kxm-runtime /v1/runs (starts the Runtime supervisor if it is not running)" },
-          { action: "write", target: taskFilePath(runtime.cwd, taskId) },
         ],
-        `run workflow ${workflow} for task ${taskId}, then mark it ${started.status}`,
+        `create workflow ${target.workflowId} for task ${taskId}; task status stays ${task.status} until work actually starts`,
       );
       return 0;
     }
-    const exitCode = await cmdKxmRun(runtime, workflow, [task.objective]);
-    if (exitCode === 0) {
-      updateTaskStatus(runtime.cwd, taskId, "in_progress");
-    }
-    return exitCode;
+    return await cmdKxmRun(runtime, workflow, [task.objective], true);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     runtime.io.stderr(`task run failed: ${message}\n`);

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

@@ -11,7 +11,6 @@ import {
   addWorkflowDefinition,
   removeWorkflowDefinition,
   modifyWorkflowDefinition,
-  parseWorkflowFile,
   scaffoldWorkflowDefinition,
   WORKFLOW_TEMPLATES,
 } from "../workflow-manager.ts";
@@ -23,7 +22,7 @@ import {
   type WorkflowJournalEntry,
   type WorkflowRun,
 } from "../workflow.ts";
-import { discoverKxmProjectRoot, kxmWorkflowWriteIssues } from "../project-config.ts";
+import { discoverKxmProjectRoot, kxmWorkflowWriteIssues, parseRestrictedYaml } from "../project-config.ts";
 import { ensureKxmSupervisor, kxmRuntimeRequest } from "../runtime-supervisor.ts";
 import { projectRuntimeOwnsRun } from "../runtime-store.ts";
 import type { WorkerOutcome } from "../envelope.ts";
@@ -215,63 +214,63 @@ export async function cmdWorkflowAdd(
   },
 ): Promise<number> {
   const scope = options.scope ?? "local";
-  const refuse = (error: string, text: string): number => {
-    print(runtime.io, runtime.json, { ok: false, command: "workflow add", error }, `workflow add failed: ${text}`);
-    return 2;
+  const refuse = (error: string, message: string, code = 2): number => {
+    print(runtime.io, runtime.json, { ok: false, command: "workflow add", error, message }, `workflow add failed: ${message}`);
+    return code;
   };
-  let content: Record<string, unknown> | string | undefined;
-  if (options.template !== undefined) {
-    if (options.file !== undefined || options.pick !== undefined) {
-      return refuse("workflow_add_conflict", "--template cannot be combined with --file or --pick");
-    }
-    if (!workflowId) return refuse("workflow_id_required", "usage: kxm workflow add <workflowId> --template <name>");
-    const template = Object.hasOwn(WORKFLOW_TEMPLATES, options.template) ? WORKFLOW_TEMPLATES[options.template] : undefined;
-    if (!template) {
-      return refuse("workflow_template_unknown", `unknown template ${options.template}; choose ${Object.keys(WORKFLOW_TEMPLATES).join(", ")}`);
-    }
-    content = { ...template, ...(options.description ? { description: options.description } : {}) };
-  } else if (!workflowId || options.pick) {
-    const candidates: PickCandidate[] = Object.entries(WORKFLOW_TEMPLATES).map(([id, tmpl]) => ({
-      id,
-      description: String(tmpl.description ?? id),
-      label: "template",
-      payload: tmpl,
-    }));
-    if (scope === "local") {
-      const globalDefs = listWorkflowDefinitions({ scope: "global", userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
-      for (const gd of globalDefs) {
-        // Read the listed file itself: it may be `.yml`, which a lookup by `<id>.yaml` misses.
-        const definition = parseWorkflowFile(gd.filePath);
-        if (definition && !candidates.some((c) => c.id === gd.id)) {
-          candidates.push({ id: gd.id, description: gd.description, label: "global", payload: definition });
+  try {
+    let content: Record<string, unknown> | string | undefined;
+    if (options.template !== undefined) {
+      if (options.file !== undefined || options.pick !== undefined) {
+        return refuse("workflow_add_conflict", "--template cannot be combined with --file or --pick");
+      }
+      if (!workflowId) return refuse("workflow_id_required", "usage: kxm workflow add <workflowId> --template <name>");
+      const template = Object.hasOwn(WORKFLOW_TEMPLATES, options.template) ? WORKFLOW_TEMPLATES[options.template] : undefined;
+      if (!template) {
+        return refuse("workflow_template_unknown", `unknown template ${options.template}; choose ${Object.keys(WORKFLOW_TEMPLATES).join(", ")}`);
+      }
+      content = { ...template, ...(options.description !== undefined ? { description: options.description } : {}) };
+    } else if (!workflowId || options.pick) {
+      const candidates: PickCandidate[] = Object.entries(WORKFLOW_TEMPLATES).map(([id, tmpl]) => ({
+        id,
+        description: String(tmpl.description ?? id),
+        label: "template",
+        payload: tmpl,
+      }));
+      if (scope === "local") {
+        const globalDefs = listWorkflowDefinitions({ scope: "global", userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
+        for (const gd of globalDefs) {
+          // Read the listed path when selected: globals may use `.yml`, not only `.yaml`.
+          if (!candidates.some((c) => c.id === gd.id)) {
+            candidates.push({ id: gd.id, description: gd.description, label: "global", payload: gd.filePath });
+          }
         }
       }
-    }
-    const picked = await resolvePickItem(runtime.io, `Select a workflow template to add (${scope})`, candidates, options.pick, runtime.env);
-    if (!picked) {
-      if (!workflowId) {
-        runtime.io.stderr("workflow add failed: missing workflowId or pick selection\n");
-        return 1;
+      const picked = await resolvePickItem(runtime.io, `Select a workflow template to add (${scope})`, candidates, options.pick, runtime.env);
+      if (!picked) {
+        return refuse("workflow_id_required", "provide a workflowId or select an available workflow with --pick <id>", 1);
       }
-    } else {
-      workflowId = picked.id;
-      if (!options.file && picked.payload) {
-        content = {
-          ...picked.payload,
-          ...(options.description ? { description: options.description } : {}),
-        };
+      workflowId ??= picked.id;
+      if (options.file === undefined) {
+        const pickedContent = typeof picked.payload === "string"
+          ? readFileSync(picked.payload, "utf8")
+          : picked.payload;
+        content = options.description !== undefined
+          ? {
+            ...(typeof pickedContent === "string" ? parseRestrictedYaml(pickedContent, String(picked.payload)) : pickedContent),
+            description: options.description,
+          }
+          : pickedContent;
       }
     }
-  }
 
-  if (options.file) {
-    const filePath = resolve(runtime.cwd, options.file);
-    content = readFileSync(filePath, "utf8");
-  } else if (!content) {
-    content = scaffoldWorkflowDefinition(options.description || `Workflow ${workflowId}`);
-  }
+    if (options.file !== undefined) {
+      const filePath = resolve(runtime.cwd, options.file);
+      content = readFileSync(filePath, "utf8");
+    } else if (!content) {
+      content = scaffoldWorkflowDefinition(options.description || `Workflow ${workflowId}`);
+    }
 
-  try {
     const document = typeof content === "string" ? content : stringify(content);
     // A local workflow is read by the project loader, which refuses the whole
     // project over one bad file, so it is checked by that loader before it lands.
@@ -286,7 +285,7 @@ export async function cmdWorkflowAdd(
         print(
           runtime.io,
           runtime.json,
-          { ok: false, command: "workflow add", error: "workflow_invalid", issues },
+          { ok: false, command: "workflow add", error: "workflow_invalid", message: "with this workflow the project would not load, so nothing was written", issues },
           `workflow add failed: with this workflow the project would not load, so nothing was written\n${issues.map((entry) => `  ${entry.file}: ${entry.code}: ${entry.message}`).join("\n")}`,
         );
         return 2;
@@ -312,8 +311,7 @@ export async function cmdWorkflowAdd(
     );
     return 0;
   } catch (err: unknown) {
-    runtime.io.stderr(`workflow add failed: ${(err as Error).message}\n`);
-    return 1;
+    return refuse("workflow_add_failed", err instanceof Error ? err.message : String(err), 1);
   }
 }
 

package/plugins/kxm/src/cli.ts

@@ -432,7 +432,7 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
       result.code = await cmdRestore(runtimeFrom(ctx, this), manifest, options);
     });
 
-  addGlobalOptions(program.command("run").description("Create a KXM run (offline-first; kxm runs drive <runId> --simulated executes it model-free)")
+  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[]) {