@kontextmind/kxm 0.7.91 → 0.7.93

package/plugins/kxm/src/local-snapshot.ts

@@ -56,6 +56,31 @@ export interface LocalMeshSnapshot {
   spend?: Array<{ recordedAt: string; routing: RoutingRecord | RoutingRecordV2 }> | undefined;
 }
 
+/** Limits a snapshot to one project and one recipient.
+ *
+ * `hubProject` is the hub project key stored on legacy messages and runs.
+ * `runtimeProjectId` is the `.kxm/project.yaml` id that keys Runtime runs;
+ * without it the snapshot reads no Runtime runs. `recipientName` selects the
+ * open messages addressed to this agent; without it no messages are read. A
+ * scoped snapshot never reads journal plans. */
+export interface LocalMeshSnapshotScope {
+  hubProject: string;
+  runtimeProjectId?: string | undefined;
+  recipientName?: string | undefined;
+}
+
+export interface LocalMeshSnapshotOptions {
+  env?: NodeJS.ProcessEnv;
+  projectRoot?: string;
+  kxmStateRoot?: string;
+  /** SQLite busy timeout for every database this snapshot opens. Default 5000. */
+  busyTimeoutMs?: number;
+  scope?: LocalMeshSnapshotScope;
+}
+
+const DEFAULT_BUSY_TIMEOUT_MS = 5000;
+const RUNTIME_PROJECT_KEY = /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/;
+
 function processExists(pid: number): boolean {
   try {
     process.kill(pid, 0);
@@ -65,8 +90,8 @@ function processExists(pid: number): boolean {
   }
 }
 
-function readJsonRows<T>(database: DatabaseSync, sql: string): T[] {
-  const rows = database.prepare(sql).all() as Array<{ record: string }>;
+function readJsonRows<T>(database: DatabaseSync, sql: string, params: string[] = []): T[] {
+  const rows = database.prepare(sql).all(...params) as Array<{ record: string }>;
   const out: T[] = [];
   for (const row of rows) {
     try {
@@ -155,12 +180,17 @@ function readPlanMetadata(database: DatabaseSync): MeshTuiPlan[] {
   }
 }
 
-function countRows(database: DatabaseSync, table: "messages" | "workflow_runs", where = ""): number {
-  const row = database.prepare(`SELECT COUNT(*) AS count FROM ${table}${where}`).get() as { count?: number | bigint } | undefined;
+function countRows(database: DatabaseSync, table: "messages" | "workflow_runs", where = "", params: string[] = []): number {
+  const row = database.prepare(`SELECT COUNT(*) AS count FROM ${table}${where}`).get(...params) as { count?: number | bigint } | undefined;
   return Number(row?.count ?? 0);
 }
 
-function readOpenMessageMetadata(database: DatabaseSync): MeshTuiOpenMessage[] {
+const OPEN_MESSAGE_WHERE = " WHERE json_extract(record, '$.status') IN ('queued', 'delivered')";
+const SCOPED_MESSAGE_WHERE = `${OPEN_MESSAGE_WHERE}
+      AND json_extract(record, '$.project') = ?
+      AND COALESCE(json_extract(record, '$.toName'), json_extract(record, '$.to')) = ?`;
+
+function readOpenMessageMetadata(database: DatabaseSync, where = OPEN_MESSAGE_WHERE, params: string[] = []): MeshTuiOpenMessage[] {
   const rows = database.prepare(`
     SELECT
       json_extract(record, '$.id') AS id,
@@ -170,11 +200,10 @@ function readOpenMessageMetadata(database: DatabaseSync): MeshTuiOpenMessage[] {
       json_extract(record, '$.delivery') AS delivery,
       json_extract(record, '$.createdAt') AS createdAt,
       json_extract(record, '$.correlationId') AS correlationId
-    FROM messages
-    WHERE json_extract(record, '$.status') IN ('queued', 'delivered')
+    FROM messages${where}
     ORDER BY json_extract(record, '$.createdAt') DESC
     LIMIT 16
-  `).all() as Array<Record<string, unknown>>;
+  `).all(...params) as Array<Record<string, unknown>>;
   const messages: MeshTuiOpenMessage[] = [];
   for (const row of rows) {
     if (
@@ -236,11 +265,41 @@ function resolveKxmStateRoot(
   return undefined;
 }
 
+function readRuntimeRuns(eventDb: DatabaseSync, projectId: string | undefined): { runs: MeshTuiRun[]; total: number } {
+  const where = projectId === undefined ? "" : " WHERE project_id = ?";
+  const params = projectId === undefined ? [] : [projectId];
+  const runRows = eventDb.prepare(`
+    SELECT run_id, project_id, workflow_id, status, created_at, updated_at
+    FROM runs${where} ORDER BY created_at DESC, run_id DESC LIMIT 8
+  `).all(...params) as Array<{
+    run_id: string;
+    project_id: string;
+    workflow_id: string;
+    status: string;
+    created_at: string;
+    updated_at: string;
+  }>;
+  const countRow = eventDb.prepare(`SELECT COUNT(*) AS total FROM runs${where}`).get(...params) as { total: number } | undefined;
+  return {
+    total: Number(countRow?.total ?? runRows.length),
+    runs: runRows.map((r) => ({
+      id: r.run_id,
+      status: r.status,
+      definitionId: r.workflow_id,
+      project: r.project_id,
+      updatedAt: r.updated_at || r.created_at,
+    })),
+  };
+}
+
 export function loadLocalMeshSnapshot(
   dataPath: string,
   stateDir: string,
-  options?: { env?: NodeJS.ProcessEnv; projectRoot?: string; kxmStateRoot?: string },
+  options?: LocalMeshSnapshotOptions,
 ): LocalMeshSnapshot {
+  const busyTimeoutMs = Math.max(0, Math.trunc(Number(options?.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS)) || 0);
+  const busyTimeout = `PRAGMA busy_timeout = ${busyTimeoutMs}`;
+  const scope = options?.scope;
   let hasLegacy = false;
   let agents: AgentRecord[] = [];
   let openMessages: MeshTuiOpenMessage[] = [];
@@ -252,7 +311,7 @@ export function loadLocalMeshSnapshot(
     hasLegacy = true;
     const database = openReadOnlyDatabase(dataPath);
     try {
-      database.exec("PRAGMA busy_timeout = 5000");
+      database.exec(busyTimeout);
       // Stored rows carry identity only. Presence is derived here against the
       // default lease window, because the hub's configured `staleAfterMs` is
       // not in the file; a reachable hub's own records replace these.
@@ -262,11 +321,24 @@ export function loadLocalMeshSnapshot(
       // `online` boolean is the only durable truth; the hub's /v1/agents or the
       // ops snapshot is the authoritative presence source.
       agents = readJsonRows<AgentIdentity>(database, "SELECT record FROM agents");
-      openMessages = readOpenMessageMetadata(database);
-      openMessageTotal = countRows(database, "messages", " WHERE json_extract(record, '$.status') IN ('queued', 'delivered')");
-      legacyRuns = readJsonRows<WorkflowRun>(database, "SELECT record FROM workflow_runs ORDER BY rowid DESC LIMIT 8");
-      legacyRunTotal = countRows(database, "workflow_runs");
-      plans = readPlanMetadata(database);
+      if (!scope) {
+        openMessages = readOpenMessageMetadata(database);
+        openMessageTotal = countRows(database, "messages", OPEN_MESSAGE_WHERE);
+        legacyRuns = readJsonRows<WorkflowRun>(database, "SELECT record FROM workflow_runs ORDER BY rowid DESC LIMIT 8");
+        legacyRunTotal = countRows(database, "workflow_runs");
+        plans = readPlanMetadata(database);
+      } else {
+        // Scoped: this project's runs and this recipient's open messages only.
+        // Plans stay empty: journal text belongs to other agents' runs.
+        if (scope.recipientName) {
+          const messageParams = [scope.hubProject, scope.recipientName];
+          openMessages = readOpenMessageMetadata(database, SCOPED_MESSAGE_WHERE, messageParams);
+          openMessageTotal = countRows(database, "messages", SCOPED_MESSAGE_WHERE, messageParams);
+        }
+        const runWhere = " WHERE json_extract(record, '$.project') = ?";
+        legacyRuns = readJsonRows<WorkflowRun>(database, `SELECT record FROM workflow_runs${runWhere} ORDER BY rowid DESC LIMIT 8`, [scope.hubProject]);
+        legacyRunTotal = countRows(database, "workflow_runs", runWhere, [scope.hubProject]);
+      }
     } finally {
       database.close();
     }
@@ -276,7 +348,8 @@ export function loadLocalMeshSnapshot(
   let hasKxm = false;
   const kxmRuns: MeshTuiRun[] = [];
   let kxmRunTotal = 0;
-  const kxmStateRoot = resolveKxmStateRoot(stateDir, options);
+  // A scoped snapshot without a Runtime project id reads no Runtime runs.
+  const kxmStateRoot = scope && !scope.runtimeProjectId ? undefined : resolveKxmStateRoot(stateDir, options);
   if (kxmStateRoot) {
     const runtimeDir = join(kxmStateRoot, "runtime");
     const registryDbPath = join(runtimeDir, "registry.db");
@@ -289,8 +362,10 @@ export function loadLocalMeshSnapshot(
       try {
         const regDb = openReadOnlyDatabase(registryDbPath);
         try {
-          regDb.exec("PRAGMA busy_timeout = 5000");
-          const pRows = regDb.prepare("SELECT project_key FROM projects").all() as Array<{ project_key: string }>;
+          regDb.exec(busyTimeout);
+          const pRows = (scope
+            ? regDb.prepare("SELECT project_key FROM projects WHERE project_id = ?").all(scope.runtimeProjectId)
+            : regDb.prepare("SELECT project_key FROM projects").all()) as Array<{ project_key: string }>;
           for (const row of pRows) {
             if (row.project_key) projectKeys.add(row.project_key);
           }
@@ -300,7 +375,9 @@ export function loadLocalMeshSnapshot(
       } catch { /* registry error */ }
     }
 
-    if (existsSync(projectsDir)) {
+    // Scoped: only the registry's key for this project, never every project
+    // directory on the machine.
+    if (!scope && existsSync(projectsDir)) {
       try {
         for (const entry of readdirSync(projectsDir, { withFileTypes: true })) {
           if (entry.isDirectory()) {
@@ -311,35 +388,17 @@ export function loadLocalMeshSnapshot(
     }
 
     for (const key of projectKeys) {
+      if (scope && !RUNTIME_PROJECT_KEY.test(key)) continue;
       const eventDbPath = join(projectsDir, key, "run-events.db");
       if (existsSync(eventDbPath)) {
         hasKxm = true;
         try {
           const eventDb = openReadOnlyDatabase(eventDbPath);
           try {
-            eventDb.exec("PRAGMA busy_timeout = 5000");
-            const runRows = eventDb.prepare(`
-              SELECT run_id, project_id, workflow_id, status, created_at, updated_at
-              FROM runs ORDER BY created_at DESC, run_id DESC LIMIT 8
-            `).all() as Array<{
-              run_id: string;
-              project_id: string;
-              workflow_id: string;
-              status: string;
-              created_at: string;
-              updated_at: string;
-            }>;
-            const countRow = eventDb.prepare("SELECT COUNT(*) AS total FROM runs").get() as { total: number } | undefined;
-            kxmRunTotal += Number(countRow?.total ?? runRows.length);
-            for (const r of runRows) {
-              kxmRuns.push({
-                id: r.run_id,
-                status: r.status,
-                definitionId: r.workflow_id,
-                project: r.project_id,
-                updatedAt: r.updated_at || r.created_at,
-              });
-            }
+            eventDb.exec(busyTimeout);
+            const { runs, total } = readRuntimeRuns(eventDb, scope?.runtimeProjectId);
+            kxmRunTotal += total;
+            kxmRuns.push(...runs);
           } finally {
             eventDb.close();
           }

package/plugins/kxm/src/mcp-server.ts

@@ -1,14 +1,18 @@
+import { statSync } from "node:fs";
+import { join } from "node:path";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { HubClient } from "./client.ts";
-import { resolveClientHubAuthToken } from "./hub-env.ts";
+import { HubClient, HubHttpError } from "./client.ts";
+import { resolveAgentHubAuthToken } from "./hub-env.ts";
 import { defaultProjectName } from "./project-name.ts";
 import { AGENT_COMMANDS_MAP, enforceToolPolicy, getMcpTools, reconcileInbox } from "./commands.ts";
 import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
+import { sessionTokenFixHint } from "./session-token-hint.ts";
 
-const VERSION = "0.7.91";
+const VERSION = "0.7.93";
+const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();
 let meshClient: HubClient | undefined;
@@ -22,11 +26,11 @@ const mcp = new Server(
       tools: {},
     },
     instructions: [
-      'KXM peer requests can arrive as <channel source="kxm" message_id="..."> events.',
-      "Handle the request using normal safety rules, then call kxm_reply with message_id and the final response.",
-      "Use kxm_inbox as a fallback when channel delivery is not enabled.",
-      "For durable workflow requests, call kxm_workflow_get, record material plans/decisions/contradictions/errors/lessons, and pass every checkpoint before replying.",
-      "If work is running in an external system, call kxm_workflow_wait and then kxm_reply so a signed callback can resume the workflow later.",
+      'Peer requests arrive as <channel source="kxm" message_id="..."> events, or in kxm_inbox; handle each under normal safety rules, then call kxm_reply with message_id and the final response.',
+      "For workflow requests, call kxm_workflow_get, record material knowledge with kxm_workflow_record in its ten categories (plan, decision, contradiction, error, lesson, observation, hypothesis, experiment, state-change, skill-candidate), pass the stageId each entry belongs to, and pass every checkpoint before replying.",
+      "For external work, call kxm_workflow_wait, then kxm_reply; a signed callback resumes the run.",
+      "In a KXM project, call kxm_context with your role and task before planning.",
+      "If a KXM tool reports a problem with the hub or token, continue without KXM and tell the user the next step it names.",
     ].join(" "),
   },
 );
@@ -41,6 +45,16 @@ function asRecord(value: unknown): Record<string, unknown> {
     : {};
 }
 
+/** Where this session works and which hub it talks to, read from the launch environment. */
+function sessionIdentity(): { projectDir: string; project: string; serverUrl: string } {
+  const projectDir = process.env.KXM_PROJECT_DIR || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  return {
+    projectDir,
+    project: defaultProjectName(projectDir, process.env),
+    serverUrl: process.env.KXM_SERVER_URL?.trim() || "http://127.0.0.1:7331",
+  };
+}
+
 async function onHubEvent(event: HubEvent): Promise<void> {
   if (event.type === "cancelled" || event.type === "expired") {
     inbox.delete(event.message.id);
@@ -75,28 +89,48 @@ async function onHubEvent(event: HubEvent): Promise<void> {
   });
 }
 
+async function startClient(project: string, serverUrl: string, name: string, authToken: string): Promise<HubClient> {
+  const candidate = new HubClient({
+    serverUrl,
+    name,
+    purpose: process.env.KXM_AGENT_PURPOSE?.trim() || "Claude Code implementation and review agent",
+    project,
+    model: "claude-code",
+    authToken,
+  });
+  try {
+    await candidate.start(onHubEvent);
+    meshClient = candidate;
+    return candidate;
+  } catch (error) {
+    await candidate.stop();
+    throw error;
+  }
+}
+
 async function ensureClient(): Promise<HubClient> {
   if (meshClient?.agent) return meshClient;
   if (starting) return starting;
   starting = (async () => {
-    const projectDir = process.env.KXM_PROJECT_DIR || process.env.CLAUDE_PROJECT_DIR || process.cwd();
-    const project = defaultProjectName(projectDir, process.env);
-    const authToken = resolveClientHubAuthToken(process.env, project);
-    const candidate = new HubClient({
-      serverUrl: process.env.KXM_SERVER_URL?.trim() || "http://127.0.0.1:7331",
-      name: process.env.KXM_AGENT_NAME?.trim() || `claude-${process.pid}`,
-      purpose: process.env.KXM_AGENT_PURPOSE?.trim() || "Claude Code implementation and review agent",
-      project,
-      model: "claude-code",
-      ...(authToken ? { authToken } : {}),
-    });
+    const { project, serverUrl } = sessionIdentity();
+    // An agent session registers with a project token only. The hub admits its admin token
+    // to any project missing from its token map, so no project token fails here, before the
+    // hub is contacted.
+    const authToken = resolveAgentHubAuthToken(process.env, project);
+    if (!authToken) {
+      throw new Error(
+        `KXM has no project token for project ${project} on this machine. Ask the user to set the kxm plugin auth_token (${CONFIGURE_PLUGIN}) or to add ${project} to the hub KXM_PROJECT_TOKENS, listing every existing project too because that variable replaces the saved map.`,
+      );
+    }
+    const name = process.env.KXM_AGENT_NAME?.trim() || `claude-${process.pid}`;
     try {
-      await candidate.start(onHubEvent);
-      meshClient = candidate;
-      return candidate;
+      return await startClient(project, serverUrl, name, authToken);
     } catch (error) {
-      await candidate.stop();
-      throw error;
+      if (!(error instanceof HubHttpError && error.code === "duplicate_agent_name")) throw error;
+      // Another live session in this project holds the name; register beside it once.
+      const substitute = `${name}-${process.pid}`;
+      process.stderr.write(`kxm: agent name ${name} is already active in project ${project}; this session registers as ${substitute}\n`);
+      return await startClient(project, serverUrl, substitute, authToken);
     }
   })();
   try {
@@ -106,6 +140,40 @@ async function ensureClient(): Promise<HubClient> {
   }
 }
 
+/** The reason the hub could not be reached at all, or undefined for any other failure. */
+function unreachableCause(error: unknown): string | undefined {
+  if (!(error instanceof Error)) return undefined;
+  if (error.message.startsWith("request timed out after")) return error.message;
+  const cause = (error as { cause?: unknown }).cause;
+  const causeCode = cause && typeof cause === "object" ? (cause as { code?: unknown }).code : undefined;
+  if (error.message === "fetch failed") {
+    if (typeof causeCode === "string") return causeCode;
+    return cause instanceof Error && cause.message ? cause.message : error.message;
+  }
+  if ((error as NodeJS.ErrnoException).code === "ECONNREFUSED" || error.message.includes("ECONNREFUSED")) return "ECONNREFUSED";
+  return undefined;
+}
+
+async function connectedClient(): Promise<HubClient> {
+  try {
+    return await ensureClient();
+  } catch (error) {
+    const cause = unreachableCause(error);
+    if (!cause) throw error;
+    throw new Error(
+      `KXM hub unreachable at ${sessionIdentity().serverUrl} (${cause}). Ask the user to start the hub (\`kxm hub start\`) or to correct the kxm plugin server_url with ${CONFIGURE_PLUGIN}.`,
+    );
+  }
+}
+
+/** Tool errors are read by the model, so each names the next step and who takes it. */
+function toolErrorText(error: unknown): string {
+  if (error instanceof HubHttpError && error.code === "invalid_auth") {
+    return `KXM hub rejected the project token for project ${sessionIdentity().project}. Ask the user to set the kxm plugin auth_token (${CONFIGURE_PLUGIN}) to that project's token from the hub KXM_PROJECT_TOKENS.`;
+  }
+  return error instanceof Error ? error.message : String(error);
+}
+
 const tools = getMcpTools();
 
 mcp.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
@@ -114,9 +182,11 @@ mcp.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
   try {
     const policy = enforceToolPolicy(request.params.name);
     if (!policy.allowed) {
-      throw new Error(`tool_policy_denied: ${policy.detail ?? policy.error}`);
+      // The denial stays fail closed; the hint only tells the user how to lift it.
+      const hint = sessionTokenFixHint(policy);
+      throw new Error(hint ? `tool_policy_denied: ${policy.detail}. ${hint}` : `tool_policy_denied: ${policy.detail ?? policy.error}`);
     }
-    const client = await ensureClient();
+    const client = await connectedClient();
     const cmd = AGENT_COMMANDS_MAP.get(request.params.name);
     if (!cmd) throw new Error(`unknown tool: ${request.params.name}`);
     const args = asRecord(request.params.arguments);
@@ -124,18 +194,47 @@ mcp.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
     return textResult(result);
   } catch (error) {
     return {
-      content: [{ type: "text" as const, text: error instanceof Error ? error.message : String(error) }],
+      content: [{ type: "text" as const, text: toolErrorText(error) }],
       isError: true,
     };
   }
 });
 
+/** Register before the first tool call, so peers see this session and its requests arrive,
+ * only where a tool call would register anyway: a KXM project with a project token whose tool
+ * policy lets the session receive and answer peer requests. */
+function registersAtStartup(): boolean {
+  const { projectDir, project } = sessionIdentity();
+  try {
+    if (!statSync(join(projectDir, ".kxm")).isDirectory()) return false;
+    if (!resolveAgentHubAuthToken(process.env, project)) return false;
+  } catch {
+    return false;
+  }
+  return enforceToolPolicy("kxm_inbox").allowed && enforceToolPolicy("kxm_reply").allowed;
+}
+
+// Wait for the client's initialized notification: a channel event sent before the handshake
+// completes would be marked delivered while the client could still drop it.
+mcp.oninitialized = () => {
+  if (registersAtStartup()) void ensureClient().catch(() => undefined);
+};
+
 await mcp.connect(new StdioServerTransport());
 
-async function shutdown(): Promise<void> {
-  await meshClient?.stop();
-  await mcp.close();
+let shuttingDown: Promise<void> | undefined;
+
+function shutdown(): Promise<void> {
+  shuttingDown ??= (async () => {
+    const client = meshClient ?? await starting?.catch(() => undefined);
+    await client?.stop();
+    await mcp.close();
+  })();
+  return shuttingDown;
 }
 
 process.once("SIGINT", () => void shutdown());
 process.once("SIGTERM", () => void shutdown());
+// A client that exits without signalling closes stdin. Leave the hub then, so this session is
+// not listed as online and does not hold its agent name against the next session.
+process.stdin.once("end", () => void shutdown());

package/plugins/kxm/src/memory.ts

@@ -323,26 +323,30 @@ export function formatHarnessMemoryBlock(records: MemoryRecord[]): string {
  * carry KXM's words instead of the project's. */
 const HARNESS_INSTRUCTION_FILES = ["AGENTS.md", "CLAUDE.md", "GEMINI.md"] as const;
 
-/** Replace the marker-delimited block, or append one when the file has none. Nothing
- * outside the markers is rewritten. Returns whether the block changed the file; `dryRun`
- * answers without writing. */
-export function updateHarnessDocument(filePath: string, block: string, dryRun = false): boolean {
-  const original = readFileSync(filePath, "utf8");
-  let updated: string;
-  if (original.includes(MEMORY_MARKER_START) && original.includes(MEMORY_MARKER_END)) {
-    const startIdx = original.indexOf(MEMORY_MARKER_START);
-    const endIdx = original.indexOf(MEMORY_MARKER_END) + MEMORY_MARKER_END.length;
-    updated = original.slice(0, startIdx) + block + original.slice(endIdx);
-  } else {
-    const head = original.trimEnd();
-    updated = head ? `${head}\n\n${block}\n` : `${block}\n`;
-  }
+/** What is wrong with the memory markers in `text`, or undefined when it has exactly one
+ * start marker followed by exactly one end marker, or neither. Any other shape has no single
+ * block to replace: an orphan start would make the next sync delete the project's text up to
+ * a later end, an end before its start would duplicate text, and a second block goes stale. */
+function memoryMarkerProblem(text: string): string | undefined {
+  const starts = text.split(MEMORY_MARKER_START).length - 1;
+  const ends = text.split(MEMORY_MARKER_END).length - 1;
+  if (starts > 1 || ends > 1) return `has ${starts} ${MEMORY_MARKER_START} and ${ends} ${MEMORY_MARKER_END} markers, not one block`;
+  if (starts > ends) return `has ${MEMORY_MARKER_START} with no ${MEMORY_MARKER_END}`;
+  if (ends > starts) return `has ${MEMORY_MARKER_END} with no ${MEMORY_MARKER_START}`;
+  if (text.indexOf(MEMORY_MARKER_END) < text.indexOf(MEMORY_MARKER_START)) return `has ${MEMORY_MARKER_END} before ${MEMORY_MARKER_START}`;
+  return undefined;
+}
 
-  if (updated !== original) {
-    if (!dryRun) writeFileSync(filePath, updated, "utf8");
-    return true;
+/** `original` with its memory block replaced, or with one appended when it has no markers.
+ * Nothing outside the markers is rewritten. Markers must already pass `memoryMarkerProblem`. */
+function withMemoryBlock(original: string, block: string): string {
+  const startIdx = original.indexOf(MEMORY_MARKER_START);
+  if (startIdx === -1) {
+    const head = original.trimEnd();
+    return head ? `${head}\n\n${block}\n` : `${block}\n`;
   }
-  return false;
+  const endIdx = original.indexOf(MEMORY_MARKER_END) + MEMORY_MARKER_END.length;
+  return original.slice(0, startIdx) + block + original.slice(endIdx);
 }
 
 export function syncHarnessMemory(
@@ -358,11 +362,30 @@ export function syncHarnessMemory(
     );
   }
 
+  // Check every file before writing any: one malformed file leaves all of them untouched.
+  const documents = present.map((name) => {
+    const original = readFileSync(join(root, name), "utf8");
+    return { name, original, problem: memoryMarkerProblem(original) };
+  });
+  const malformed = documents.filter((doc) => doc.problem !== undefined);
+  if (malformed.length > 0) {
+    throw new Error(
+      `${malformed.map((doc) => `${doc.name} ${doc.problem}`).join("; ")}; wrote no file. `
+        + `Keep exactly one ${MEMORY_MARKER_START} followed by one ${MEMORY_MARKER_END} in each file, or delete both so sync appends a fresh block`,
+    );
+  }
+
   const block = formatHarnessMemoryBlock(loadAuthoredMemory(root));
   const updated: string[] = [];
   const unchanged: string[] = [];
-  for (const name of present) {
-    (updateHarnessDocument(join(root, name), block, options.dryRun) ? updated : unchanged).push(name);
+  for (const { name, original } of documents) {
+    const next = withMemoryBlock(original, block);
+    if (next === original) {
+      unchanged.push(name);
+    } else {
+      if (!options.dryRun) writeFileSync(join(root, name), next, "utf8");
+      updated.push(name);
+    }
   }
   return { updated, unchanged, missing };
 }

package/plugins/kxm/src/project-config.ts

@@ -813,6 +813,29 @@ function validateAgentScope(
   }
 }
 
+/** The outcomes a gate step settles on, by `expect` (computeGateEvidenceOutcome
+ * in runtime-store.ts): nothing else ever reaches a gate step's `on` map. */
+const GATE_STEP_OUTCOMES = {
+  pass: ["passed", "implementation-failure"],
+  fail: ["passed", "repro-missing"],
+} as const satisfies Record<"pass" | "fail", readonly string[]>;
+
+/** A gate step that routes on an outcome it never produces (such as `failed`)
+ * instead of one it does can never settle: the Runtime records the produced
+ * outcome, finds no transition for it, and leaves the attempt unsettled. An
+ * extra dead key next to every produced outcome still settles, and the built-in
+ * template has always declared `failed` beside `implementation-failure`, so only
+ * the combination is refused. Misspellings are gate_outcome_renamed's. */
+function gateOutcomeImpossible(step: JsonObject, stepId: string, file: string): KxmConfigIssue | undefined {
+  const expect = step.expect === "fail" ? "fail" : "pass";
+  const produced: readonly string[] = GATE_STEP_OUTCOMES[expect];
+  const declared = Object.keys(objectValue(step.on) ?? {});
+  const impossible = declared.filter((outcome) => !produced.includes(outcome) && outcome !== "implementation_failure" && outcome !== "repro_missing");
+  const missing = produced.filter((outcome) => !declared.includes(outcome));
+  if (impossible.length === 0 || missing.length === 0) return undefined;
+  return issue("semantic", "gate_outcome_impossible", file, `${stepId} declares ${impossible.join(", ")}, which a gate step with expect ${expect} never produces; it settles on ${produced.join(" or ")}, so declare ${missing.join(" and ")}`);
+}
+
 function transition(value: JsonValue): { target?: string; maxTransitions?: number; terminalStatus?: string } {
   if (typeof value === "string") return { target: value };
   const object = objectValue(value);
@@ -887,6 +910,8 @@ function validateWorkflow(
     if (kind === "gate" && Object.keys(objectValue(step.on) ?? {}).some((outcome) => outcome === "implementation_failure" || outcome === "repro_missing")) {
       issues.push(issue("semantic", "gate_outcome_renamed", file, `${stepId} must use implementation-failure and repro-missing`));
     }
+    const impossibleOutcome = kind === "gate" ? gateOutcomeImpossible(step, stepId, file) : undefined;
+    if (impossibleOutcome) issues.push(impossibleOutcome);
     for (const repositoryId of Object.keys(objectValue(step.repositories) ?? {})) {
       if (!repositories.has(repositoryId)) issues.push(issue("reference", "repository_unknown", file, `${stepId} references unknown repository ${repositoryId}`));
     }

package/plugins/kxm/src/protocol.ts

@@ -149,6 +149,17 @@ export type JournalCategory =
   | "state-change"
   | "skill-candidate";
 export type ImprovementArea = "harness" | "gates" | "implementation" | "workflow" | "documentation" | "security" | "other";
+/** Every improvement area, in report order. The order also breaks ties when
+ * a signal's modal area is ambiguous. */
+export const IMPROVEMENT_AREAS: readonly ImprovementArea[] = [
+  "harness",
+  "gates",
+  "implementation",
+  "workflow",
+  "documentation",
+  "security",
+  "other",
+];
 
 /** Evidence submitted for one checkpoint or external signal, keyed by a
  * requirement from WorkflowStageDefinition.requiredEvidence. */