@kontextmind/kxm 0.7.86 → 0.7.87

package/plugins/kxm/dist/server.js

@@ -14783,7 +14783,7 @@ import { createHash as createHash5, createHmac } from "node:crypto";
 import { existsSync as existsSync6 } from "node:fs";
 import { createServer } from "node:http";
 import { isIP } from "node:net";
-import { dirname as dirname5, join as join6, resolve as resolve6 } from "node:path";
+import { dirname as dirname6, join as join6, resolve as resolve6 } from "node:path";
 
 // plugins/kxm/src/protocol.ts
 import { randomUUID } from "node:crypto";
@@ -18213,7 +18213,7 @@ function boundedRefs(value, field) {
 var import_yaml4 = __toESM(require_dist(), 1);
 import { createHash as createHash4 } from "node:crypto";
 import { existsSync as existsSync4, mkdirSync as mkdirSync2, readdirSync as readdirSync3, readFileSync as readFileSync3, renameSync, rmSync, statSync, writeFileSync as writeFileSync2 } from "node:fs";
-import { join as join4 } from "node:path";
+import { dirname as dirname4, join as join4 } from "node:path";
 var SKILL_CANDIDATE_SCHEMA = "kxm.skill-candidate.v1";
 var SKILL_EVALUATION_SCHEMA = "kxm.skill-evaluation.v1";
 var SKILL_DECISION_SCHEMA = "kxm.skill-decision.v1";
@@ -18301,10 +18301,22 @@ var SkillLifecycle = class {
   root;
   now;
   allowOptimizationEvals;
+  dryRun;
+  /** What a `dryRun` lifecycle would have written or moved, in order. */
+  planned = [];
   constructor(root, options = {}) {
     this.root = root;
     this.now = options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
     this.allowOptimizationEvals = options.allowOptimizationEvals === true;
+    this.dryRun = options.dryRun === true;
+  }
+  write(file, content) {
+    if (this.dryRun) {
+      this.planned.push({ action: "write", target: file });
+      return;
+    }
+    mkdirSync2(dirname4(file), { recursive: true });
+    writeFileSync2(file, content);
   }
   dir(state) {
     return join4(this.root, state === "candidate" ? "candidates" : `${state}s`.replace("rejecteds", "rejected").replace("promoteds", "promoted"));
@@ -18317,15 +18329,14 @@ var SkillLifecycle = class {
     return { dir, metadata: join4(dir, "metadata.json"), skill: join4(dir, "SKILL.md") };
   }
   appendHistory(id, record) {
-    mkdirSync2(join4(this.root, "history"), { recursive: true });
     const line = `${JSON.stringify(record)}
 `;
     if (existsSync4(this.historyFile(id))) {
       const existing = readFileSync3(this.historyFile(id), "utf8");
       const lines = existing.split("\n").filter((entry) => entry.trim());
-      writeFileSync2(this.historyFile(id), [...lines.slice(-499), line.trim()].join("\n") + "\n");
+      this.write(this.historyFile(id), [...lines.slice(-499), line.trim()].join("\n") + "\n");
     } else {
-      writeFileSync2(this.historyFile(id), line);
+      this.write(this.historyFile(id), line);
     }
   }
   history(id) {
@@ -18346,6 +18357,10 @@ var SkillLifecycle = class {
     if (!existsSync4(fromDir)) {
       throw new SkillLifecycleError("skill_not_found", `skill ${id} not found in ${from}`);
     }
+    if (this.dryRun) {
+      this.planned.push({ action: "move", target: `${fromDir} -> ${toDir}` });
+      return;
+    }
     mkdirSync2(this.dir(to), { recursive: true });
     if (existsSync4(toDir)) rmSync(toDir, { recursive: true, force: true });
     renameSync(fromDir, toDir);
@@ -18389,7 +18404,7 @@ var SkillLifecycle = class {
     if (!harness) throw new SkillLifecycleError("invalid_skill_compatibility", "compatibility.harness is required");
     const contentSha256 = skillContentSha256(content);
     const id = skillIdFor(name, contentSha256);
-    const { dir, metadata, skill } = this.paths("candidate", id);
+    const { metadata, skill } = this.paths("candidate", id);
     if (existsSync4(metadata)) {
       throw new SkillLifecycleError(
         "skill_candidate_exists",
@@ -18409,9 +18424,8 @@ var SkillLifecycle = class {
       createdAt: this.now(),
       ...input.supersedes ? { supersedes: input.supersedes } : {}
     };
-    mkdirSync2(dir, { recursive: true });
-    writeFileSync2(skill, content);
-    writeFileSync2(metadata, `${JSON.stringify(record, null, 2)}
+    this.write(skill, content);
+    this.write(metadata, `${JSON.stringify(record, null, 2)}
 `);
     this.appendHistory(id, { schema: "kxm.skill-history-event.v1", event: "candidate_created", by: createdBy, supersedes: input.supersedes, at: record.createdAt });
     return record;
@@ -18500,18 +18514,15 @@ var SkillLifecycle = class {
     };
     const candidatePaths = this.paths("candidate", candidateId);
     const promotedPaths = this.paths("promoted", candidateId);
-    mkdirSync2(promotedPaths.dir, { recursive: true });
     const skillContent = readFileSync3(candidatePaths.skill, "utf8");
     const metadataContent = readFileSync3(candidatePaths.metadata, "utf8");
-    writeFileSync2(promotedPaths.skill, skillContent);
-    writeFileSync2(promotedPaths.metadata, metadataContent);
-    const patchesDir = join4(this.root, "patches");
-    mkdirSync2(patchesDir, { recursive: true });
-    const patchPath = join4(patchesDir, `${candidateId}.patch`);
+    this.write(promotedPaths.skill, skillContent);
+    this.write(promotedPaths.metadata, metadataContent);
+    const patchPath = join4(this.root, "patches", `${candidateId}.patch`);
     const relSkillPath = `.kxm/skills/promoted/${candidateId}/SKILL.md`;
     const relMetaPath = `.kxm/skills/promoted/${candidateId}/metadata.json`;
     const patch = `${createUnifiedPatch(relSkillPath, skillContent)}${createUnifiedPatch(relMetaPath, metadataContent)}`;
-    writeFileSync2(patchPath, patch, "utf8");
+    this.write(patchPath, patch);
     this.appendHistory(candidateId, record);
     return { ...metadata, patch, patchPath };
   }
@@ -19031,7 +19042,7 @@ import {
   unlinkSync,
   writeFileSync as writeFileSync4
 } from "node:fs";
-import { basename as basename3, dirname as dirname4, join as join5, resolve as resolve4 } from "node:path";
+import { basename as basename3, dirname as dirname5, join as join5, resolve as resolve4 } from "node:path";
 
 // plugins/kxm/src/sqlite.ts
 import { createRequire } from "node:module";
@@ -19078,7 +19089,7 @@ function databaseError(code, file, message) {
   return new KxmConfigError([issue2]);
 }
 function checkedParent(path, description) {
-  const parent = dirname4(path);
+  const parent = dirname5(path);
   if (!existsSync5(parent)) mkdirSync4(parent, { recursive: true, mode: 448 });
   const stat = lstatSync2(parent, { throwIfNoEntry: false });
   if (!stat || stat.isSymbolicLink() || !stat.isDirectory()) {
@@ -20359,7 +20370,7 @@ function createMeshHub(options = {}) {
   const logger = options.logger ?? (() => void 0);
   const hubNow = options.now ?? (() => Date.now());
   const assetsDir2 = options.assetsDir;
-  const hubRepoRoot = options.repoRoot ?? (options.dataPath && options.dataPath !== ":memory:" ? resolve6(dirname5(dirname5(options.dataPath))) : process.cwd());
+  const hubRepoRoot = options.repoRoot ?? (options.dataPath && options.dataPath !== ":memory:" ? resolve6(dirname6(dirname6(options.dataPath))) : process.cwd());
   const store = new MeshStore(options.dataPath);
   const agents = store.agents;
   const messages = store.messages;
@@ -22556,11 +22567,11 @@ data: ${JSON.stringify({ agent: publicAgent(current, staleAfterMs) })}
 
 // plugins/kxm/src/server.ts
 import { mkdirSync as mkdirSync6, readFileSync as readFileSync5 } from "node:fs";
-import { dirname as dirname7, join as join7, resolve as resolve7 } from "node:path";
+import { dirname as dirname8, join as join7, resolve as resolve7 } from "node:path";
 
 // plugins/kxm/src/logger.ts
 import { appendFileSync, existsSync as existsSync7, mkdirSync as mkdirSync5, renameSync as renameSync3, statSync as statSync2, unlinkSync as unlinkSync2 } from "node:fs";
-import { dirname as dirname6 } from "node:path";
+import { dirname as dirname7 } from "node:path";
 var LOG_LEVEL_PRIORITY = {
   debug: 10,
   info: 20,
@@ -22666,7 +22677,7 @@ function createLogger(options) {
         currentSize = 0;
       }
       try {
-        mkdirSync5(dirname6(filePath), { recursive: true });
+        mkdirSync5(dirname7(filePath), { recursive: true });
         appendFileSync(filePath, line, { encoding: "utf8", mode: 384 });
         currentSize += lineBytes;
       } catch {
@@ -22729,7 +22740,7 @@ var rateLimitWindowMs = Number.parseInt(
   process.env.KXM_RATE_LIMIT_WINDOW_MS ?? String(DEFAULT_RATE_LIMIT_WINDOW_MS),
   10
 );
-for (const directory of [configDir, logsDir, assetsDir, stateDir, dirname7(logPath)]) {
+for (const directory of [configDir, logsDir, assetsDir, stateDir, dirname8(logPath)]) {
   mkdirSync6(directory, { recursive: true });
 }
 var structuredLog = createLogger({

package/plugins/kxm/package.json

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

package/plugins/kxm/src/cli/context-skills.ts

@@ -1,5 +1,5 @@
 import { readFileSync } from "node:fs";
-import { join, relative } from "node:path";
+import { join, relative, resolve } from "node:path";
 import { redactSecrets } from "../redact.ts";
 import {
   createMemoryNote,
@@ -10,7 +10,7 @@ import {
 } from "../memory.ts";
 import { SkillLifecycle, type SkillEvaluationKind, type SkillState } from "../skills.ts";
 import { writeCompiledWiki } from "../wiki.ts";
-import { print, type Runtime } from "./types.ts";
+import { print, printPlan, type Runtime } from "./types.ts";
 
 /** Authenticated hub POST for context operations. The CLI operates as the
  * control plane: the administrative token scopes one project per request. */
@@ -122,6 +122,15 @@ export async function cmdContextPromote(runtime: Runtime, project: string, propo
     runtime.io.stderr("context promote --evidence must contain at least one durable evidence reference\n");
     return 2;
   }
+  if (runtime.dryRun) {
+    printPlan(
+      runtime,
+      { command: "context promote", project, proposalId, evidence },
+      [{ action: "request", target: `POST ${runtime.serverUrl.replace(/\/$/, "")}/v1/context/state/promote` }],
+      `promote proposal ${proposalId} in ${project}`,
+    );
+    return 0;
+  }
   const response = await hubContextPost({
     serverUrl: runtime.serverUrl,
     path: "/v1/context/state/promote",
@@ -158,6 +167,16 @@ export async function cmdContextWikiCompile(runtime: Runtime, project: string, o
     return 1;
   }
   const compiled = response.body as { audit: { pages: string[]; contradictions: number }; pages: { path: string; content: string }[] };
+  if (options.out && runtime.dryRun) {
+    const outDir = options.out;
+    printPlan(
+      runtime,
+      { command: "context wiki-compile", project, pages: compiled.audit.pages, openContradictions: compiled.audit.contradictions, outDir },
+      compiled.pages.map((page) => ({ action: "write", target: resolve(outDir, page.path) })),
+      `write ${compiled.pages.length} compiled wiki page(s) to ${outDir}`,
+    );
+    return 0;
+  }
   let written: string[] = [];
   if (options.out) {
     const pages = new Map(compiled.pages.map((page) => [page.path, page.content]));
@@ -233,7 +252,7 @@ export async function cmdSkillsCreate(runtime: Runtime, options: { file: string;
 }
 
 export async function cmdSkillsEvaluate(runtime: Runtime, skillId: string, options: { kind: string; evaluator: string; fail?: boolean | undefined; score?: string | undefined; details?: string | undefined }): Promise<number> {
-  const lifecycle = new SkillLifecycle(skillsRoot(runtime));
+  const lifecycle = new SkillLifecycle(skillsRoot(runtime), { dryRun: runtime.dryRun });
   try {
     const outcome = lifecycle.evaluate(skillId, {
       kind: options.kind as SkillEvaluationKind,
@@ -242,6 +261,10 @@ export async function cmdSkillsEvaluate(runtime: Runtime, skillId: string, optio
       ...(options.score !== undefined ? { score: Number(options.score) } : {}),
       ...(options.details ? { details: options.details } : {}),
     });
+    if (runtime.dryRun) {
+      printPlan(runtime, { command: "skills evaluate", skillId, quarantined: outcome.quarantined, evaluation: outcome.evaluation }, lifecycle.planned, `record ${options.kind} evaluation${outcome.quarantined ? " (candidate quarantined)" : ""}`);
+      return 0;
+    }
     print(runtime.io, runtime.json, { ok: true, command: "skills evaluate", skillId, quarantined: outcome.quarantined, evaluation: outcome.evaluation }, `recorded ${options.kind} evaluation${outcome.quarantined ? " (candidate quarantined)" : ""}`);
     return 0;
   } catch (error) {
@@ -252,13 +275,17 @@ export async function cmdSkillsEvaluate(runtime: Runtime, skillId: string, optio
 }
 
 export async function cmdSkillsPromote(runtime: Runtime, skillId: string, options: { decidedBy: string; evidence: string; reason?: string | undefined }): Promise<number> {
-  const lifecycle = new SkillLifecycle(skillsRoot(runtime));
+  const lifecycle = new SkillLifecycle(skillsRoot(runtime), { dryRun: runtime.dryRun });
   try {
     const promoted = lifecycle.promote(skillId, {
       decidedBy: options.decidedBy,
       reason: options.reason ?? "passed protected evaluation",
       evidenceRefs: csv(options.evidence) ?? [],
     });
+    if (runtime.dryRun) {
+      printPlan(runtime, { command: "skills promote", skillId, metadata: promoted, patchPath: promoted.patchPath }, lifecycle.planned, `promote skill ${skillId}`);
+      return 0;
+    }
     print(runtime.io, runtime.json, { ok: true, command: "skills promote", skillId, metadata: promoted, patchPath: promoted.patchPath }, `promoted skill ${skillId} (patch: ${promoted.patchPath})`);
     return 0;
   } catch (error) {
@@ -269,9 +296,13 @@ export async function cmdSkillsPromote(runtime: Runtime, skillId: string, option
 }
 
 export async function cmdSkillsReject(runtime: Runtime, skillId: string, options: { decidedBy: string; reason?: string | undefined }): Promise<number> {
-  const lifecycle = new SkillLifecycle(skillsRoot(runtime));
+  const lifecycle = new SkillLifecycle(skillsRoot(runtime), { dryRun: runtime.dryRun });
   try {
     const metadata = lifecycle.reject(skillId, { decidedBy: options.decidedBy, reason: options.reason ?? "rejected" });
+    if (runtime.dryRun) {
+      printPlan(runtime, { command: "skills reject", skillId, metadata }, lifecycle.planned, `reject skill ${skillId} (history retained)`);
+      return 0;
+    }
     print(runtime.io, runtime.json, { ok: true, command: "skills reject", skillId, metadata }, `rejected skill ${skillId} (history retained)`);
     return 0;
   } catch (error) {
@@ -339,8 +370,13 @@ export async function cmdMemoryNote(
       scope: (options.scope ?? "project") as MemoryScope,
       ...(options.kind !== undefined ? { kind: options.kind } : {}),
       ...(options.body !== undefined ? { body: options.body } : {}),
+      dryRun: runtime.dryRun,
     });
     const relPath = relative(runtime.cwd, path);
+    if (runtime.dryRun) {
+      printPlan(runtime, { command: "memory note", candidate: record, path: relPath }, [{ action: "write", target: path }], `record memory candidate in ${relPath} (the id is assigned when it is recorded)`);
+      return 0;
+    }
     print(
       runtime.io,
       runtime.json,
@@ -357,7 +393,16 @@ export async function cmdMemoryNote(
 
 export async function cmdMemorySync(runtime: Runtime): Promise<number> {
   try {
-    const result = syncHarnessMemory(runtime.cwd);
+    const result = syncHarnessMemory(runtime.cwd, { dryRun: runtime.dryRun });
+    if (runtime.dryRun) {
+      printPlan(
+        runtime,
+        { command: "memory sync", ...result },
+        [...result.created, ...result.updated].map((file) => ({ action: "write", target: join(runtime.cwd, file) })),
+        "regenerate project memory blocks in AGENTS.md, CLAUDE.md, and GEMINI.md",
+      );
+      return 0;
+    }
     print(
       runtime.io,
       runtime.json,

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

@@ -6,7 +6,7 @@ import { defaultProjectName } from "../project-name.ts";
 import { hasClientHubCredential, resolveClientHubAuthToken } from "../hub-env.ts";
 import { agentWorker, type Worker } from "../envelope.ts";
 import { MESH_TUI_PANELS, runMeshTui, type MeshTuiPanel } from "../tui.ts";
-import { formatSessionBriefText, loadSessionBriefAsync, type SessionHubStatus } from "../session-work.ts";
+import { formatSessionBriefText, loadSessionBriefAsync, readCachedSessionBrief, type SessionHubStatus } from "../session-work.ts";
 import {
   HUB_BINDING_SCHEMA,
   HubBindingError,
@@ -47,11 +47,13 @@ import {
 import { createSession, loadNamedWorkers, rosterNames, sessionAssetDirs, workflowAssetDirs, writeSession } from "../session.ts";
 import {
   print,
+  printPlan,
   printWorker,
   hostMode,
   workspaceEnv,
   spawnScript,
   processExists,
+  type PlannedChange,
   type Runtime,
 } from "./types.ts";
 
@@ -140,7 +142,7 @@ export async function refreshKxmUpdateNotice(
   }
   const fetched = await fetchLatestKxmVersion(resolved.source, runtime.env, runtime.fetchImpl);
   const notice = noticeFromVersions(installed, fetched.latest, resolved, fetched.error, fetched.asset);
-  writeUpdateCache(runtime.dirs.state, notice);
+  if (!runtime.dryRun) writeUpdateCache(runtime.dirs.state, notice);
   return notice;
 }
 
@@ -556,6 +558,12 @@ export async function cmdSessionStatus(runtime: Runtime): Promise<number> {
 }
 
 export async function cmdAuthToken(runtime: Runtime, options: { status?: boolean | undefined; clear?: boolean | undefined; issue?: boolean | undefined } = {}): Promise<number> {
+  const tokenFile = sessionTokenPath(runtime.env.KXM_USER_CONFIG_DIR);
+  if (options.clear && runtime.dryRun) {
+    const present = existsSync(tokenFile);
+    printPlan(runtime, { command: "auth token", cleared: present }, present ? [{ action: "delete", target: tokenFile }] : [], present ? "clear the session token from disk" : "no session token file to clear");
+    return 0;
+  }
   if (options.clear) {
     const cleared = clearSessionTokenFromDisk({ userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
     print(
@@ -615,18 +623,19 @@ export async function cmdAuthToken(runtime: Runtime, options: { status?: boolean
     return 1;
   }
 
+  const existingToken = options.issue ? undefined : readSessionTokenFromDisk({ userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
+  if (runtime.dryRun && !existingToken) {
+    // The token is only worth printing once it is on disk; a dry run never is.
+    printPlan(runtime, { command: "auth token" }, [{ action: "write", target: tokenFile }], "issue an operator session token and persist it");
+    return 0;
+  }
+
   let token: string;
-  if (options.issue) {
+  if (existingToken) {
+    token = existingToken.token;
+  } else {
     token = mintSessionToken({ preset: "operator" });
     persistSessionTokenToDisk(token, { userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
-  } else {
-    const existing = readSessionTokenFromDisk({ userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
-    if (existing) {
-      token = existing.token;
-    } else {
-      token = mintSessionToken({ preset: "operator" });
-      persistSessionTokenToDisk(token, { userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
-    }
   }
 
   print(runtime.io, runtime.json, { ok: true, command: "auth token", token }, token);
@@ -635,11 +644,17 @@ export async function cmdAuthToken(runtime: Runtime, options: { status?: boolean
 
 export async function cmdSessionBrief(runtime: Runtime, options: { status?: boolean | undefined; token?: boolean | undefined } = {}): Promise<number> {
   const existing = readSessionTokenFromDisk({ userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
-  const sessionToken = existing ? existing.token : mintSessionToken({ preset: "operator" });
-  if (!existing) {
+  // A dry run neither mints nor persists a token; it names the file it would write.
+  const planned: PlannedChange[] = existing ? [] : [{ action: "write", target: sessionTokenPath(runtime.env.KXM_USER_CONFIG_DIR) }];
+  const sessionToken = existing?.token ?? (runtime.dryRun ? undefined : mintSessionToken({ preset: "operator" }));
+  if (!existing && sessionToken) {
     persistSessionTokenToDisk(sessionToken, { userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
   }
   if (options.token) {
+    if (!sessionToken) {
+      printPlan(runtime, { command: "session brief" }, planned, "issue an operator session token and persist it");
+      return 0;
+    }
     print(runtime.io, runtime.json, { ok: true, command: "session brief", sessionToken }, sessionToken);
     return 0;
   }
@@ -668,9 +683,19 @@ export async function cmdSessionBrief(runtime: Runtime, options: { status?: bool
 
   const brief = await loadSessionBriefAsync(runtime.dirs.workdir, env, undefined, hub, {
     fetchImpl: runtime.fetchImpl,
-    sessionToken,
+    ...(sessionToken ? { sessionToken } : {}),
+    writeCache: !runtime.dryRun,
   });
 
+  if (runtime.dryRun) {
+    if (!readCachedSessionBrief(runtime.dirs.state)) planned.push({ action: "write", target: join(runtime.dirs.state, "session-brief.json") });
+    print(runtime.io, runtime.json, { ...brief, dryRun: true, planned }, [
+      options.status ? brief.statusLine : formatSessionBriefText(brief),
+      ...planned.map((change) => `dry run: would ${change.action} ${change.target}`),
+    ].join("\n"));
+    return 0;
+  }
+
   if (options.status) {
     print(runtime.io, runtime.json, brief, brief.statusLine);
     return 0;

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",