@kontextmind/kxm 0.7.92 → 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.92";
+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/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. */

package/plugins/kxm/src/relevance.ts

@@ -0,0 +1,138 @@
+import type { ContextItem } from "./context.ts";
+
+/**
+ * Deterministic lexical relevance (BM25) for context ranking and recall.
+ *
+ * No model, no clock, no randomness: the same query and documents always
+ * produce bit-identical scores, so arbiter packets and recall results stay
+ * reproducible and testable.
+ */
+
+/** Words that carry no task signal. Dropped before scoring. */
+export const RELEVANCE_STOPWORDS: ReadonlySet<string> = Object.freeze(new Set([
+  "a", "an", "and", "are", "as", "at", "be", "been", "but", "by", "can", "could",
+  "did", "do", "does", "for", "from", "had", "has", "have", "how", "if", "in",
+  "into", "is", "it", "its", "of", "on", "or", "our", "should", "so", "than",
+  "that", "the", "their", "them", "then", "there", "these", "they", "this",
+  "those", "to", "was", "we", "were", "what", "when", "where", "which", "while",
+  "who", "why", "will", "with", "would", "you", "your",
+]));
+
+/** BM25 term-frequency saturation. */
+export const RELEVANCE_K1 = 1.2;
+/** BM25 document-length normalization. */
+export const RELEVANCE_B = 0.75;
+
+const MIN_TOKEN_CHARS = 2;
+const MAX_TOKEN_CHARS = 64;
+
+function foldPlural(token: string): string {
+  if (/^\p{N}+$/u.test(token)) return token;
+  if (token.length > 4 && token.endsWith("ies")) return `${token.slice(0, -3)}y`;
+  if (token.length > 4 && token.endsWith("sses")) return token.slice(0, -2);
+  if (
+    token.length > 3
+    && token.endsWith("s")
+    && !token.endsWith("ss")
+    && !token.endsWith("us")
+    && !token.endsWith("is")
+  ) {
+    return token.slice(0, -1);
+  }
+  return token;
+}
+
+/** NFKC-normalized, lowercased, stopword-free, plural-folded tokens in text
+ * order, duplicates kept. */
+export function relevanceTokens(text: string): string[] {
+  const tokens: string[] = [];
+  for (const raw of text.normalize("NFKC").toLowerCase().split(/[^\p{L}\p{N}]+/u)) {
+    if (raw.length < MIN_TOKEN_CHARS || raw.length > MAX_TOKEN_CHARS) continue;
+    if (RELEVANCE_STOPWORDS.has(raw)) continue;
+    tokens.push(foldPlural(raw));
+  }
+  return tokens;
+}
+
+/** Index-aligned BM25 scores of each document against the query. Terms are
+ * summed in first-occurrence query order so the float result is bit-stable. */
+export function scoreRelevance(query: string, documents: readonly string[]): number[] {
+  const scores = documents.map(() => 0);
+  const terms = [...new Set(relevanceTokens(query))];
+  if (terms.length === 0 || documents.length === 0) return scores;
+
+  const indexed = documents.map((document) => {
+    const tokens = relevanceTokens(document);
+    const frequencies = new Map<string, number>();
+    for (const token of tokens) frequencies.set(token, (frequencies.get(token) ?? 0) + 1);
+    return { length: tokens.length, frequencies };
+  });
+  const count = indexed.length;
+  let totalLength = 0;
+  for (const document of indexed) totalLength += document.length;
+  const averageLength = totalLength > 0 ? totalLength / count : 1;
+
+  const inverseFrequency = new Map<string, number>();
+  for (const term of terms) {
+    let documentFrequency = 0;
+    for (const document of indexed) {
+      if (document.frequencies.has(term)) documentFrequency += 1;
+    }
+    inverseFrequency.set(term, Math.log(1 + (count - documentFrequency + 0.5) / (documentFrequency + 0.5)));
+  }
+
+  indexed.forEach((document, index) => {
+    let score = 0;
+    for (const term of terms) {
+      const frequency = document.frequencies.get(term) ?? 0;
+      if (frequency === 0) continue;
+      const lengthNorm = 1 - RELEVANCE_B + RELEVANCE_B * (document.length / averageLength);
+      score += inverseFrequency.get(term)! * ((frequency * (RELEVANCE_K1 + 1)) / (frequency + RELEVANCE_K1 * lengthNorm));
+    }
+    scores[index] = score;
+  });
+  return scores;
+}
+
+/** Relevance rounded to three decimals for audits and responses. */
+export function roundRelevance(score: number): number {
+  return Math.round(score * 1000) / 1000;
+}
+
+/** The text a context item is ranked on: its summary plus its state key.
+ * Kind, id and sourceRef are excluded. */
+export function contextItemRelevanceText(item: ContextItem): string {
+  return item.stateKey !== undefined ? `${item.summary} ${item.stateKey}` : item.summary;
+}
+
+/** Locale-independent code-unit order for identifiers. */
+export function compareCodeUnitIds(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+export interface RankedRecallItem {
+  item: ContextItem;
+  relevance: number;
+}
+
+/** Rank recall candidates: exact-phrase hits first, then BM25 any-token hits,
+ * then id. An empty query is a phrase hit for every item (id order). Items
+ * that neither contain the phrase nor share a token are dropped. */
+export function rankRecall(query: string, items: readonly ContextItem[], limit: number): RankedRecallItem[] {
+  const needle = query.toLowerCase();
+  const scores = scoreRelevance(query, items.map(contextItemRelevanceText));
+  const ranked: { item: ContextItem; score: number; phraseHit: boolean }[] = [];
+  items.forEach((item, index) => {
+    const score = scores[index] ?? 0;
+    const phraseHit = needle === ""
+      || item.summary.toLowerCase().includes(needle)
+      || (item.stateKey ?? "").toLowerCase().includes(needle);
+    if (phraseHit || score > 0) ranked.push({ item, score, phraseHit });
+  });
+  ranked.sort((left, right) =>
+    (right.phraseHit ? 1 : 0) - (left.phraseHit ? 1 : 0)
+    || right.score - left.score
+    || compareCodeUnitIds(left.item.id, right.item.id),
+  );
+  return ranked.slice(0, limit).map(({ item, score }) => ({ item, relevance: roundRelevance(score) }));
+}