@kontextmind/kxm 0.7.103 → 0.7.105

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

@@ -1,9 +1,10 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline";
-import { createBackup, planBackup, planRestore, restoreBackup } from "../database.ts";
+import { applyRestorePlan, createBackup, databaseError, planBackup, planRestore, type RestorePlan } from "../database.ts";
+import { readLiveHubClaim } from "../hub-autostart.ts";
 import { refreshModelInventory } from "../model-inventory.ts";
 import { listInventoryModels, listRoleBindings, loadRoutePolicy, setRouteState, updateRouteState } from "../routes.ts";
 import {
@@ -15,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,
@@ -114,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",
@@ -127,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") {
@@ -181,23 +191,30 @@ export async function cmdKxmInit(
   }
 }
 
-export async function cmdBackup(runtime: Runtime, options: { out?: string | undefined }): Promise<number> {
+/** The checkout backup and restore act for, found as the Runtime finds it, so the
+ * project's event store key is the one the Runtime derives. */
+function backupProjectRoot(runtime: Runtime): string {
+  return discoverKxmProjectRoot(runtime.cwd) ?? runtime.cwd;
+}
+
+export async function cmdBackup(runtime: Runtime, options: { out?: string | undefined; allProjects?: boolean | undefined }): Promise<number> {
   try {
     const backupOptions = {
-      projectRoot: runtime.cwd,
+      projectRoot: backupProjectRoot(runtime),
       env: runtime.env,
+      ...(options.allProjects === true ? { allProjects: true } : {}),
       ...(options.out ? { outDir: resolve(runtime.cwd, options.out) } : {}),
     };
     if (runtime.dryRun) {
       const plan = planBackup(backupOptions);
       printPlan(
         runtime,
-        { command: "backup", outDir: plan.outDir, stores: plan.stores, files: plan.files },
+        { command: "backup", scope: plan.scope, outDir: plan.outDir, stores: plan.stores, files: plan.files },
         [
           ...[...plan.stores, ...plan.files].map((entry) => ({ action: "write" as const, target: join(plan.outDir, entry.backupFile) })),
           { action: "write", target: join(plan.outDir, "manifest.json") },
         ],
-        `back up ${plan.stores.length} store(s) and ${plan.files.length} file(s) to ${plan.outDir} (sources are not opened, so their WAL is not checkpointed)`,
+        `back up ${plan.stores.length} store(s) and ${plan.files.length} file(s) (${plan.scope} scope) to ${plan.outDir} (sources are not opened, so their WAL is not checkpointed)`,
       );
       return 0;
     }
@@ -212,7 +229,7 @@ export async function cmdBackup(runtime: Runtime, options: { out?: string | unde
     };
     const summary = [
       complete
-        ? `Created SQLite backup with ${manifest.stores.length} store(s):`
+        ? `Created SQLite backup with ${manifest.stores.length} store(s) (${manifest.scope ?? "project"} scope):`
         : `Backup is incomplete (${manifest.omitted?.length ?? 0} omitted); not ok:`,
       ...manifest.stores.map((s) => `  - ${s.storeId}: ${s.sourcePath} -> ${s.backupFile} (schema v${s.schemaVersion}, ${s.bytes} bytes, sha256 ${s.sha256.slice(0, 12)}...)`),
       ...(manifest.omitted ?? []).map((id) => `  - omitted ${id}`),
@@ -230,16 +247,63 @@ export async function cmdBackup(runtime: Runtime, options: { out?: string | unde
   }
 }
 
-export async function cmdRestore(runtime: Runtime, manifestArg: string): Promise<number> {
+/**
+ * Refuse while anything holds the stores a restore would overwrite. Replacing a
+ * SQLite file under an open connection loses the writer's next commit or corrupts
+ * the store, and the supervisor holds the registry and every project's event store
+ * open. Reads only: the registry is opened read-only and the hub claim is a file,
+ * so the check is the same under --dry-run.
+ */
+function assertRestoreTargetsStopped(runtime: Runtime, plan: RestorePlan): void {
+  const paths = kxmRuntimePaths({ env: runtime.env });
+  let supervisor: ReturnType<typeof kxmSupervisorStatus>;
   try {
+    supervisor = kxmSupervisorStatus(paths, { readOnly: true });
+  } catch (error) {
+    // Fail closed, but name the way out: a registry too broken to read is also one a
+    // restore may be meant to replace.
+    throw databaseError(
+      "restore_runtime_unverified",
+      paths.registryDb,
+      `cannot read the Runtime registry to check whether the supervisor is running (${error instanceof Error ? error.message : String(error)}); stop the Runtime, move the registry aside, and restore again`,
+    );
+  }
+  if (supervisor.running) {
+    throw databaseError(
+      "restore_runtime_running",
+      paths.registryDb,
+      `the Runtime supervisor is running (pid ${String(supervisor.pid)}); stop it with \`kxm runtime stop\` and keep it stopped until the restore finishes`,
+    );
+  }
+  for (const store of plan.stores) {
+    if (store.storeId !== "hub-store") continue;
+    const claim = readLiveHubClaim(dirname(store.targetPath));
+    if (claim) {
+      throw databaseError(
+        "restore_hub_running",
+        store.targetPath,
+        `a hub (pid ${String(claim.pid)}) is running on ${store.targetPath}; stop it with \`kxm hub stop\` before restoring`,
+      );
+    }
+  }
+}
+
+export async function cmdRestore(runtime: Runtime, manifestArg: string, options: { allProjects?: boolean | undefined } = {}): Promise<number> {
+  try {
+    const plan = planRestore(resolve(runtime.cwd, manifestArg), {
+      projectRoot: backupProjectRoot(runtime),
+      env: runtime.env,
+      ...(options.allProjects === true ? { allProjects: true } : {}),
+    });
+    assertRestoreTargetsStopped(runtime, plan);
     if (runtime.dryRun) {
-      const plan = planRestore(resolve(runtime.cwd, manifestArg), { projectRoot: runtime.cwd });
       printPlan(
         runtime,
         {
           command: "restore",
           backupId: plan.backupId,
           manifestPath: plan.manifestPath,
+          ...(plan.scope !== undefined ? { scope: plan.scope } : {}),
           stores: plan.stores.map(({ storeId, targetPath, schemaVersion }) => ({ storeId, targetPath, schemaVersion })),
           files: plan.files.map(({ id, targetPath }) => ({ id, targetPath })),
         },
@@ -256,14 +320,13 @@ export async function cmdRestore(runtime: Runtime, manifestArg: string): Promise
       );
       return 0;
     }
-    const result = restoreBackup(resolve(runtime.cwd, manifestArg), {
-      projectRoot: runtime.cwd,
-    });
+    const result = applyRestorePlan(plan);
     const payload = {
       ok: true,
       command: "restore",
       backupId: result.backupId,
       manifestPath: result.manifestPath,
+      ...(plan.scope !== undefined ? { scope: plan.scope } : {}),
       restoredStores: result.restoredStores,
     };
     const summary = [
@@ -334,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
@@ -346,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,
@@ -355,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;
   }
@@ -365,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) {
@@ -397,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) {
@@ -728,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

@@ -419,18 +419,20 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
       });
     });
 
-  addGlobalOptions(program.command("backup").description("Create a verified SQLite backup of the project hub store and the Runtime stores under the user state root, with a hashed manifest"))
+  addGlobalOptions(program.command("backup").description("Create a verified SQLite backup of this project's hub store and Runtime event store, with a hashed manifest"))
     .option("--out <dir>", "Directory to write backup and manifest")
-    .action(async function backupAction(this: Command, options: { out?: string }) {
+    .option("--all-projects", "Also back up the shared Runtime registry and every project's event store on this machine")
+    .action(async function backupAction(this: Command, options: { out?: string; allProjects?: boolean }) {
       result.code = await cmdBackup(runtimeFrom(ctx, this), options);
     });
 
-  addGlobalOptions(program.command("restore <manifest>").description("Restore SQLite stores from a verified backup manifest"))
-    .action(async function restoreAction(this: Command, manifest: string) {
-      result.code = await cmdRestore(runtimeFrom(ctx, this), manifest);
+  addGlobalOptions(program.command("restore <manifest>").description("Restore this project's SQLite stores from a verified backup manifest; refuses while the Runtime or hub is running"))
+    .option("--all-projects", "Also restore the shared Runtime registry and other projects' event stores the backup holds")
+    .action(async function restoreAction(this: Command, manifest: string, options: { allProjects?: boolean }) {
+      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[]) {