@kontextmind/kxm 0.7.85 → 0.7.87

package/plugins/kxm/dist/runtime.js

@@ -18372,7 +18372,7 @@ function discoverProjectStores(projectRoot, options = {}) {
   }
   return stores;
 }
-function createBackup(options = {}) {
+function planBackup(options = {}) {
   const projectRoot = options.projectRoot ? resolve3(options.projectRoot) : process.cwd();
   const stores = discoverProjectStores(projectRoot, {
     ...options.hubDataPath !== void 0 ? { hubDataPath: options.hubDataPath } : {}
@@ -18380,30 +18380,35 @@ function createBackup(options = {}) {
   if (stores.length === 0) {
     throw databaseError("backup_no_stores", projectRoot, "no existing SQLite stores found to backup");
   }
-  const now = /* @__PURE__ */ new Date();
-  const timestamp = now.toISOString().replace(/[:.]/g, "-");
-  const backupId = `bk_${randomBytes(8).toString("hex")}`;
+  const createdAt = (/* @__PURE__ */ new Date()).toISOString();
+  const timestamp = createdAt.replace(/[:.]/g, "-");
   const outDir = options.outDir ? resolve3(options.outDir) : join4(projectRoot, ".kxm", "backups", `backup-${timestamp}`);
-  if (!existsSync4(outDir)) {
-    mkdirSync(outDir, { recursive: true, mode: 448 });
-  }
-  const backedUpStores = [];
   const usedFilenames = /* @__PURE__ */ new Set();
-  for (const store of stores) {
+  const planned = stores.map((store) => {
     let filename = basename2(store.sourcePath);
     if (usedFilenames.has(filename)) {
       const sanitizedId = store.storeId.replace(/[^a-zA-Z0-9_.-]/g, "_");
       filename = `${sanitizedId}-${filename}`;
     }
     usedFilenames.add(filename);
-    const targetFile = join4(outDir, filename);
-    const record2 = backupDatabaseFile(store.sourcePath, targetFile, store.storeId);
-    backedUpStores.push(record2);
+    return { storeId: store.storeId, sourcePath: store.sourcePath, backupFile: filename };
+  });
+  return { projectRoot, outDir, createdAt, stores: planned };
+}
+function createBackup(options = {}) {
+  const { projectRoot, outDir, createdAt, stores } = planBackup(options);
+  const backupId = `bk_${randomBytes(8).toString("hex")}`;
+  if (!existsSync4(outDir)) {
+    mkdirSync(outDir, { recursive: true, mode: 448 });
+  }
+  const backedUpStores = [];
+  for (const store of stores) {
+    backedUpStores.push(backupDatabaseFile(store.sourcePath, join4(outDir, store.backupFile), store.storeId));
   }
   const manifest = {
     schema: "kxm.backup-manifest.v1",
     backupId,
-    createdAt: now.toISOString(),
+    createdAt,
     projectRoot,
     stores: backedUpStores
   };
@@ -18415,7 +18420,7 @@ function createBackup(options = {}) {
   writeFileSync(manifestPath, finalJson, "utf8");
   return { manifest, outDir };
 }
-function restoreBackup(manifestPathOrDir, options = {}) {
+function planRestore(manifestPathOrDir, options = {}) {
   let manifestPath = resolve3(manifestPathOrDir);
   const stat = lstatSync2(manifestPath, { throwIfNoEntry: false });
   if (!stat) {
@@ -18438,7 +18443,7 @@ function restoreBackup(manifestPathOrDir, options = {}) {
   if (manifest.schema !== "kxm.backup-manifest.v1" || !Array.isArray(manifest.stores) || manifest.stores.length === 0) {
     throw databaseError("restore_manifest_invalid", manifestPath, "manifest is not a valid kxm.backup-manifest.v1 document");
   }
-  const restoredStores = [];
+  const stores = [];
   for (const store of manifest.stores) {
     const backupFilePath = join4(manifestDir, store.backupFile);
     if (!existsSync4(backupFilePath)) {
@@ -18452,24 +18457,35 @@ function restoreBackup(manifestPathOrDir, options = {}) {
         `backup file ${store.backupFile} sha256 ${actualSha256} does not match manifest hash ${store.sha256}`
       );
     }
-    const maxSupported = kxmBackupCeiling(store.storeId);
+    const maxSupportedVersion = kxmBackupCeiling(store.storeId);
+    if (store.schemaVersion > maxSupportedVersion) {
+      throw databaseError(
+        "runtime_schema_newer",
+        backupFilePath,
+        `backup store ${store.storeId} schema version ${store.schemaVersion} is newer than supported maximum ${maxSupportedVersion}`
+      );
+    }
     let targetPath = store.sourcePath;
     if (options.projectRoot && manifest.projectRoot && targetPath.startsWith(manifest.projectRoot)) {
       const rel = targetPath.slice(manifest.projectRoot.length).replace(/^[\\/]+/, "");
       targetPath = join4(resolve3(options.projectRoot), rel);
     }
-    const result = restoreDatabaseFile(
-      backupFilePath,
-      targetPath,
-      store.storeId,
-      store.schemaVersion,
-      maxSupported
-    );
-    restoredStores.push(result);
+    stores.push({ storeId: store.storeId, backupFilePath, targetPath, schemaVersion: store.schemaVersion, maxSupportedVersion });
   }
+  return { manifestPath, backupId: manifest.backupId, stores };
+}
+function restoreBackup(manifestPathOrDir, options = {}) {
+  const plan = planRestore(manifestPathOrDir, options);
+  const restoredStores = plan.stores.map((store) => restoreDatabaseFile(
+    store.backupFilePath,
+    store.targetPath,
+    store.storeId,
+    store.schemaVersion,
+    store.maxSupportedVersion
+  ));
   return {
-    manifestPath,
-    backupId: manifest.backupId,
+    manifestPath: plan.manifestPath,
+    backupId: plan.backupId,
     restoredStores
   };
 }
@@ -29003,17 +29019,38 @@ async function startKxmRuntimeSupervisorInner(paths, requestedPortOption, now, e
     }
   }, 1e3);
   heartbeat.unref();
-  for (const reg of registry.projectsForRuntime(activeRuntimeId)) {
-    try {
-      contextFor(reg.projectRoot);
-    } catch {
-      logger.warn({
-        event: "runtime_sync_context_unavailable",
-        projectId: reg.projectId,
-        message: `cannot reopen ${reg.projectRoot}: its outbox rows stay pending`
-      });
+  const reopenRegisteredProjects = () => {
+    for (const reg of registry.projectsForRuntime(activeRuntimeId)) {
+      const key = projectRuntimeKey(reg.projectRoot);
+      if (contexts.has(key)) continue;
+      try {
+        contextFor(reg.projectRoot);
+        syncStatuses.delete(key);
+      } catch (error) {
+        const reason = syncFailureText(error);
+        const prior = syncStatuses.get(key);
+        if (prior === void 0 || prior.lastError !== reason) {
+          logger.warn({
+            event: "runtime_sync_context_unavailable",
+            projectId: reg.projectId,
+            message: `cannot reopen ${reg.projectRoot}: its outbox rows stay pending`,
+            reason
+          });
+        }
+        syncStatuses.set(key, {
+          projectId: reg.projectId,
+          projectRoot: reg.projectRoot,
+          homeRuntimeId: activeRuntimeId,
+          state: "blocked",
+          outbox: { pending: 0, acked: 0, refused: 0, refusals: [] },
+          storeReadable: false,
+          consecutiveFailures: 1,
+          lastError: reason
+        });
+      }
     }
-  }
+  };
+  reopenRegisteredProjects();
   const recordSyncStatus = (context, next) => {
     const key = projectRuntimeKey(context.projectRoot);
     const previous = syncStatuses.get(key);
@@ -29042,6 +29079,7 @@ async function startKxmRuntimeSupervisorInner(paths, requestedPortOption, now, e
     if (syncing || stopping) return;
     syncing = true;
     void (async () => {
+      reopenRegisteredProjects();
       for (const context of [...contexts.values()]) {
         const key = projectRuntimeKey(context.projectRoot);
         const prior = syncStatuses.get(key);
@@ -31414,7 +31452,9 @@ export {
   parsePiOneShotUsage,
   parseSshConfig,
   persistKxmRunState,
+  planBackup,
   planHarnessUpdate,
+  planRestore,
   probeHarnessAssignment,
   probeHarnessAssignmentAsync,
   probeHarnesses,

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.85",
+  "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;