0xray 3.4.6 → 3.4.8

package/.xray/config.json

@@ -1,6 +1,5 @@
 {
   "$schema": "./config.schema.json",
-  "version": "3.1.0",
   "description": "0xRay Framework - Token Management & Performance Configuration",
   "token_management": {
     "maxPromptTokens": 20000,

package/AGENTS-consumer.md

@@ -1,8 +1,10 @@
 # 0xRay AI Agents
 
+<!-- 0xray-managed -->
+
 Quick reference for the 0xRay AI orchestration framework (shipped to your project on `npm install 0xray`).
 
-**v3.4.6** — 7 MCP servers · 45 skills · 68 codex terms · 4 platform bridges
+**v3.4.8** — 7 MCP servers · 45 skills · 68 codex terms · 4 platform bridges
 
 ## Postinstall (automatic)
 

package/AGENTS.md

@@ -1,6 +1,6 @@
 # xray Agents
 
-Quick reference for the xray AI orchestration framework (**v3.4.6**).
+Quick reference for the xray AI orchestration framework (**v3.4.8**).
 
 **42 agents** · **45 skills** · **7 consumer MCP servers** · **68 codex terms** · **3,226 tests**
 

package/README.md

@@ -1,6 +1,6 @@
 # xray — MCP-Centric AI Governance OS
 
-**v3.4.6** — 42 agents · 45 skills · 7 MCP servers · 68 codex terms · 3,226 tests
+**v3.4.8** — 42 agents · 45 skills · 7 MCP servers · 68 codex terms · 3,226 tests
 
 xray is the pure v2 three-subsystem AI orchestration framework — **MCP-centric**, governed by Dynamo, and autonomous via thinDispatch. Consumer `npm install 0xray` auto-wires all four platform bridges and seven MCP servers with zero manual config.
 

package/SKILLS.md

@@ -1,6 +1,6 @@
 # 0xray Skills
 
-**v3.4.6** — **45 skills** · invoked via `xray-skills` MCP · synced on postinstall
+**v3.4.8** — **45 skills** · invoked via `xray-skills` MCP · synced on postinstall
 
 xray ships 45 knowledge skills (`src/skills/<name>/SKILL.md`) across the full software lifecycle. Lead-dev operating model lives in **`orchestrator`** skill + `multi_agent_orchestration.lead_dev_mode` in features.json. Skills load on demand via the **xray-skills** MCP server (`npx -y 0xray mcp skills`), agent `@mentions`, or platform skill directories after postinstall.
 

package/dist/AGENTS.md

@@ -1,6 +1,6 @@
 # xray Agents
 
-Quick reference for the xray AI orchestration framework (**v3.4.6**).
+Quick reference for the xray AI orchestration framework (**v3.4.8**).
 
 **42 agents** · **45 skills** · **7 consumer MCP servers** · **68 codex terms** · **3,226 tests**
 

package/dist/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Conventional Commits](https://www.conventionalcommits.org/).
 
+## [3.4.8] - 2026-06-19
+
+### 🐛 Bug Fixes
+- **Hermes v2 OAuth** — governance LLM voters read `providers.xai-oauth.tokens` from `~/.hermes/auth.json` (npm consumers on modern Hermes no longer abstain)
+- **Headless deliberation** — honor `XRAY_GOVERNANCE_IN_PROCESS=1` for in-process skill voters without MCP subprocesses
+- **Governance MCP HTTP** — per-session Streamable HTTP transports on Railway
+
+### ✅ Tests
+- Unit coverage for Hermes v2 auth parsing and `XRAY_GOVERNANCE_IN_PROCESS` governance path
+
+---
+
+## [3.4.7] - 2026-06-18
+
+### 🐛 Bug Fixes
+- **Release gate upgrade smoke** — `consumer-install-smoke` simulates consumer opt-in merge on every publish
+- **Release pipeline** — artifacts sync before gate; idempotent `npm publish`; tag after publish
+- **Postinstall** — skip customized `AGENTS.md`; hard-fail on bridge wiring errors
+- **pre-publish-guard** — allow `.xray/config.json` and `.xray/state/` runtime dirt between gate steps
+
+---
+
 ## [3.4.6] - 2026-06-18
 
 ### 🐛 Bug Fixes

package/dist/README.md

@@ -1,6 +1,6 @@
 # xray — MCP-Centric AI Governance OS
 
-**v3.4.6** — 42 agents · 45 skills · 7 MCP servers · 68 codex terms · 3,226 tests
+**v3.4.8** — 42 agents · 45 skills · 7 MCP servers · 68 codex terms · 3,226 tests
 
 xray is the pure v2 three-subsystem AI orchestration framework — **MCP-centric**, governed by Dynamo, and autonomous via thinDispatch. Consumer `npm install 0xray` auto-wires all four platform bridges and seven MCP servers with zero manual config.
 

package/dist/SKILLS.md

@@ -1,6 +1,6 @@
 # 0xray Skills
 
-**v3.4.6** — **45 skills** · invoked via `xray-skills` MCP · synced on postinstall
+**v3.4.8** — **45 skills** · invoked via `xray-skills` MCP · synced on postinstall
 
 xray ships 45 knowledge skills (`src/skills/<name>/SKILL.md`) across the full software lifecycle. Lead-dev operating model lives in **`orchestrator`** skill + `multi_agent_orchestration.lead_dev_mode` in features.json. Skills load on demand via the **xray-skills** MCP server (`npx -y 0xray mcp skills`), agent `@mentions`, or platform skill directories after postinstall.
 

package/dist/governance/governance-service.js

@@ -128,7 +128,9 @@ export class GovernanceService {
     }
     async callSkillServer(serverName, proposals, context) {
         const votes = [];
-        const useInProcess = process.env.VERCEL === '1' || !!process.env.RAILWAY_ENVIRONMENT;
+        const useInProcess = process.env.VERCEL === '1' ||
+            !!process.env.RAILWAY_ENVIRONMENT ||
+            process.env.XRAY_GOVERNANCE_IN_PROCESS === '1';
         for (const proposal of proposals) {
             try {
                 let text = '';

package/dist/governance/llm-governance-provider.js

@@ -42,6 +42,71 @@ DECISION: approve|reject|abstain
 CONFIDENCE: <0.0-1.0>
 REASONING: <2-4 sentence analysis of the proposal's broader project impact>`,
 };
+function resolveHermesExpiresAt(provider, tokens) {
+    if (typeof provider.expires_at === "number")
+        return provider.expires_at;
+    const expiresIn = tokens?.expires_in ?? provider.expires_in;
+    if (typeof expiresIn !== "number")
+        return undefined;
+    const refreshCandidates = [provider.last_refresh, tokens?.last_refresh];
+    for (const lastRefresh of refreshCandidates) {
+        if (typeof lastRefresh !== "string")
+            continue;
+        const base = Date.parse(lastRefresh);
+        if (!Number.isNaN(base)) {
+            return Math.floor((base + expiresIn * 1000) / 1000);
+        }
+    }
+    return undefined;
+}
+function extractHermesOAuthEntry(data) {
+    if (!data || typeof data !== "object")
+        return undefined;
+    if (Array.isArray(data)) {
+        return data.find((e) => e.provider === "xai-oauth" || !!e.access_token);
+    }
+    const record = data;
+    const legacy = record["xai-oauth"];
+    if (legacy && typeof legacy === "object") {
+        const entry = legacy;
+        if (entry.access_token)
+            return entry;
+    }
+    if (typeof record.access_token === "string") {
+        return record;
+    }
+    for (const bucket of ["providers", "credential_pool"]) {
+        const pool = record[bucket];
+        if (!pool || typeof pool !== "object")
+            continue;
+        const provider = pool["xai-oauth"];
+        if (!provider || typeof provider !== "object")
+            continue;
+        const prov = provider;
+        const tokens = prov.tokens && typeof prov.tokens === "object"
+            ? prov.tokens
+            : undefined;
+        if (tokens && typeof tokens.access_token === "string") {
+            const entry = {
+                access_token: tokens.access_token,
+                provider: "xai-oauth",
+            };
+            if (typeof tokens.refresh_token === "string") {
+                entry.refresh_token = tokens.refresh_token;
+            }
+            const expiresAt = resolveHermesExpiresAt(prov, tokens);
+            if (expiresAt !== undefined)
+                entry.expires_at = expiresAt;
+            if (typeof tokens.token_type === "string")
+                entry.token_type = tokens.token_type;
+            return entry;
+        }
+        if (typeof prov.access_token === "string") {
+            return prov;
+        }
+    }
+    return undefined;
+}
 function readHermesOAuthToken() {
     try {
         const authPath = join(homedir(), ".hermes", "auth.json");
@@ -49,16 +114,7 @@ function readHermesOAuthToken() {
             return null;
         const raw = readFileSync(authPath, "utf-8");
         const data = JSON.parse(raw);
-        let entry;
-        if (data && typeof data === "object" && !Array.isArray(data)) {
-            entry = data["xai-oauth"];
-            if (!entry?.access_token && data.access_token) {
-                entry = data;
-            }
-        }
-        if (!entry?.access_token && Array.isArray(data)) {
-            entry = data.find((e) => e.provider === "xai-oauth" || !!e.access_token);
-        }
+        const entry = extractHermesOAuthEntry(data);
         if (!entry?.access_token) {
             process.stderr.write("[llm] readHermesOAuthToken: no access_token in auth file\n");
             return null;

package/dist/mcps/governance.server.d.ts

@@ -29,6 +29,7 @@ declare class GovernanceServer extends XrayKnowledgeSkillBase {
     connect(transport: Transport): Promise<void>;
     /**
      * Run as HTTP server using Streamable HTTP transport (for Grok CLI compatibility).
+     * Uses per-session transports so concurrent clients can each initialize independently.
      */
     runHttp(port?: number): Promise<void>;
 }

package/dist/mcps/governance.server.js

@@ -13,7 +13,7 @@
  */
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
-import { CallToolRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, isInitializeRequest, } from "@modelcontextprotocol/sdk/types.js";
 import { XrayKnowledgeSkillBase } from "./shared/knowledge-skill-base.js";
 import { frameworkLogger } from "../core/framework-logger.js";
 import { featuresConfigLoader } from "../core/features-config.js";
@@ -351,6 +351,7 @@ class GovernanceServer extends XrayKnowledgeSkillBase {
     }
     /**
      * Run as HTTP server using Streamable HTTP transport (for Grok CLI compatibility).
+     * Uses per-session transports so concurrent clients can each initialize independently.
      */
     async runHttp(port = parseInt(process.env.MCP_PORT ?? "3100", 10)) {
         await this.initializeGovernance();
@@ -360,10 +361,7 @@ class GovernanceServer extends XrayKnowledgeSkillBase {
             host: mcpHost,
             ...(allowedHosts ? { allowedHosts } : {}),
         });
-        const transport = new StreamableHTTPServerTransport({
-            sessionIdGenerator: () => randomUUID(),
-        });
-        await this.server.connect(transport);
+        const transports = {};
         const apiKey = process.env.GOVERNANCE_API_KEY;
         if (apiKey) {
             frameworkLogger.log("governance-mcp", "api-key-auth-enabled", "info", {});
@@ -383,8 +381,45 @@ class GovernanceServer extends XrayKnowledgeSkillBase {
             }
             next();
         });
-        app.post("/mcp", async (req, res) => {
+        const mcpPostHandler = async (req, res) => {
             try {
+                const sessionId = req.headers["mcp-session-id"];
+                let transport;
+                if (sessionId && transports[sessionId]) {
+                    transport = transports[sessionId];
+                }
+                else if (!sessionId && isInitializeRequest(req.body)) {
+                    transport = new StreamableHTTPServerTransport({
+                        sessionIdGenerator: () => randomUUID(),
+                        onsessioninitialized: (sid) => {
+                            if (transport) {
+                                transports[sid] = transport;
+                                frameworkLogger.log("governance-mcp", "session-initialized", "info", {
+                                    sessionId: sid,
+                                });
+                            }
+                        },
+                    });
+                    transport.onclose = () => {
+                        const sid = transport?.sessionId;
+                        if (sid && transports[sid]) {
+                            delete transports[sid];
+                            frameworkLogger.log("governance-mcp", "session-closed", "info", { sessionId: sid });
+                        }
+                    };
+                    const sessionServer = new GovernanceServer();
+                    await sessionServer.connect(transport);
+                    await transport.handleRequest(req, res, req.body);
+                    return;
+                }
+                else {
+                    res.status(400).json({
+                        jsonrpc: "2.0",
+                        error: { code: -32000, message: "Bad Request: No valid session ID provided" },
+                        id: null,
+                    });
+                    return;
+                }
                 await transport.handleRequest(req, res, req.body);
             }
             catch (error) {
@@ -393,15 +428,51 @@ class GovernanceServer extends XrayKnowledgeSkillBase {
                     res.status(500).json({ jsonrpc: "2.0", error: { code: -32603, message: "Internal error" }, id: null });
                 }
             }
+        };
+        app.post("/mcp", mcpPostHandler);
+        app.get("/mcp", async (req, res) => {
+            const sessionId = req.headers["mcp-session-id"];
+            if (!sessionId || !transports[sessionId]) {
+                res.status(400).send("Invalid or missing session ID");
+                return;
+            }
+            try {
+                await transports[sessionId].handleRequest(req, res);
+            }
+            catch (error) {
+                frameworkLogger.log("governance-mcp", "http-sse-error", "error", { error: String(error) });
+                if (!res.headersSent) {
+                    res.status(500).send("Error processing SSE stream");
+                }
+            }
+        });
+        app.delete("/mcp", async (req, res) => {
+            const sessionId = req.headers["mcp-session-id"];
+            if (!sessionId || !transports[sessionId]) {
+                res.status(400).send("Invalid or missing session ID");
+                return;
+            }
+            try {
+                await transports[sessionId].handleRequest(req, res);
+            }
+            catch (error) {
+                frameworkLogger.log("governance-mcp", "http-delete-error", "error", { error: String(error) });
+                if (!res.headersSent) {
+                    res.status(500).send("Error processing session termination");
+                }
+            }
         });
         app.get("/health", (_req, res) => {
             res.json({ status: "ok", server: "governance" });
         });
+        const closeAllTransports = async () => {
+            await Promise.all(Object.values(transports).map((t) => t.close()));
+        };
         app.listen(port, () => {
             frameworkLogger.log("governance-mcp", "http-listening", "info", { port });
         });
-        process.on("SIGINT", () => { transport.close(); process.exit(0); });
-        process.on("SIGTERM", () => { transport.close(); process.exit(0); });
+        process.on("SIGINT", () => { void closeAllTransports().then(() => process.exit(0)); });
+        process.on("SIGTERM", () => { void closeAllTransports().then(() => process.exit(0)); });
     }
 }
 // Start the server if this file is run directly

package/package.json

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

package/scripts/node/consumer-install-smoke.mjs

@@ -3,6 +3,7 @@
  * consumer-install-smoke.mjs — Clean-room pack + install verification.
  *
  * Simulates what consumers receive from npm without publishing.
+ * Runs fresh install checks + upgrade merge simulation.
  *
  * Usage:
  *   node scripts/node/consumer-install-smoke.mjs
@@ -38,6 +39,85 @@ function run(cmd, cwd, { inherit = false } = {}) {
   return inherit ? "" : String(result).trim();
 }
 
+function assertFreshInstallDefaults(tmpRoot, version) {
+  const consumerFeaturesPath = path.join(tmpRoot, ".xray", "features.json");
+  if (!fs.existsSync(consumerFeaturesPath)) {
+    throw new Error(".xray/features.json not deployed to consumer project by postinstall");
+  }
+  const features = JSON.parse(fs.readFileSync(consumerFeaturesPath, "utf-8"));
+  if (!features.memory_routing) {
+    throw new Error("Deployed features.json missing memory_routing block");
+  }
+  if (features.memory_routing.enabled !== false) {
+    throw new Error(
+      `Fresh install must default memory_routing.enabled=false (got ${features.memory_routing.enabled})`,
+    );
+  }
+  if (!features.inference_governance) {
+    throw new Error("Deployed features.json missing inference_governance block");
+  }
+  if (features.inference_governance.enabled !== false) {
+    throw new Error("Fresh install must default inference_governance.enabled=false");
+  }
+  console.log("  ✅ .xray/features.json fresh-install defaults (opt-in off)");
+  return { consumerFeaturesPath, features };
+}
+
+function runUpgradeMergeSmoke(tmpRoot, nmRoot, version) {
+  console.log("\n📋 Upgrade merge smoke (consumer opt-ins preserved)...");
+
+  const { deployXrayConfig } = require(path.join(nmRoot, "scripts/node/install-bridges.cjs"));
+  const consumerFeaturesPath = path.join(tmpRoot, ".xray", "features.json");
+
+  fs.writeFileSync(
+    consumerFeaturesPath,
+    `${JSON.stringify(
+      {
+        version: "3.4.0",
+        memory_routing: {
+          enabled: true,
+          provider: "repertoire",
+          module_path: "dist/provider/memory-routing-provider.js",
+        },
+        inference_governance: { enabled: true },
+        consumer_custom_block: { kept: true },
+      },
+      null,
+      2,
+    )}\n`,
+  );
+
+  const shippedTemplate = JSON.parse(
+    fs.readFileSync(path.join(nmRoot, "xray/features.json"), "utf-8"),
+  );
+  const shippedMarker = shippedTemplate.token_optimization ? "token_optimization" : null;
+
+  deployXrayConfig(tmpRoot, nmRoot, () => {});
+
+  const merged = JSON.parse(fs.readFileSync(consumerFeaturesPath, "utf-8"));
+
+  if (merged.memory_routing?.enabled !== true) {
+    throw new Error(`Upgrade merge lost memory_routing.enabled (got ${merged.memory_routing?.enabled})`);
+  }
+  if (merged.memory_routing?.provider !== "repertoire") {
+    throw new Error(`Upgrade merge lost memory_routing.provider (got ${merged.memory_routing?.provider})`);
+  }
+  if (merged.inference_governance?.enabled !== true) {
+    throw new Error("Upgrade merge lost inference_governance.enabled");
+  }
+  if (merged.consumer_custom_block?.kept !== true) {
+    throw new Error("Upgrade merge dropped consumer-only keys");
+  }
+  if (merged.version !== version) {
+    throw new Error(`Upgrade merge version: expected ${version}, got ${merged.version}`);
+  }
+  if (shippedMarker && !merged[shippedMarker]) {
+    throw new Error(`Upgrade merge missing shipped template key: ${shippedMarker}`);
+  }
+
+  console.log("  ✅ upgrade merge preserves opt-ins + bumps features.version");
+}
+
 function main() {
   console.log("\n=== Consumer Install Smoke ===\n");
 
@@ -94,7 +174,7 @@ function main() {
     }
 
     const bridges = require(path.join(nmRoot, "scripts/node/install-bridges.cjs"));
-    for (const exp of ["installAllBridges", "resolveConsumerTargetDir", "isConsumerInstall"]) {
+    for (const exp of ["installAllBridges", "resolveConsumerTargetDir", "isConsumerInstall", "deployXrayConfig"]) {
       if (typeof bridges[exp] !== "function") {
         throw new Error(`install-bridges missing export: ${exp}`);
       }
@@ -106,7 +186,6 @@ function main() {
     }
     console.log("  ✅ consumer target resolution");
 
-    // Postinstall should have run; verify .mcp.json merge
     const mcpPath = path.join(tmpRoot, ".mcp.json");
     if (!fs.existsSync(mcpPath)) {
       throw new Error(".mcp.json not created by postinstall");
@@ -124,26 +203,7 @@ function main() {
     }
     console.log(`  ✅ .mcp.json has ${XRAY_MCP_NAMES.length} npx MCP servers`);
 
-    const consumerFeaturesPath = path.join(tmpRoot, ".xray", "features.json");
-    if (!fs.existsSync(consumerFeaturesPath)) {
-      throw new Error(".xray/features.json not deployed to consumer project by postinstall");
-    }
-    const features = JSON.parse(fs.readFileSync(consumerFeaturesPath, "utf-8"));
-    if (!features.memory_routing) {
-      throw new Error("Deployed features.json missing memory_routing block");
-    }
-    if (features.memory_routing.enabled !== false) {
-      throw new Error(
-        `Shipped template must default memory_routing.enabled=false (got ${features.memory_routing.enabled})`,
-      );
-    }
-    if (!features.inference_governance) {
-      throw new Error("Deployed features.json missing inference_governance block");
-    }
-    if (features.inference_governance.enabled !== false) {
-      throw new Error("Shipped template must default inference_governance.enabled=false");
-    }
-    console.log("  ✅ .xray/features.json deployed (memory_routing + inference_governance opt-in defaults)");
+    assertFreshInstallDefaults(tmpRoot, version);
 
     const schemaInPackage = path.join(nmRoot, "xray", "features.schema.json");
     if (!fs.existsSync(schemaInPackage)) {
@@ -151,6 +211,8 @@ function main() {
     }
     console.log("  ✅ xray/features.schema.json in package");
 
+    runUpgradeMergeSmoke(tmpRoot, nmRoot, version);
+
     console.log("\n✅ Consumer install smoke passed\n");
   } catch (err) {
     console.error(`\n❌ Consumer smoke failed: ${err.message}\n`);

package/scripts/node/postinstall.cjs

@@ -19,11 +19,24 @@ const targetDir = resolveConsumerTargetDir(packageRoot, process.env.PWD || proce
 const resolvedPackage = path.resolve(packageRoot);
 const resolvedTarget = path.resolve(targetDir);
 
-// Copy AGENTS-consumer.md → AGENTS.md
+const XRAY_MANAGED_AGENTS_MARKER = "<!-- 0xray-managed -->";
+
+// Copy AGENTS-consumer.md → AGENTS.md (only if absent or still 0xray-managed)
 const agentsConsumer = path.join(packageRoot, "AGENTS-consumer.md");
 const agentsDest = path.join(targetDir, "AGENTS.md");
 if (fs.existsSync(agentsConsumer) && isConsumerInstall(resolvedPackage, resolvedTarget)) {
-  fs.copyFileSync(agentsConsumer, agentsDest);
+  const shouldDeployAgents =
+    !fs.existsSync(agentsDest) ||
+    fs.readFileSync(agentsDest, "utf8").includes(XRAY_MANAGED_AGENTS_MARKER);
+  if (shouldDeployAgents) {
+    let content = fs.readFileSync(agentsConsumer, "utf8");
+    if (!content.includes(XRAY_MANAGED_AGENTS_MARKER)) {
+      content = `${content.trimEnd()}\n\n${XRAY_MANAGED_AGENTS_MARKER}\n`;
+    }
+    fs.writeFileSync(agentsDest, content);
+  } else {
+    structuredLog("postinstall", "Skipped AGENTS.md (consumer-customized)", "info");
+  }
 }
 
 // Copy .gitignore.default → .gitignore (never overwrite existing)
@@ -43,7 +56,9 @@ if (isConsumerInstall(resolvedPackage, resolvedTarget)) {
       log: structuredLog,
     });
   } catch (e) {
-    structuredLog("postinstall", "Bridge install failed", "warn", { error: e.message });
+    structuredLog("postinstall", "Bridge install failed", "error", { error: e.message });
+    console.error("\n❌ 0xRay postinstall failed — bridge wiring did not complete.\n");
+    process.exit(1);
   }
 
   structuredLog(

package/scripts/node/pre-publish-guard.js

@@ -67,6 +67,8 @@ const ARTIFACT_PREFIXES = [
   '.opencode/activity-report.json',
   '.opencode/init.sh',
   '.xray/inference/',
+  '.xray/config.json',
+  '.xray/state/',
   'logs/',
   'backups/',
   '.ci-reports/',

package/scripts/node/release-gate.mjs

@@ -3,8 +3,8 @@
  * release-gate.mjs — Single release checkpoint.
  *
  * Modes:
- *   (default)     build + test + consumer smoke — run once before commit
- *   --verify-only git + reconcile + release docs + consumer smoke — after push, before tag
+ *   (default)     build + test + consumer smoke (fresh + upgrade merge)
+ *   --verify-only git + reconcile + release docs + consumer smoke — after push, before publish
  *   --skip-smoke  skip consumer install smoke
  *   --skip-docs   skip release docs validation (not recommended for publish)
  *
@@ -36,21 +36,26 @@ function main() {
 
   try {
     if (verifyOnly) {
-      step("1/4 Git + reconcile", "node scripts/node/pre-publish-guard.js --verify-only");
+      step("1/5 Git + reconcile", "node scripts/node/pre-publish-guard.js --verify-only");
       if (!skipDocs) {
-        step("2/4 Release docs", "node scripts/node/validate-release-docs.mjs");
+        step("2/5 Release docs", "node scripts/node/validate-release-docs.mjs");
       }
+      step(
+        "3/5 Plugin infrastructure",
+        "node scripts/test/validate-plugins-e2e.cjs --structural-only",
+      );
       if (!skipSmoke) {
-        step("3/4 Consumer install smoke", "node scripts/node/consumer-install-smoke.mjs");
+        step("4/5 Consumer install smoke", "node scripts/node/consumer-install-smoke.mjs");
       }
     } else {
-      step("1/4 Build", "npm run build");
-      step("2/4 Tests", "npm test");
+      step("1/5 Build", "npm run build");
+      step("2/5 Tests", "npm test");
+      step(
+        "3/5 Plugin infrastructure",
+        "node scripts/test/validate-plugins-e2e.cjs --structural-only",
+      );
       if (!skipSmoke) {
-        step("3/4 Consumer install smoke", "node scripts/node/consumer-install-smoke.mjs");
-      }
-      if (!skipDocs && process.argv.includes("--with-docs")) {
-        step("4/4 Release docs", "node scripts/node/validate-release-docs.mjs");
+        step("4/5 Consumer install smoke (fresh + upgrade)", "node scripts/node/consumer-install-smoke.mjs");
       }
     }
 

package/scripts/node/release.mjs

@@ -4,16 +4,15 @@
  * Canonical 0xRay release script.
  *
  * 1. Bump version from npm registry baseline (reconcile-version)
- * 2. Release gate once (build + test + consumer smoke)
- * 3. Update CHANGELOG / README / AGENTS / docs (version-manager --artifacts-only)
+ * 2. Release artifacts (CHANGELOG / README / AGENTS / docs) — before gate so docs tests pass
+ * 3. Release gate (build + test + consumer smoke)
  * 4. Commit release artifacts → push
  * 5. Verify gate (reconcile + git + release docs + smoke)
- * 6. Tag → push tag → npm publish
+ * 6. npm publish (idempotent — skip if version already on registry)
+ * 7. Tag → push tag (only after successful publish)
  *
  * Usage:
  *   npm run release:patch
- *   npm run release:minor
- *   npm run release:major
  *   node scripts/node/release.mjs patch --dry-run
  */
 
@@ -44,6 +43,32 @@ function currentBranch() {
   return execSync("git rev-parse --abbrev-ref HEAD", { cwd: rootDir, encoding: "utf-8" }).trim();
 }
 
+function npmVersionPublished(version) {
+  try {
+    const out = execSync(`npm view 0xray@${version} version`, {
+      cwd: rootDir,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    return out === version;
+  } catch {
+    return false;
+  }
+}
+
+function publishIdempotent(version) {
+  if (dryRun) {
+    console.log(`  would: npm publish --access public (check 0xray@${version} first)`);
+    return;
+  }
+  if (npmVersionPublished(version)) {
+    console.log(`ℹ️  0xray@${version} already on npm — skipping publish`);
+    return;
+  }
+  execSync("npm publish --access public", { cwd: rootDir, stdio: "inherit", encoding: "utf-8" });
+  console.log(`✅ Published 0xray@${version}`);
+}
+
 async function main() {
   if (!["major", "minor", "patch"].includes(releaseType)) {
     console.error("Usage: node scripts/node/release.mjs [patch|minor|major] [--dry-run]");
@@ -70,14 +95,14 @@ async function main() {
     : readVersion();
   console.log(`📌 Release version: ${newVersion}`);
 
-  // 2. Single gate before commit
-  console.log("\n📦 Step 2: Release gate (build + test + smoke)");
-  run("node scripts/node/release-gate.mjs", "release gate");
-
-  // 3. Changelog + doc artifacts
-  console.log("\n📦 Step 3: Release artifacts (CHANGELOG, README, AGENTS, docs)");
+  // 2. Artifacts BEFORE gate (docs vitest matches package.json version)
+  console.log("\n📦 Step 2: Release artifacts (CHANGELOG, README, AGENTS, docs)");
   run("node scripts/node/version-manager.mjs --artifacts-only", "release artifacts");
 
+  // 3. Gate
+  console.log("\n📦 Step 3: Release gate (build + test + smoke)");
+  run("node scripts/node/release-gate.mjs", "release gate");
+
   // 4. Commit + push
   console.log("\n📦 Step 4: Commit & push");
   const releaseFiles = getReleaseArtifactPaths();
@@ -97,24 +122,33 @@ async function main() {
   const branch = currentBranch();
   run(`git push origin ${branch}`, "git push");
 
-  // 5. Post-push verify before tag
-  console.log("\n📦 Step 5: Verify gate (reconcile + git + smoke)");
+  // 5. Post-push verify before publish
+  console.log("\n📦 Step 5: Verify gate (reconcile + git + docs + smoke)");
   run("node scripts/node/release-gate.mjs --verify-only", "verify gate");
 
-  // 6. Tag
-  console.log("\n📦 Step 6: Tag");
+  // 6. Publish (idempotent)
+  console.log("\n📦 Step 6: npm publish");
+  publishIdempotent(newVersion);
+
+  // 7. Tag after publish
+  console.log("\n📦 Step 7: Tag");
   if (!dryRun) {
-    execSync(`git tag -a v${newVersion} -m "Release v${newVersion}"`, { cwd: rootDir, stdio: "inherit" });
-    console.log(`✅ Created tag v${newVersion}`);
+    try {
+      execSync(`git tag -a v${newVersion} -m "Release v${newVersion}"`, { cwd: rootDir, stdio: "inherit" });
+      console.log(`✅ Created tag v${newVersion}`);
+    } catch (e) {
+      const msg = String(e.stderr || e.message || "");
+      if (msg.includes("already exists")) {
+        console.log(`ℹ️  Tag v${newVersion} already exists`);
+      } else {
+        throw e;
+      }
+    }
   } else {
     console.log(`  would: git tag -a v${newVersion}`);
   }
   run(`git push origin v${newVersion}`, "push tag");
 
-  // 7. Publish
-  console.log("\n📦 Step 7: npm publish");
-  run("npm publish --access public", "npm publish");
-
   console.log("\n╔════════════════════════════════════════════════════════╗");
   console.log("║        ✅ Release Complete!                            ║");
   console.log("╚════════════════════════════════════════════════════════╝");
@@ -125,7 +159,7 @@ async function main() {
       fs.mkdirSync(path.join(rootDir, "tweets"), { recursive: true });
       fs.writeFileSync(
         tweetPath,
-        `🎉 0xRay v${newVersion} is LIVE - {THEME}!\n...\n\`\`\`\nnpm install 0xray@latest\n\`\`\`\n`,
+        `🎉 0xRay v${newVersion} is LIVE - consumer-safe upgrades!\n...\n\`\`\`\nnpm install 0xray@latest\n\`\`\`\n`,
       );
       console.log(`📝 Tweet template: tweets/v${newVersion}.md`);
     }

package/src/mcps/governance.server.ts

@@ -18,6 +18,7 @@ import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import {
   CallToolRequestSchema,
+  isInitializeRequest,
   type CallToolResult,
 } from "@modelcontextprotocol/sdk/types.js";
 import { XrayKnowledgeSkillBase } from "./shared/knowledge-skill-base.js";
@@ -419,6 +420,7 @@ class GovernanceServer extends XrayKnowledgeSkillBase {
 
   /**
    * Run as HTTP server using Streamable HTTP transport (for Grok CLI compatibility).
+   * Uses per-session transports so concurrent clients can each initialize independently.
    */
   async runHttp(port: number = parseInt(process.env.MCP_PORT ?? "3100", 10)): Promise<void> {
     await this.initializeGovernance();
@@ -429,11 +431,7 @@ class GovernanceServer extends XrayKnowledgeSkillBase {
       host: mcpHost,
       ...(allowedHosts ? { allowedHosts } : {}),
     });
-    const transport = new StreamableHTTPServerTransport({
-      sessionIdGenerator: () => randomUUID(),
-    });
-
-    await this.server.connect(transport as any);
+    const transports: Record<string, StreamableHTTPServerTransport> = {};
 
     const apiKey = process.env.GOVERNANCE_API_KEY;
     if (apiKey) {
@@ -455,8 +453,45 @@ class GovernanceServer extends XrayKnowledgeSkillBase {
       next();
     });
 
-    app.post("/mcp", async (req: any, res: any) => {
+    const mcpPostHandler = async (req: any, res: any) => {
       try {
+        const sessionId = req.headers["mcp-session-id"] as string | undefined;
+        let transport: StreamableHTTPServerTransport | undefined;
+
+        if (sessionId && transports[sessionId]) {
+          transport = transports[sessionId];
+        } else if (!sessionId && isInitializeRequest(req.body)) {
+          transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+            onsessioninitialized: (sid) => {
+              if (transport) {
+                transports[sid] = transport;
+                frameworkLogger.log("governance-mcp", "session-initialized", "info", {
+                  sessionId: sid,
+                });
+              }
+            },
+          });
+          transport.onclose = () => {
+            const sid = transport?.sessionId;
+            if (sid && transports[sid]) {
+              delete transports[sid];
+              frameworkLogger.log("governance-mcp", "session-closed", "info", { sessionId: sid });
+            }
+          };
+          const sessionServer = new GovernanceServer();
+          await sessionServer.connect(transport as Transport);
+          await transport.handleRequest(req, res, req.body);
+          return;
+        } else {
+          res.status(400).json({
+            jsonrpc: "2.0",
+            error: { code: -32000, message: "Bad Request: No valid session ID provided" },
+            id: null,
+          });
+          return;
+        }
+
         await transport.handleRequest(req, res, req.body);
       } catch (error) {
         frameworkLogger.log("governance-mcp", "http-handler-error", "error", { error: String(error) });
@@ -464,18 +499,56 @@ class GovernanceServer extends XrayKnowledgeSkillBase {
           res.status(500).json({ jsonrpc: "2.0", error: { code: -32603, message: "Internal error" }, id: null });
         }
       }
+    };
+
+    app.post("/mcp", mcpPostHandler);
+
+    app.get("/mcp", async (req: any, res: any) => {
+      const sessionId = req.headers["mcp-session-id"] as string | undefined;
+      if (!sessionId || !transports[sessionId]) {
+        res.status(400).send("Invalid or missing session ID");
+        return;
+      }
+      try {
+        await transports[sessionId].handleRequest(req, res);
+      } catch (error) {
+        frameworkLogger.log("governance-mcp", "http-sse-error", "error", { error: String(error) });
+        if (!res.headersSent) {
+          res.status(500).send("Error processing SSE stream");
+        }
+      }
+    });
+
+    app.delete("/mcp", async (req: any, res: any) => {
+      const sessionId = req.headers["mcp-session-id"] as string | undefined;
+      if (!sessionId || !transports[sessionId]) {
+        res.status(400).send("Invalid or missing session ID");
+        return;
+      }
+      try {
+        await transports[sessionId].handleRequest(req, res);
+      } catch (error) {
+        frameworkLogger.log("governance-mcp", "http-delete-error", "error", { error: String(error) });
+        if (!res.headersSent) {
+          res.status(500).send("Error processing session termination");
+        }
+      }
     });
 
     app.get("/health", (_req: any, res: any) => {
       res.json({ status: "ok", server: "governance" });
     });
 
+    const closeAllTransports = async () => {
+      await Promise.all(Object.values(transports).map((t) => t.close()));
+    };
+
     app.listen(port, () => {
       frameworkLogger.log("governance-mcp", "http-listening", "info", { port });
     });
 
-    process.on("SIGINT", () => { transport.close(); process.exit(0); });
-    process.on("SIGTERM", () => { transport.close(); process.exit(0); });
+    process.on("SIGINT", () => { void closeAllTransports().then(() => process.exit(0)); });
+    process.on("SIGTERM", () => { void closeAllTransports().then(() => process.exit(0)); });
   }
 }