0xray 4.0.25 → 4.0.26

package/.grok-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "0xray",
-  "version": "4.0.25",
+  "version": "4.0.26",
   "description": "0xRay suit for Grok, Hermes, OpenClaw, OpenCode: mill+inspect, Codex, 7 MCP servers. Costume 45/42 is opt-in foundry, not the default wear.",
   "author": {
     "name": "0xRay AI",

package/.xray/features.json

@@ -1,6 +1,6 @@
 {
   "$schema": "./features.schema.json",
-  "version": "4.0.25",
+  "version": "4.0.26",
   "description": "0xRay Framework - Unified Feature Configuration",
   "suit_temperament": {
     "profile": "auto",

package/dist/CHANGELOG.md

@@ -41,6 +41,22 @@ The format is based on [Conventional Commits](https://www.conventionalcommits.or
 - Archive root `integrations/` costume SKILL dump → `docs/archive/integrations-costume/`. Live wear is `src/integrations`.
 - Archive root `commands/` stale copy → `docs/archive/commands-copy/`. Live wear is `src/opencode/commands`.
 
+## [4.0.26] - 2026-09-25
+
+### 🔄 Changes
+
+### 🐛 Bug Fixes
+- fix: store a lesson when the task matches no signal (e3c75b43d)
+- fix: prove a Cursor compact cut with a session log and per-session receipt (bb3a1c68f)
+- fix: mill check accepts a published version; mcp:status runs (a8bd79e23)
+
+### 🔎 Other Changes
+- Merge pull request #116 from 0xRayAI/cursor/mill-ci-mcp-status-fbe0 (ba94508d2)
+- Merge pull request #120 from 0xRayAI/cursor/lesson-recall-fbe0 (8f4a5a62a)
+- Merge pull request #119 from 0xRayAI/cursor/compact-receipt-proof-fbe0 (a911fd17b)
+
+---
+
 ## [4.0.25] - 2026-09-24
 
 `0xray@4.0.25` ships the plate schematics in the package. `docs-site/docs/plates/` is on the npm `files` list. A worn suit resolves `memory-recall` and `processor` from `dist/integrations/hooks/plates.cjs`.

package/dist/cli/commands/mcp-install.d.ts

@@ -1,3 +1,15 @@
+export type McpInstallerAction = {
+    kind: "list" | "status" | "help";
+} | {
+    kind: "install" | "remove";
+    name?: string;
+} | {
+    kind: "unknown";
+    command: string;
+};
+/** Colon and hyphen forms documented on `npx 0xray` map to the bare dispatcher verbs. */
+export declare function normalizeMcpInstallerToken(command: string | undefined): string | undefined;
+export declare function classifyMcpInstallerArgs(args: readonly string[]): McpInstallerAction;
 export declare function listMCPsCommand(): void;
 export declare function showMCPStatusCommand(): void;
 export declare function installMCPCommand(name: string): Promise<void>;

package/dist/cli/commands/mcp-install.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync } from "fs";
-import { join, dirname } from "path";
+import { join, dirname, resolve } from "path";
 import { execSync } from "child_process";
+import { fileURLToPath } from "url";
 import { getConfigDir } from "../../core/config-paths.js";
 function getMCPConfigPath() {
     return join(process.cwd(), ".xray", "mcp-registry.json");
@@ -186,9 +187,44 @@ function removeMCP(name) {
     saveInstalledMCPs(installed);
     console.log(`\n✅ Removed ${name}`);
 }
+const MCP_INSTALLER_ALIASES = {
+    "mcp:list": "list",
+    "mcp-list": "list",
+    "mcp:status": "status",
+    "mcp-status": "status",
+    "mcp:install": "install",
+    "mcp-install": "install",
+    "mcp:remove": "remove",
+    "mcp-remove": "remove",
+};
+/** Colon and hyphen forms documented on `npx 0xray` map to the bare dispatcher verbs. */
+export function normalizeMcpInstallerToken(command) {
+    if (command === undefined)
+        return undefined;
+    return MCP_INSTALLER_ALIASES[command] ?? command;
+}
+export function classifyMcpInstallerArgs(args) {
+    const raw = args[0];
+    const command = normalizeMcpInstallerToken(raw);
+    if (command === undefined || command === "status")
+        return { kind: "status" };
+    if (command === "list")
+        return { kind: "list" };
+    if (command === "help" || command === "--help" || command === "-h")
+        return { kind: "help" };
+    if (command === "install" || command === "remove") {
+        const name = args[1];
+        return name === undefined ? { kind: command } : { kind: command, name };
+    }
+    return { kind: "unknown", command: raw ?? command };
+}
+const isDirectRun = process.argv[1] !== undefined &&
+    resolve(process.argv[1]) === fileURLToPath(import.meta.url);
 async function main() {
+    if (!isDirectRun)
+        return;
     const args = process.argv.slice(2);
-    const command = args[0];
+    const command = normalizeMcpInstallerToken(args[0]);
     switch (command) {
         case "list":
             listMCPs();

package/dist/integrations/cursor/README.md

@@ -40,7 +40,9 @@ Do **not** prove window pressure with UTF-8 chars÷4. `src/integrations/cursor/h
 | `cursor-cloud` `run-info` / `get-events` / dashboard (model, bc-id, window) | yes — token MISS is honest |
 | chars÷4, fill-only, `fillBytes` | **forbidden** (`ok: false`) |
 
-Host `preCompact` fire is counted from `.xray/state/cursor-hook-invoke.log` (`event=preCompact`). Do not hand-invoke `pre-compact.js` to mint that Y.
+Host `preCompact` fire is counted from `.xray/state/cursor-hook-invoke.log` (`event=preCompact`). Do not hand-invoke `pre-compact.js` to mint that Y. That invoke log has no session id.
+
+A cut counts only when `.xray/state/cursor-receipts/<sessionId>.json` exists **and** `.xray/state/cursor-hook.log` contains a line with that same session id (timestamp, `context_tokens`, `context_usage_percent`, `context_window_size`, `generation_id`). `probeLogExists` is true only when that append succeeded. `.xray/state/cursor-usage-receipt.json` and `cursor-precompact.json` keep only the newest event. That single latest json is not enough — the next arm overwrites it.
 
 Arm S landscape + receipt: `examples/killer-dual/`.
 

package/dist/integrations/cursor/hooks/cursor-hook-utils.js

@@ -53,6 +53,11 @@ export {
   FORBIDDEN_USAGE_METHODS,
   invokeProbeLogPath,
   cursorUsageReceiptPath,
+  cursorHookLogPath,
+  sanitizeSessionReceiptId,
+  cursorSessionReceiptPath,
+  appendCursorCompactProofLog,
+  writeCursorSessionReceipt,
   parseInvokeProbeLog,
   hostUsageFromPreCompactEvent,
   classifyUsageCite,

package/dist/integrations/cursor/hooks/cursor-usage-receipt.js

@@ -28,6 +28,70 @@ export function cursorUsageReceiptPath(root) {
   return path.join(root, '.xray', 'state', 'cursor-usage-receipt.json');
 }
 
+/** Proof log. A cut is greppable here; cursor-hook-invoke.log has no session id. */
+export function cursorHookLogPath(root) {
+  return path.join(root, '.xray', 'state', 'cursor-hook.log');
+}
+
+function logToken(value) {
+  if (value == null) return '';
+  return String(value).replace(/[\r\n]+/g, '');
+}
+
+/**
+ * Safe filename segment for `.xray/state/cursor-receipts/<id>.json`.
+ * Empty when the id cannot be kept inside that directory.
+ */
+export function sanitizeSessionReceiptId(sessionId) {
+  const raw = typeof sessionId === 'string' ? sessionId.trim() : '';
+  if (!raw) return '';
+  const safe = raw
+    .replace(/\0/g, '')
+    .replace(/[/\\]/g, '_')
+    .replace(/\.\./g, '_')
+    .replace(/[^A-Za-z0-9._-]+/g, '_')
+    .replace(/^[._]+/, '')
+    .replace(/[._]+$/g, '');
+  if (!safe || safe === '.' || safe === '..') return '';
+  return safe.slice(0, 180);
+}
+
+export function cursorSessionReceiptPath(root, sessionId) {
+  const safe = sanitizeSessionReceiptId(sessionId);
+  if (!safe) return null;
+  return path.join(root, '.xray', 'state', 'cursor-receipts', `${safe}.json`);
+}
+
+/**
+ * Append one preCompact proof line. True only when the append landed and
+ * the file contains that session id (grep of *.log can find the cut).
+ */
+export function appendCursorCompactProofLog(root, fields = {}) {
+  const sessionId = logToken(fields.sessionId);
+  const timestamp = logToken(fields.timestamp) || new Date().toISOString();
+  const line = [
+    `ts=${timestamp}`,
+    `session_id=${sessionId}`,
+    `context_tokens=${logToken(fields.context_tokens)}`,
+    `context_usage_percent=${logToken(fields.context_usage_percent)}`,
+    `context_window_size=${logToken(fields.context_window_size)}`,
+    `generation_id=${logToken(fields.generation_id)}`,
+  ].join(' ');
+  const dest = cursorHookLogPath(root);
+  try {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.appendFileSync(dest, `${line}\n`);
+  } catch {
+    return false;
+  }
+  if (!sessionId) return false;
+  try {
+    return fs.readFileSync(dest, 'utf8').includes(`session_id=${sessionId}`);
+  } catch {
+    return false;
+  }
+}
+
 export function parseInvokeProbeLog(root) {
   const dest = invokeProbeLogPath(root);
   const counts = { preToolUse: 0, preCompact: 0, afterFileEdit: 0, unknown: 0 };
@@ -228,7 +292,7 @@ export function buildCursorUsageReceipt(root, input = {}) {
       preToolUseCount: probe.counts.preToolUse,
       afterFileEditCount: probe.counts.afterFileEdit,
       eventClass,
-      probeLogExists: probe.exists,
+      probeLogExists: input.probeLogExists === true,
     },
     usage,
     repertoire,
@@ -299,3 +363,32 @@ export function writeCursorUsageReceipt(root, input = {}) {
     return null;
   }
 }
+
+/**
+ * Per-session copy of the latest precompact + usage receipts.
+ * The next arm overwrites cursor-precompact.json and cursor-usage-receipt.json.
+ */
+export function writeCursorSessionReceipt(root, sessionId, paths = {}) {
+  const dest = cursorSessionReceiptPath(root, sessionId);
+  if (!dest) return null;
+  if (!paths.precompactPath && !paths.usagePath) return null;
+  try {
+    const payload = {
+      sessionId: typeof sessionId === 'string' ? sessionId : null,
+      precompact: null,
+      usage: null,
+    };
+    if (paths.precompactPath && fs.existsSync(paths.precompactPath)) {
+      payload.precompact = JSON.parse(fs.readFileSync(paths.precompactPath, 'utf8'));
+    }
+    if (paths.usagePath && fs.existsSync(paths.usagePath)) {
+      payload.usage = JSON.parse(fs.readFileSync(paths.usagePath, 'utf8'));
+    }
+    if (!payload.precompact && !payload.usage) return null;
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, JSON.stringify(payload, null, 2));
+    return dest;
+  } catch {
+    return null;
+  }
+}

package/dist/integrations/cursor/hooks/pre-compact.js

@@ -18,7 +18,9 @@ import {
   writeSessionBoot,
 } from './cursor-hook-utils.js';
 import {
+  appendCursorCompactProofLog,
   hostUsageFromPreCompactEvent,
+  writeCursorSessionReceipt,
   writeCursorUsageReceipt,
 } from './cursor-usage-receipt.js';
 
@@ -132,6 +134,17 @@ async function main() {
       });
       bootPath = writeSessionBoot(root, payload);
       stationLine = payload.stationLine;
+      const stampedAt = new Date().toISOString();
+      const proofLogged = appendCursorCompactProofLog(root, {
+        sessionId,
+        timestamp: stampedAt,
+        context_tokens: typeof event.context_tokens === 'number' ? event.context_tokens : null,
+        context_usage_percent:
+          typeof event.context_usage_percent === 'number' ? event.context_usage_percent : null,
+        context_window_size:
+          typeof event.context_window_size === 'number' ? event.context_window_size : null,
+        generation_id: generationId,
+      });
       receiptPath = writeCursorPrecompactReceipt(root, {
         event_class: eventClass,
         hookEvent: 'pre_compact',
@@ -145,13 +158,18 @@ async function main() {
         messages_to_compact:
           typeof event.messages_to_compact === 'number' ? event.messages_to_compact : null,
         bootPath,
-        timestamp: new Date().toISOString(),
+        timestamp: stampedAt,
       });
       usagePath = writeCursorUsageReceipt(root, {
         eventClass,
         sessionId,
+        probeLogExists: proofLogged,
         usage: hostUsageFromPreCompactEvent(event),
       });
+      writeCursorSessionReceipt(root, sessionId, {
+        precompactPath: receiptPath,
+        usagePath,
+      });
       if (plates) {
         try {
           const named = plates.recallPlate(payload.intent || intent || '');

package/dist/integrations/openclaw/plugin/xray-pre-tool/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xray-pre-tool",
-  "version": "4.0.25",
+  "version": "4.0.26",
   "private": true,
   "type": "module",
   "description": "0xRay constitution + temperament PreToolUse for OpenClaw",

package/dist/memory-routing/record-lesson.d.ts

@@ -4,13 +4,18 @@ export interface LessonInput {
     taskId: string;
     assignedAgent: string;
     sessionId: string;
-    /** Signals the finished task already named. When set, text matching is not used. */
+    /**
+     * Signals the finished task already named. When set, text matching is not used.
+     * An empty list with a lesson still stores that lesson under a name taken from the task.
+     */
     signals?: string[];
     /** Approaches, solutions, or the wrong turn from the sessions that named the law. */
     lesson?: string;
 }
 /**
  * A finished task names the signals its text actually matched and says
- * whether the outcome was good. That is the one-tenth step. No match, no write.
+ * whether the outcome was good. That is the one-tenth step.
+ * A lesson with no matched signal is stored under a hyphenated name from the
+ * task, so the same task text recalls it. No lesson and no match, no write.
  */
 export declare function recordLesson(input: LessonInput): string[];

package/dist/memory-routing/record-lesson.js

@@ -1,14 +1,48 @@
 import { ensureMemoryRoutingProviderSync } from "./provider-registry.js";
+/**
+ * Hyphenated phrase whose spaced form is still inside the task.
+ * A later routing read of that same task hits the name.
+ */
+function signalNameForUnmatchedLesson(task) {
+    const words = task
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((word) => word.length >= 3);
+    const normalized = task.toLowerCase();
+    const kept = [];
+    for (const word of words) {
+        const next = [...kept, word];
+        const phrase = next.join(" ");
+        const hyphen = next.join("-");
+        if (!normalized.includes(phrase) || hyphen.length > 120)
+            break;
+        kept.push(word);
+    }
+    if (kept.length === 0)
+        return null;
+    return kept.join("-");
+}
 /**
  * A finished task names the signals its text actually matched and says
- * whether the outcome was good. That is the one-tenth step. No match, no write.
+ * whether the outcome was good. That is the one-tenth step.
+ * A lesson with no matched signal is stored under a hyphenated name from the
+ * task, so the same task text recalls it. No lesson and no match, no write.
  */
 export function recordLesson(input) {
     const provider = ensureMemoryRoutingProviderSync();
     if (provider.id === "null" || !provider.ingestFeedback)
         return [];
-    const named = input.signals ?? provider.buildRoutingContext(input.operation).matchedSignals;
-    const names = [...new Set(named.filter((name) => name.length > 0))];
+    const lesson = (input.lesson ?? "").trim();
+    const supplied = input.signals;
+    const named = supplied !== undefined
+        ? supplied
+        : provider.buildRoutingContext(input.operation).matchedSignals;
+    let names = [...new Set(named.filter((name) => name.length > 0))];
+    if (names.length === 0 && lesson.length > 0) {
+        const coined = signalNameForUnmatchedLesson(input.operation);
+        if (coined)
+            names = [coined];
+    }
     if (names.length === 0)
         return [];
     provider.ingestFeedback({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "0xray",
-  "version": "4.0.25",
+  "version": "4.0.26",
   "description": "Multi-agent orchestration and Codex governance for OpenCode, Hermes, Grok Build, and OpenClaw",
   "readme": "README.md",
   "license": "MIT",

package/scripts/foundry/reconcile-version.mjs

@@ -11,7 +11,9 @@
  *   npx @0xray/foundry reconcile patch --apply
  *
  * --apply writes package.json and the package-lock.json version fields.
- * --check fails when the lock does not match package.json.
+ * --check passes when package.json is equal to the registry (already published)
+ * or greater (the pre-publish bump). It fails when package.json is behind npm,
+ * or when the lock does not match package.json.
  */
 
 import { execSync } from "child_process";
@@ -91,6 +93,21 @@ function fail(msg) {
   process.exit(1);
 }
 
+/**
+ * Registry gate for --check.
+ * Equal to npm is a shipped release. Greater is the pre-publish bump.
+ * Only a package.json behind the registry fails.
+ * @param {string} local
+ * @param {string} npmVersion
+ * @returns {string | null}
+ */
+export function publishedVersionCheckError(local, npmVersion) {
+  if (compare(local, npmVersion) < 0) {
+    return `package.json (${local}) must be >= npm (${npmVersion}). Run: npx @0xray/foundry reconcile patch --apply`;
+  }
+  return null;
+}
+
 function main() {
   const local = readLocalVersion();
   const npm = readPublishedVersion();
@@ -138,9 +155,12 @@ function main() {
     return;
   }
 
-  // Strict checks for release gate / pre-tag
-  if (compare(local, npm) <= 0) {
-    fail(`package.json (${local}) must be > npm (${npm}). Run: npx @0xray/foundry reconcile patch --apply`);
+  // Strict checks for release gate / pre-tag.
+  // `local` is the version read before --apply. Apply still writes
+  // bumpVersion(max(npm, tag)) and is not this gate.
+  const behindNpm = publishedVersionCheckError(local, npm);
+  if (behindNpm) {
+    fail(behindNpm);
   }
 
   const pkgVersion = readLocalVersion();

package/src/integrations/openclaw/plugin/xray-pre-tool/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xray-pre-tool",
-  "version": "4.0.25",
+  "version": "4.0.26",
   "private": true,
   "type": "module",
   "description": "0xRay constitution + temperament PreToolUse for OpenClaw",

package/xray/features.json

@@ -1,6 +1,6 @@
 {
   "$schema": "./features.schema.json",
-  "version": "4.0.25",
+  "version": "4.0.26",
   "description": "0xRay Framework - Unified Feature Configuration",
   "suit_temperament": {
     "profile": "auto",