@kontextmind/kxm 0.7.86 → 0.7.88

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

@@ -3,7 +3,7 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:f
 import { homedir, tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { createInterface } from "node:readline";
-import { createBackup, restoreBackup } from "../database.ts";
+import { createBackup, planBackup, planRestore, restoreBackup } from "../database.ts";
 import { refreshModelInventory } from "../model-inventory.ts";
 import { listInventoryModels, listRoleBindings, loadRoutePolicy, setRouteState, updateRouteState } from "../routes.ts";
 import {
@@ -43,7 +43,7 @@ import {
 } from "../kxm-update.ts";
 import { loadKxmUpdateConfig } from "../kxm-update-config.ts";
 import type { InstallKindReport, InstallProbe } from "../kxm-install-kind.ts";
-import { print, type CliIo, type CliSpawnResult, type Runtime } from "./types.ts";
+import { print, printPlan, refuseDryRun, type CliIo, type CliSpawnResult, type Runtime } from "./types.ts";
 
 export const kxmDriveCliSeams: {
   ensureSupervisor?: typeof ensureKxmSupervisor;
@@ -181,10 +181,24 @@ export async function cmdKxmInit(
 
 export async function cmdBackup(runtime: Runtime, options: { out?: string | undefined }): Promise<number> {
   try {
-    const { manifest, outDir } = createBackup({
+    const backupOptions = {
       projectRoot: runtime.cwd,
       ...(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 },
+        [
+          ...plan.stores.map((store) => ({ action: "write" as const, target: join(plan.outDir, store.backupFile) })),
+          { action: "write", target: join(plan.outDir, "manifest.json") },
+        ],
+        `back up ${plan.stores.length} store(s) to ${plan.outDir} (sources are not opened, so their WAL is not checkpointed)`,
+      );
+      return 0;
+    }
+    const { manifest, outDir } = createBackup(backupOptions);
     const payload = {
       ok: true,
       command: "backup",
@@ -211,6 +225,26 @@ export async function cmdBackup(runtime: Runtime, options: { out?: string | unde
 
 export async function cmdRestore(runtime: Runtime, manifestArg: string): Promise<number> {
   try {
+    if (runtime.dryRun) {
+      const plan = planRestore(resolve(runtime.cwd, manifestArg), { projectRoot: runtime.cwd });
+      printPlan(
+        runtime,
+        {
+          command: "restore",
+          backupId: plan.backupId,
+          manifestPath: plan.manifestPath,
+          stores: plan.stores.map(({ storeId, targetPath, schemaVersion }) => ({ storeId, targetPath, schemaVersion })),
+        },
+        plan.stores.flatMap((store) => [
+          { action: "write" as const, target: store.targetPath },
+          ...[`${store.targetPath}-wal`, `${store.targetPath}-shm`]
+            .filter((file) => existsSync(file))
+            .map((file) => ({ action: "delete" as const, target: file })),
+        ]),
+        `restore ${plan.stores.length} store(s) from ${plan.manifestPath}; digests verified against the manifest`,
+      );
+      return 0;
+    }
     const result = restoreBackup(resolve(runtime.cwd, manifestArg), {
       projectRoot: runtime.cwd,
     });
@@ -281,10 +315,23 @@ export async function cmdKxmTrust(runtime: Runtime, check: boolean, options: { b
   }
 }
 
+/** The supervisor a run read talks to. Normally it is started on demand; under
+ * `--dry-run` a read may only attach, because starting the Runtime is a change. */
+async function readSupervisor(runtime: Runtime, command: string): Promise<Awaited<ReturnType<typeof ensureKxmSupervisor>> | number> {
+  if (!runtime.dryRun) return await (kxmDriveCliSeams.ensureSupervisor ?? ensureKxmSupervisor)({ env: runtime.env });
+  const attached = await attachKxmSupervisor({ env: runtime.env });
+  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";
 export const RUN_ENGINE_NOTICE = "runs remain created until the run engine lands; no steps execute yet";
 
-export async function cmdKxmRun(runtime: Runtime, workflow: string | undefined, promptParts: string[]): Promise<number> {
+/** Where `kxm run <workflow>` would create its run, or the exit code of the
+ * refusal it already printed. Reads only; shared with `task run --dry-run`. */
+export function resolveKxmRunTarget(
+  runtime: Runtime,
+  workflow: string | undefined,
+): { projectRoot: string; workflowId: string; configRevision: string } | number {
   if (runtime.workspaceFlag !== undefined) {
     print(runtime.io, runtime.json, {
       ok: false,
@@ -297,33 +344,38 @@ export async function cmdKxmRun(runtime: Runtime, workflow: string | undefined,
     print(runtime.io, runtime.json, { ok: false, command: "run", error: "workflow_required" }, "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)");
+    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`);
+    return 1;
+  }
+  return { projectRoot, workflowId: workflow, configRevision: bundle.configRevision };
+}
+
+export async function cmdKxmRun(runtime: Runtime, workflow: string | undefined, promptParts: string[]): Promise<number> {
   try {
-    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)");
-      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`);
-      return 1;
-    }
+    const target = resolveKxmRunTarget(runtime, workflow);
+    if (typeof target === "number") return target;
+    const { projectRoot } = target;
     if (runtime.dryRun) {
       print(runtime.io, runtime.json, {
         ok: true,
         command: "run",
         dryRun: true,
-        projectRoot,
-        workflowId: workflow,
-        configRevision: bundle.configRevision,
-      }, `run plan: workflow ${workflow} at ${bundle.configRevision.slice(0, 19)}… (no run created)`);
+        ...target,
+      }, `run plan: workflow ${target.workflowId} at ${target.configRevision.slice(0, 19)}… (no run created)`);
       return 0;
     }
     const supervisor = await ensureKxmSupervisor({ env: runtime.env });
     const prompt = promptParts.join(" ").trim();
     const acceptance = await kxmRuntimeRequest(supervisor, "POST", "/v1/runs", {
       projectRoot,
-      workflowId: workflow,
+      workflowId: target.workflowId,
       prompt,
     });
     const run = acceptance.run as { runId: string; homeRuntimeId: string; status: string; configRevision: string };
@@ -408,7 +460,8 @@ export async function cmdKxmRunStatus(runtime: Runtime, runId: string): Promise<
       print(runtime.io, runtime.json, { ok: false, command: "runs status", error: "project_required" }, "kxm runs status requires a KXM project (run kxm init first)");
       return 1;
     }
-    const supervisor = await (kxmDriveCliSeams.ensureSupervisor ?? ensureKxmSupervisor)({ env: runtime.env });
+    const supervisor = await readSupervisor(runtime, "runs status");
+    if (typeof supervisor === "number") return supervisor;
     const result = await (kxmDriveCliSeams.runtimeRequest ?? kxmRuntimeRequest)(supervisor, "GET", `/v1/runs/${encodeURIComponent(runId)}?projectRoot=${encodeURIComponent(projectRoot)}`);
     const run = result.run as { runId: string; status: string; workflowId: string; configRevision: string; updatedAt: string };
     const drive = result.drive as KxmStatusDrive | undefined;
@@ -570,7 +623,8 @@ export async function cmdKxmRunList(runtime: Runtime): Promise<number> {
     }
     const bundle = loadKxmProject(projectRoot, {});
     const projectId = String(bundle.project.value.id);
-    const supervisor = await ensureKxmSupervisor({ env: runtime.env });
+    const supervisor = await readSupervisor(runtime, "runs list");
+    if (typeof supervisor === "number") return supervisor;
     const result = await kxmRuntimeRequest(supervisor, "GET", `/v1/projects/${encodeURIComponent(projectId)}/runs?projectRoot=${encodeURIComponent(projectRoot)}`);
     const runs = (result.runs ?? []) as Array<{ runId: string; status: string; workflowId: string; createdAt: string; projectionError?: string }>;
     print(
@@ -851,7 +905,8 @@ export async function cmdKxmRunReceipt(runtime: Runtime, runId: string, options:
       print(runtime.io, runtime.json, { ok: false, command: "runs receipt", error: "project_required" }, "kxm runs receipt requires a KXM project (run kxm init first)");
       return 1;
     }
-    const supervisor = await (kxmDriveCliSeams.ensureSupervisor ?? ensureKxmSupervisor)({ env: runtime.env });
+    const supervisor = await readSupervisor(runtime, "runs receipt");
+    if (typeof supervisor === "number") return supervisor;
     const result = await (kxmDriveCliSeams.runtimeRequest ?? kxmRuntimeRequest)(
       supervisor,
       "GET",

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

@@ -3,7 +3,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
-import { DatabaseSync } from "../sqlite.ts";
+import { DatabaseSync, openReadOnlyDatabase } from "../sqlite.ts";
 import {
   DEFAULT_ROLES,
   DEFAULT_ROLE_SEATS,
@@ -20,7 +20,7 @@ import {
 import { discoverKxmProjectRoot } from "../project-config.ts";
 import { ensureKxmSupervisor, kxmRuntimeRequest } from "../runtime-supervisor.ts";
 import { resumeWorkflowFromRuling, type WorkflowRun } from "../workflow.ts";
-import { print, type CliIo, type Runtime } from "./types.ts";
+import { print, printPlan, type CliIo, type Runtime } from "./types.ts";
 
 export interface PickCandidate {
   id: string;
@@ -192,7 +192,12 @@ export async function cmdRoleAdd(
             repoRoot: runtime.cwd,
             userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
             overwrite: options.overwrite,
+            dryRun: runtime.dryRun,
           });
+          if (runtime.dryRun) {
+            printPlan(runtime, { command: "role add", roleId, ...res }, [{ action: "write", target: res.filePath }], `add role '${roleId}' to ${res.scope}`);
+            return 0;
+          }
           print(
             runtime.io,
             runtime.json,
@@ -232,7 +237,12 @@ export async function cmdRoleAdd(
       repoRoot: runtime.cwd,
       userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
       overwrite: options.overwrite,
+      dryRun: runtime.dryRun,
     });
+    if (runtime.dryRun) {
+      printPlan(runtime, { command: "role add", roleId, ...res }, [{ action: "write", target: res.filePath }], `add role '${roleId}' to ${res.scope}`);
+      return 0;
+    }
     print(
       runtime.io,
       runtime.json,
@@ -283,7 +293,12 @@ export async function cmdRoleRemove(
       scope,
       repoRoot: runtime.cwd,
       userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
+      dryRun: runtime.dryRun,
     });
+    if (runtime.dryRun) {
+      printPlan(runtime, { command: "role remove", roleId, ...res }, [{ action: "delete", target: res.filePath }], `remove role '${roleId}' from ${res.scope}`);
+      return 0;
+    }
     print(
       runtime.io,
       runtime.json,
@@ -377,7 +392,12 @@ export async function cmdRoleModify(
       scope: options.scope,
       repoRoot: runtime.cwd,
       userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
+      dryRun: runtime.dryRun,
     });
+    if (runtime.dryRun) {
+      printPlan(runtime, { command: "role modify", roleId, ...res }, [{ action: "write", target: res.filePath }], `modify role '${roleId}' in ${res.scope}`);
+      return 0;
+    }
     print(
       runtime.io,
       runtime.json,
@@ -482,7 +502,17 @@ export async function cmdRoleSetHost(
       scope: options.scope ?? "local",
       repoRoot: runtime.cwd,
       userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
+      dryRun: runtime.dryRun,
     });
+    if (runtime.dryRun) {
+      printPlan(
+        runtime,
+        { command: "role set-host", seatId, host, binding: result.binding, filePath: result.filePath, scope: result.scope },
+        [{ action: "write", target: result.filePath }],
+        `bind seat '${seatId}' to host '${host}'`,
+      );
+      return 0;
+    }
 
     print(
       runtime.io,
@@ -521,7 +551,12 @@ export async function cmdRoleResume(
   const projectRoot = discoverKxmProjectRoot(runtime.cwd);
   if (projectRoot && /^run_[a-f0-9]{32}$/i.test(runId)) {
     if (runtime.dryRun) {
-      print(runtime.io, runtime.json, { ok: true, command: "role resume", runId, ruling: effectiveRuling }, `would resume KXM run ${runId}`);
+      printPlan(
+        runtime,
+        { command: "role resume", runId, ruling: effectiveRuling },
+        [{ action: "request", target: `POST kxm-runtime /v1/runs/${runId}/signal (audit_escalation unblock)` }],
+        `resume KXM run ${runId}`,
+      );
       return 0;
     }
     try {
@@ -555,7 +590,7 @@ export async function cmdRoleResume(
   const dbPath = join(runtime.cwd, ".kxm", "state", "kxm.db");
   if (existsSync(dbPath)) {
     try {
-      const database = new DatabaseSync(dbPath);
+      const database = runtime.dryRun ? openReadOnlyDatabase(dbPath) : new DatabaseSync(dbPath);
       try {
         const row = database.prepare("SELECT record FROM workflow_runs WHERE id = ?").get(runId) as { record: string } | undefined;
         if (!row) {
@@ -565,6 +600,15 @@ export async function cmdRoleResume(
         const run = JSON.parse(row.record) as WorkflowRun;
         const now = new Date().toISOString();
         const resumeResult = resumeWorkflowFromRuling(run, effectiveRuling, now);
+        if (runtime.dryRun) {
+          printPlan(
+            runtime,
+            { command: "role resume", runId, stageId: resumeResult.stageId, ruling: effectiveRuling, status: resumeResult.run.status },
+            [{ action: "write", target: `${dbPath} (workflow_runs ${runId}, one workflow_journal decision)` }],
+            `resume workflow run ${runId} (stage: ${resumeResult.stageId})`,
+          );
+          return 0;
+        }
 
         database.prepare("UPDATE workflow_runs SET record = ? WHERE id = ?").run(
           JSON.stringify(resumeResult.run),

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

@@ -88,6 +88,7 @@ import {
 import { kxmUserStateRoot } from "../bindings.ts";
 import {
   print,
+  printPlan,
   printWorker,
   gateOf,
   type CliIo,
@@ -224,6 +225,10 @@ export async function cmdSshRun(
   options: { sudo?: boolean | undefined },
 ): Promise<number> {
   const command = commandParts.join(" ");
+  if (runtime.dryRun) {
+    printPlan(runtime, { command: "ssh run", host, remoteCommand: command, sudo: options.sudo === true }, [{ action: "ssh", target: `${host}: ${options.sudo ? "sudo " : ""}${command}` }], `run a command on ${host}`);
+    return 0;
+  }
   const receipt = executeSshRun({
     action: "command",
     host,
@@ -247,6 +252,10 @@ export async function cmdSshFile(
   options: { content?: string | undefined; read?: boolean | undefined; append?: boolean | undefined; sudo?: boolean | undefined },
 ): Promise<number> {
   const op = options.read ? "read" : (options.append ? "append" : "write");
+  if (runtime.dryRun) {
+    printPlan(runtime, { command: "ssh file", host, path: filePath, op, sudo: options.sudo === true }, [{ action: "ssh", target: `${host}: ${op} ${filePath}` }], `${op} ${filePath} on ${host}`);
+    return 0;
+  }
   const receipt = executeSshRun({
     action: "file",
     host,
@@ -269,6 +278,10 @@ export async function cmdSshFile(
 }
 
 export async function cmdSshClose(runtime: Runtime, host: string): Promise<number> {
+  if (runtime.dryRun) {
+    printPlan(runtime, { command: "ssh close", host }, [{ action: "ssh", target: `${host}: close the ControlMaster socket` }], `close the ControlMaster socket for ${host}`);
+    return 0;
+  }
   const closed = closeControlSocket(host);
   if (runtime.json) {
     print(runtime.io, runtime.json, { ok: true, closed, command: "ssh close", host }, "");
@@ -568,7 +581,11 @@ export async function cmdConfigSet(
     } catch {
       // keep string
     }
-    setKxmConfigValue(runtime.cwd, key, parsedVal, { scope });
+    const { file } = setKxmConfigValue(runtime.cwd, key, parsedVal, { scope, dryRun: runtime.dryRun });
+    if (runtime.dryRun) {
+      printPlan(runtime, { command: "config set", key, value: parsedVal, scope }, [{ action: "write", target: file }], `set ${key} = ${value} in ${scope} config`);
+      return 0;
+    }
     print(
       runtime.io,
       runtime.json,

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

@@ -11,6 +11,8 @@ import {
   getTask,
   updateTaskStatus,
   syncTaskWithTracker,
+  goalFilePath,
+  taskFilePath,
   type TaskStatus,
   type TrackerType,
 } from "../task-manager.ts";
@@ -22,8 +24,8 @@ import {
   generateStudioLayout,
 } from "../studio-layout.ts";
 import { readSessionTokenFromDisk } from "../commands.ts";
-import { print, type Runtime } from "./types.ts";
-import { cmdKxmRun } from "./project.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> {
   try {
@@ -74,7 +76,11 @@ export async function cmdGoalCreate(
       area: options.area,
       successMetrics: options.metric,
       targetDate: options.targetDate,
-    });
+    }, { dryRun: runtime.dryRun });
+    if (runtime.dryRun) {
+      printPlan(runtime, { command: "goal create", goal }, [{ action: "write", target: goalFilePath(runtime.cwd, goal.id) }], `create goal ${goal.title} (the id is assigned when it is created)`);
+      return 0;
+    }
     print(
       runtime.io,
       runtime.json,
@@ -118,7 +124,11 @@ export async function cmdTaskCreate(
       trackerSync: options.tracker && options.issue
         ? { tracker: options.tracker as TrackerType, issueKey: options.issue }
         : undefined,
-    });
+    }, { dryRun: runtime.dryRun });
+    if (runtime.dryRun) {
+      printPlan(runtime, { command: "task create", task }, [{ action: "write", target: taskFilePath(runtime.cwd, task.id) }], `create task ${task.title} [${task.status}] (the id is assigned when it is created)`);
+      return 0;
+    }
     print(
       runtime.io,
       runtime.json,
@@ -187,6 +197,21 @@ export async function cmdTaskRun(runtime: Runtime, taskId: string): Promise<numb
       return 1;
     }
     const workflow = task.assignedWorkflow ?? "default";
+    if (runtime.dryRun) {
+      const target = resolveKxmRunTarget(runtime, workflow);
+      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 },
+        [
+          { 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}`,
+      );
+      return 0;
+    }
     const exitCode = await cmdKxmRun(runtime, workflow, [task.objective]);
     if (exitCode === 0) {
       updateTaskStatus(runtime.cwd, taskId, "in_progress");
@@ -201,7 +226,11 @@ export async function cmdTaskRun(runtime: Runtime, taskId: string): Promise<numb
 
 export async function cmdTaskSync(runtime: Runtime, taskId: string): Promise<number> {
   try {
-    const synced = syncTaskWithTracker(runtime.cwd, taskId);
+    const synced = syncTaskWithTracker(runtime.cwd, taskId, { dryRun: runtime.dryRun });
+    if (runtime.dryRun) {
+      printPlan(runtime, { command: "task sync", task: synced }, [{ action: "write", target: taskFilePath(runtime.cwd, taskId) }], `mark task ${taskId} synced with ${synced.trackerSync?.tracker} #${synced.trackerSync?.issueKey}`);
+      return 0;
+    }
     print(
       runtime.io,
       runtime.json,

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

@@ -101,6 +101,36 @@ export function print(io: CliIo, jsonMode: boolean, payload: object, text: strin
   else io.stdout(line);
 }
 
+/** One change a command would have made had `--dry-run` not been given. */
+export interface PlannedChange {
+  action: "write" | "delete" | "move" | "request" | "ssh";
+  target: string;
+}
+
+/** The `--dry-run` answer of a mutating command: the envelope the real run
+ * prints, marked `dryRun: true`, plus every write, request, or remote step it
+ * would have taken. Nothing is written by the caller before or after this. */
+export function printPlan(
+  runtime: Runtime,
+  payload: Record<string, unknown> & { command: string },
+  planned: readonly PlannedChange[],
+  text: string,
+): void {
+  print(runtime.io, runtime.json, { ok: true, ...payload, dryRun: true, planned }, [
+    `dry run: ${text}`,
+    ...(planned.length === 0 ? ["  no changes"] : planned.map((change) => `  would ${change.action} ${change.target}`)),
+  ].join("\n"));
+}
+
+export const DRY_RUN_UNSUPPORTED = "dry_run_unsupported";
+
+/** For a command that cannot say what it would do without doing some of it:
+ * refuse under `--dry-run` instead of executing. */
+export function refuseDryRun(io: CliIo, jsonMode: boolean, command: string, reason: string): number {
+  print(io, jsonMode, { ok: false, command, dryRun: true, error: DRY_RUN_UNSUPPORTED, detail: reason }, `kxm ${command} --dry-run refused: ${reason}`);
+  return 2;
+}
+
 export function printWorker(
   runtime: Runtime,
   worker: Worker,

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

@@ -1,7 +1,7 @@
 import { createHmac, randomUUID } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
-import { DatabaseSync } from "../sqlite.ts";
+import { openReadOnlyDatabase } from "../sqlite.ts";
 import { buildRetrospective, writeRetrospective } from "../retrospective.ts";
 import { redactSecrets } from "../redact.ts";
 import { postWorkflowSignal, watchGithubChecks } from "../github-watch.ts";
@@ -24,6 +24,7 @@ import { ensureKxmSupervisor, kxmRuntimeRequest } from "../runtime-supervisor.ts
 import type { WorkerOutcome } from "../envelope.ts";
 import {
   print,
+  printPlan,
   printWorker,
   gateOf,
   parseEvidencePairs,
@@ -37,7 +38,7 @@ const CLI_NAME = "kxm";
 
 export function localWorkflowSnapshot(dataPath: string, runId?: string): { runs: WorkflowRun[]; journal: WorkflowJournalEntry[] } {
   if (!existsSync(dataPath)) throw new Error("state_database_not_found");
-  const database = new DatabaseSync(dataPath, { readOnly: true });
+  const database = openReadOnlyDatabase(dataPath);
   try {
     const rows = runId
       ? database.prepare("SELECT record FROM workflow_runs WHERE id = ?").all(runId)
@@ -265,7 +266,12 @@ export async function cmdWorkflowAdd(
       repoRoot: runtime.cwd,
       userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
       overwrite: options.overwrite,
+      dryRun: runtime.dryRun,
     });
+    if (runtime.dryRun) {
+      printPlan(runtime, { command: "workflow add", workflowId, ...res }, [{ action: "write", target: res.filePath }], `add workflow '${workflowId}' to ${res.scope}`);
+      return 0;
+    }
     print(
       runtime.io,
       runtime.json,
@@ -316,7 +322,12 @@ export async function cmdWorkflowRemove(
       scope,
       repoRoot: runtime.cwd,
       userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
+      dryRun: runtime.dryRun,
     });
+    if (runtime.dryRun) {
+      printPlan(runtime, { command: "workflow remove", workflowId, ...res }, [{ action: "delete", target: res.filePath }], `remove workflow '${workflowId}' from ${res.scope}`);
+      return 0;
+    }
     print(
       runtime.io,
       runtime.json,
@@ -373,8 +384,13 @@ export async function cmdWorkflowModify(
         scope: options.scope,
         repoRoot: runtime.cwd,
         userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
+        dryRun: runtime.dryRun,
       },
     );
+    if (runtime.dryRun) {
+      printPlan(runtime, { command: "workflow modify", workflowId, ...res }, [{ action: "write", target: res.filePath }], `modify workflow '${workflowId}' in ${res.scope}`);
+      return 0;
+    }
     print(
       runtime.io,
       runtime.json,
@@ -520,7 +536,7 @@ export async function cmdSignal(runtime: Runtime, runId: string, signalKey: stri
   const projectRoot = discoverKxmProjectRoot(runtime.cwd);
   if (projectRoot && /^run_[a-f0-9]{32}$/i.test(runId)) {
     if (runtime.dryRun) {
-      printWorker(runtime, worker, { ok: true, command: "signal", runId, signalKey, status, summary, evidence }, "would post signal to KXM run");
+      printWorker(runtime, worker, { ok: true, command: "signal", dryRun: true, runId, signalKey, status, summary, evidence }, "would post signal to KXM run");
       return 0;
     }
     const deliveryId = String(deliveryIdFlag || `cli-signal:${randomUUID()}`);
@@ -557,7 +573,7 @@ export async function cmdSignal(runtime: Runtime, runId: string, signalKey: stri
     return 2;
   }
   if (runtime.dryRun) {
-    printWorker(runtime, worker, { ok: true, command: "signal", runId, signalKey, status, summary, evidence }, "would post signed signal");
+    printWorker(runtime, worker, { ok: true, command: "signal", dryRun: true, runId, signalKey, status, summary, evidence }, "would post signed signal");
     return 0;
   }
   const deliveryId = String(deliveryIdFlag || `cli-signal:${randomUUID()}`);

package/plugins/kxm/src/cli.ts

@@ -30,6 +30,7 @@ import { ensureKxmSupervisor, kxmRuntimeRequest } from "./runtime-supervisor.ts"
 // Submodule imports
 import {
   print,
+  refuseDryRun,
   runtimeFrom,
   redactConfiguredValues,
   type CliContext,
@@ -172,6 +173,54 @@ const USAGE_ERROR_CODES = new Set([
   "commander.optionMissingArgument",
 ]);
 
+/**
+ * Every command that answers `--dry-run` without changing anything: it only
+ * reads, or it prints the plan (`dryRun: true` plus `planned`) and stops.
+ * A command missing from this set is refused under `--dry-run` with
+ * `dry_run_unsupported` before its action runs, so a new command that forgets
+ * to check the flag fails closed instead of mutating. Keyed by command path.
+ */
+const DRY_RUN_COMMANDS: ReadonlySet<string> = new Set([
+  "init", "backup", "restore", "run", "explain", "suggest", "update", "dash", "completion", "completion install",
+  "runs status", "runs drive", "runs receipt", "runs cancel", "runs list",
+  "tenant status", "models inventory-refresh", "harness list", "auth token",
+  "routes list", "routes count", "routes admit", "routes disable",
+  "runtime start", "runtime status", "runtime sync-retry", "runtime stop",
+  "trust diff", "trust check", "agent worker",
+  "session status", "session brief", "session token", "session start", "session stop",
+  "peer list", "peer send", "peer get", "peer await", "peer cancel", "peer fanout", "peer inbox", "peer reply",
+  "workflow list", "workflow get", "workflow checkpoint", "workflow record", "workflow wait", "workflow signal",
+  "workflow start", "workflow export", "workflow definitions", "workflow add", "workflow remove", "workflow modify",
+  "role list", "role get", "role add", "role remove", "role modify", "role hosts", "role set-host", "role resume",
+  "gate validate", "gate artifacts-exist", "gate degrade", "gate signal", "gate github watch",
+  "improve report",
+  "context get", "context recall", "context state", "context episode", "context promote", "context explain",
+  "context wiki-compile", "context wiki-lint",
+  "skills create", "skills evaluate", "skills promote", "skills reject", "skills list", "skills verify",
+  "memory brief", "memory note", "memory sync",
+  "routing report", "routing benchmark",
+  "ssh info", "ssh run", "ssh file", "ssh close",
+  "hub view", "hub start", "hub stop", "hub bind", "hub unbind",
+  "config get", "config set", "config list",
+  "goal create", "goal list",
+  "task create", "task list", "task get", "task run", "task sync",
+  "studio layout", "studio serve",
+]);
+
+class DryRunRefused extends Error {
+  readonly code: number;
+  constructor(code: number) {
+    super("dry_run_unsupported");
+    this.code = code;
+  }
+}
+
+function commandPath(command: Command): string {
+  const names: string[] = [];
+  for (let current: Command | null = command; current?.parent; current = current.parent) names.unshift(current.name());
+  return names.join(" ");
+}
+
 function addGlobalOptions(command: Command): Command {
   return command
     .option("--json", "Print machine-readable JSON")
@@ -331,6 +380,13 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
     })
     .helpCommand("help", "Show help");
   addGlobalOptions(program);
+  program.hook("preAction", (_program, actionCommand) => {
+    const opts = actionCommand.optsWithGlobals() as { dryRun?: boolean; json?: boolean };
+    if (!opts.dryRun) return;
+    const path = commandPath(actionCommand);
+    if (DRY_RUN_COMMANDS.has(path)) return;
+    throw new DryRunRefused(refuseDryRun(ctx.io, Boolean(opts.json), path, "this command cannot plan without making changes; rerun without --dry-run"));
+  });
 
   program.command("init").description("Create, validate, repair, or join a KXM project")
     .option("--json", "Print machine-readable JSON")
@@ -1222,6 +1278,7 @@ export async function runCli(
     return result.code;
   } catch (error) {
     if (error instanceof CommanderError) return mapCommanderError(error);
+    if (error instanceof DryRunRefused) return error.code;
     throw error;
   }
 }

package/plugins/kxm/src/commands.ts

@@ -823,8 +823,8 @@ export const AGENT_COMMANDS: readonly AgentCommand[] = [
         summary: { type: "string", description: "Promotion summary" },
         authority: {
           type: "string",
-          enum: ["policy", "instruction", "evidence", "hypothesis"],
-          description: "Authority class",
+          enum: ["evidence", "hypothesis"],
+          description: "Authority class; an agent's proposal is peer origin, so evidence at most",
         },
         confidence: {
           type: "string",