@kontextmind/kxm 0.7.86 → 0.7.88

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";
@@ -17303,8 +17303,8 @@ var AGENT_COMMANDS = [
         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",
@@ -18082,6 +18082,9 @@ var NativeStateProvider = class {
     if (change?.schema !== "kxm.state-change-proposal.v1") {
       throw new ProtocolError(400, "invalid state change proposal schema", "invalid_state_proposal");
     }
+    if (change.origin !== "peer" && change.origin !== "human") {
+      throw new ProtocolError(400, "state change proposal origin must be peer or human", "invalid_state_proposal");
+    }
     const project = requireNonEmpty(change.project, "proposal project");
     const key = requireNonEmpty(change.key, "proposal key");
     const evidenceRefs = boundedRefs(change.evidenceRefs, "proposal evidenceRefs");
@@ -18091,7 +18094,7 @@ var NativeStateProvider = class {
       project,
       summary: change.summary,
       provenance: {
-        sourceType: change.proposedBy.startsWith("agent_") ? "peer" : "human",
+        sourceType: change.origin,
         sourceRef: `proposed-by:${change.proposedBy}`
       },
       authority: change.authority,
@@ -18213,7 +18216,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 +18304,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 +18332,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 +18360,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 +18407,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 +18427,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 +18517,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 +19045,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 +19092,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 +20373,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;
@@ -20470,12 +20484,12 @@ function createMeshHub(options = {}) {
       if (agent.project !== project) {
         throw new ProtocolError(403, "context requests are limited to the agent's project", "context_isolation_violation");
       }
-      return { project, caller: agent.id };
+      return { project, caller: agent.id, credential: "agent" };
     }
     requireAdminAuth(request);
     const callerHeader = request.headers["x-kxm-caller-id"];
     const caller = typeof callerHeader === "string" && callerHeader.trim() ? callerHeader.trim() : "kxm-admin";
-    return { project, caller };
+    return { project, caller, credential: "admin" };
   }
   function requireAdminAuth(request) {
     if (!authToken2 && isLoopback(host2)) return;
@@ -21582,7 +21596,17 @@ data: ${JSON.stringify({ type: "ops", project, topic: "agents", at: nowIso() })}
       const contextStateProposeMatch = url.pathname.match(/^\/v1\/context\/state\/propose$/);
       if (method === "POST" && contextStateProposeMatch) {
         const body = await readJson(request);
-        const { project: callerProject, caller: callerId } = contextCallerProject(request, body.project);
+        const { project: callerProject, caller: callerId, credential } = contextCallerProject(request, body.project);
+        if (credential === "admin") requireConfiguredAdminAuth(request, "human-origin state proposals");
+        if (body.proposedBy !== void 0 && body.proposedBy !== callerId) {
+          logger({ event: "security_alert", alert: "state_proposer_mismatch", project: callerProject, callerId, credential });
+          throw new ProtocolError(
+            403,
+            "proposedBy must name the authenticated caller",
+            "state_proposer_mismatch"
+          );
+        }
+        const origin = credential === "agent" ? "peer" : "human";
         const proposalId = await stateProvider.propose({
           schema: "kxm.state-change-proposal.v1",
           project: callerProject,
@@ -21591,11 +21615,12 @@ data: ${JSON.stringify({ type: "ops", project, topic: "agents", at: nowIso() })}
           authority: parseContextAuthority(body.authority),
           confidence: parseContextConfidence(body.confidence),
           evidenceRefs: boundedStringList(body.evidenceRefs, "evidenceRefs", 32),
-          proposedBy: typeof body.proposedBy === "string" && body.proposedBy.trim() ? body.proposedBy.trim() : callerId
+          proposedBy: callerId,
+          origin
         });
         counters.contextRequests += 1;
         publishOps(callerProject, "workflows");
-        logger({ event: "context_state_proposed", project: callerProject, proposalId, proposedBy: callerId });
+        logger({ event: "context_state_proposed", project: callerProject, proposalId, proposedBy: callerId, origin });
         json(response, 201, { proposalId });
         return;
       }
@@ -22556,11 +22581,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 +22691,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 +22754,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.88",
   "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;