0xray 3.4.1 → 3.4.3

package/dist/utils/token-manager.d.ts

@@ -0,0 +1,48 @@
+export interface TokenLimits {
+    maxPromptTokens: number;
+    warningThreshold: number;
+    modelLimits: Record<string, number>;
+}
+export interface ContextPruningConfig {
+    enabled: boolean;
+    aggressivePruning: boolean;
+    preserveCriticalContext: boolean;
+}
+export declare class TokenManager {
+    private config;
+    constructor(configPath?: string);
+    private loadConfig;
+    /**
+     * Estimate token count for text (rough approximation)
+     * Uses 4 characters per token as a conservative estimate
+     */
+    estimateTokens(text: string): number;
+    /**
+     * Check if prompt exceeds limits
+     */
+    checkLimits(prompt: string, modelName?: string): {
+        withinLimit: boolean;
+        currentTokens: number;
+        maxTokens: number;
+        needsPruning: boolean;
+        warning: boolean;
+    };
+    /**
+     * Prune context to fit within token limits
+     */
+    pruneContext(context: string, targetTokens?: number): string;
+    private extractCriticalSections;
+    private extractSection;
+    private extractNonCriticalContent;
+    private pruneNonCriticalContent;
+    /**
+     * Generate warning message for token limits
+     */
+    generateWarning(limitCheck: ReturnType<TokenManager["checkLimits"]>): string;
+    /**
+     * Get current configuration
+     */
+    getConfig(): TokenLimits & {
+        contextPruning: ContextPruningConfig;
+    };
+}

package/dist/validation/agent-config-validator.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Agent Configuration Validator
+ *
+ * Validates agent configuration files for correctness and completeness
+ * ensuring all required fields are present and properly formatted.
+ *
+ * @since 2026-01-23
+ */
+export interface AgentConfig {
+    name: string;
+    description: string;
+    version: string;
+    model: string;
+    mode: "primary" | "subagent";
+    logging?: {
+        level: string;
+        format: string;
+        destinations: string[];
+        retention_days?: number;
+        sensitive_data_filtering?: boolean;
+        audit_trail?: boolean;
+    };
+    processor_pipeline?: Array<{
+        name: string;
+        type: string;
+        priority: "low" | "medium" | "high" | "critical";
+        timeout_ms?: number;
+        retry_attempts?: number;
+    }>;
+    capabilities?: string[];
+    error_handling?: {
+        retry_attempts?: number;
+        circuit_breaker?: {
+            enabled?: boolean;
+            failure_threshold?: number;
+            recovery_timeout_ms?: number;
+        };
+        fallback_strategy?: string;
+        alert_on_failure?: boolean;
+    };
+    performance?: {
+        timeout_ms?: number;
+        concurrency_limit?: number;
+        memory_limit_mb?: number;
+        cpu_limit_percent?: number;
+    };
+    security?: {
+        sandboxed_execution?: boolean;
+        permission_level?: string;
+        data_classification?: string;
+        encryption_required?: boolean;
+    };
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+    config: AgentConfig | null;
+}
+export declare class AgentConfigValidator {
+    private readonly requiredFields;
+    private readonly validModes;
+    private readonly validLogLevels;
+    private readonly validLogFormats;
+    private readonly validPriorities;
+    private readonly validProcessorTypes;
+    /**
+     * Validate agent configuration from file
+     */
+    validateConfigFile(filePath: string): Promise<ValidationResult>;
+    /**
+     * Validate agent configuration object
+     */
+    validateConfig(config: AgentConfig): ValidationResult;
+    /**
+     * Validate logging configuration
+     */
+    private validateLoggingConfig;
+    /**
+     * Validate processor pipeline configuration
+     */
+    private validateProcessorPipeline;
+    /**
+     * Validate performance configuration
+     */
+    private validatePerformanceConfig;
+    /**
+     * Validate security configuration
+     */
+    private validateSecurityConfig;
+    /**
+     * Validate error handling configuration
+     */
+    private validateErrorHandlingConfig;
+    /**
+     * Validate all agent configurations in a directory
+     */
+    validateAllAgentConfigs(agentConfigDir?: string): Promise<{
+        results: Array<{
+            file: string;
+            result: ValidationResult;
+        }>;
+        summary: {
+            total: number;
+            valid: number;
+            invalid: number;
+        };
+    }>;
+}
+export declare const agentConfigValidator: AgentConfigValidator;

package/dist/validation/estimation-validator.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Estimation Validator
+ *
+ * Tracks estimates vs. actuals and provides calibrated estimates
+ * Prevents the "always estimate high" syndrome by learning from history
+ */
+/**
+ * Estimation Validator
+ * Tracks estimates and learns from actuals to improve future predictions
+ */
+export declare class EstimationValidator {
+    private estimations;
+    private calibrations;
+    private readonly STORAGE_KEY;
+    constructor();
+    /**
+     * Start tracking an estimate
+     */
+    startEstimate(taskId: string, description: string, category: string, estimatedMinutes: number, confidence?: 'high' | 'medium' | 'low'): void;
+    /**
+     * Complete tracking and record actual time
+     */
+    completeEstimate(taskId: string): void;
+    /**
+     * Get calibrated estimate based on historical data
+     */
+    getCalibratedEstimate(category: string, baseEstimate: number, confidence?: 'high' | 'medium' | 'low'): {
+        calibratedEstimate: number;
+        calibrationFactor: number;
+        confidence: number;
+    };
+    /**
+     * Check if an estimate needs adjustment
+     */
+    validateEstimate(category: string, estimate: number): {
+        isReasonable: boolean;
+        suggestedEstimate: number;
+        warning?: string;
+    };
+    /**
+     * Get estimation accuracy report
+     */
+    getAccuracyReport(): {
+        overallAccuracy: number;
+        categoryBreakdown: Array<{
+            category: string;
+            sampleSize: number;
+            avgRatio: number;
+            trend: 'over' | 'under' | 'accurate';
+        }>;
+        recommendations: string[];
+    };
+    private updateCalibration;
+    private loadFromStorage;
+    private saveToStorage;
+}
+export declare function getEstimationValidator(): EstimationValidator;
+/**
+ * Decorator for async functions to track estimates
+ */
+export declare function trackEstimate(taskId: string, description: string, category: string, estimatedMinutes: number): (_target: unknown, _propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;

package/dist/validation/orchestration-flow-validator.d.ts

@@ -0,0 +1,87 @@
+/**
+ * COMPREHENSIVE ORCHESTRATION FLOW VALIDATION SUITE
+ * Validates the complete end-to-end orchestration pipeline
+ */
+interface TestResult {
+    testName: string;
+    success: boolean;
+    duration: number;
+    error?: string;
+    metrics: {
+        agentsSpawned: number;
+        agentsCompleted: number;
+        agentsFailed: number;
+        dependenciesResolved: number;
+        monitoringUpdates: number;
+    };
+    validationSteps: ValidationStep[];
+}
+interface ValidationStep {
+    step: string;
+    success: boolean;
+    timestamp: number;
+    details?: unknown;
+}
+declare class OrchestrationFlowValidator {
+    private orchestrator;
+    private stateManager;
+    private agentDelegator;
+    private testResults;
+    constructor();
+    /**
+     * SIMULATION 1: Basic Orchestration Flow
+     * Tests the fundamental orchestration pipeline
+     */
+    testBasicOrchestrationFlow(): Promise<TestResult>;
+    /**
+     * SIMULATION 2: Dependency Management Flow
+     * Tests complex task dependencies and sequencing
+     */
+    testDependencyManagementFlow(): Promise<TestResult>;
+    /**
+     * SIMULATION 3: Error Handling & Recovery Flow
+     * Tests system resilience and fallback mechanisms
+     */
+    testErrorHandlingFlow(): Promise<TestResult>;
+    /**
+     * SIMULATION 4: Performance & Scalability Flow
+     * Tests system performance under load
+     */
+    testPerformanceFlow(): Promise<TestResult>;
+    /**
+     * SIMULATION 5: Monitoring & Cleanup Flow
+     * Tests the complete monitoring and cleanup lifecycle
+     */
+    testMonitoringCleanupFlow(): Promise<TestResult>;
+    /**
+     * Run all orchestration flow validations
+     */
+    runCompleteValidationSuite(): Promise<ValidationSuiteResults>;
+    /**
+     * Generate comprehensive validation report
+     */
+    private generateValidationReport;
+    /**
+     * Generate recommendations based on test results
+     */
+    private generateRecommendations;
+}
+interface ValidationSuiteResults {
+    summary: {
+        totalTests: number;
+        passedTests: number;
+        failedTests: number;
+        successRate: number;
+        totalDuration: number;
+        avgDuration: number;
+    };
+    metrics: {
+        totalAgentsSpawned: number;
+        totalAgentsCompleted: number;
+        totalDependenciesResolved: number;
+        totalMonitoringUpdates: number;
+    };
+    testResults: TestResult[];
+    recommendations: string[];
+}
+export { OrchestrationFlowValidator };

package/dist/validation/report-content-validator.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Report Content Validator
+ * Reads and analyzes full report content to detect hidden errors and inconsistencies
+ */
+export declare class ReportContentValidator {
+    private reportPatterns;
+    /**
+     * Validate full report content for hidden errors
+     */
+    validateReportContent(reportPath: string, reportType: "session" | "framework" | "validation" | "simulation"): Promise<{
+        valid: boolean;
+        issues: string[];
+        summary: {
+            errorCount: number;
+            warningCount: number;
+            falsePositiveCount: number;
+            inconsistencyCount: number;
+            riskLevel: "low" | "medium" | "high" | "critical";
+        };
+        details: {
+            criticalErrors: string[];
+            warnings: string[];
+            falsePositives: string[];
+            inconsistencies: string[];
+        };
+    }>;
+    private validateReportTypeSpecific;
+    private createValidationResult;
+    /**
+     * Get validation patterns for debugging
+     */
+    getValidationPatterns(): {
+        criticalErrors: RegExp[];
+        warnings: RegExp[];
+        falsePositives: RegExp[];
+        inconsistencies: RegExp[];
+    };
+    /**
+     * Add custom validation pattern
+     */
+    addValidationPattern(category: keyof typeof this.reportPatterns, pattern: RegExp): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "0xray",
-  "version": "3.4.1",
+  "version": "3.4.3",
   "description": "Multi-agent orchestration and Codex governance for OpenCode, Hermes, Grok Build, and OpenClaw",
   "readme": "README.md",
   "license": "MIT",
@@ -55,12 +55,16 @@
     "plugin": "./dist/plugin/xray-codex-injection.js",
     "mcps": "./dist/mcps/"
   },
+  "xray": {
+    "dist": "dist",
+    "mcpServersPath": "dist/mcps"
+  },
   "scripts": {
-    "prepublishOnly": "npm run prepare-consumer && npm run build:all && find dist -name '*.d.ts' -o -name '*.d.ts.map' -o -name '*.js.map' | xargs rm -f",
+    "prepublishOnly": "node scripts/node/reconcile-version.mjs --check && npm run prepare-consumer && npm run build:all && find dist -name '*.js.map' -o -name '*.d.ts.map' | xargs rm -f 2>/dev/null || true",
     "version:bump": "node scripts/node/version-manager.mjs",
     "version": "node scripts/node/version-manager.mjs",
     "prebuild": "rm -rf dist tsconfig.tsbuildinfo tsconfig.*.tsbuildinfo",
-    "build": "tsc && mkdir -p dist/public dist/scripts && cp -r public/* dist/public/ && cp scripts/hooks/pre-command dist/scripts/ && cp scripts/hooks/pre-command.mjs dist/scripts/ && cp README.md AGENTS.md SKILLS.md CHANGELOG.md LICENSE .gitignore.default dist/ && find src -name '*.mjs' ! -path '*/__tests__/*' | while read f; do tgt=\"dist/${f#src/}\"; mkdir -p \"$(dirname $tgt)\"; cp \"$f\" \"$tgt\"; done && for dir in skills integrations mcps; do find src/$dir -type f ! -name '*.ts' ! -path '*/.pytest_cache/*' | while read f; do tgt=\"dist/${f#src/}\"; mkdir -p \"$(dirname $tgt)\"; cp \"$f\" \"$tgt\"; done; done && mkdir -p dist/plugin && (find dist/plugin -name '*codex-injection*.js' -exec cp {} dist/plugin/xray-codex-injection.js \\; 2>/dev/null || true) && cp -r src/opencode/ .opencode/ && mkdir -p .xray && cp xray/codex.json .xray/codex.json 2>/dev/null || true",
+    "build": "tsc && mkdir -p dist/public dist/scripts && cp -r public/* dist/public/ && cp scripts/hooks/pre-command dist/scripts/ && cp scripts/hooks/pre-command.mjs dist/scripts/ && cp README.md AGENTS.md SKILLS.md CHANGELOG.md LICENSE .gitignore.default dist/ && find src -name '*.mjs' ! -path '*/__tests__/*' | while read f; do tgt=\"dist/${f#src/}\"; mkdir -p \"$(dirname $tgt)\"; cp \"$f\" \"$tgt\"; done && for dir in skills integrations mcps; do find src/$dir -type f ! -name '*.ts' ! -path '*/.pytest_cache/*' | while read f; do tgt=\"dist/${f#src/}\"; mkdir -p \"$(dirname $tgt)\"; cp \"$f\" \"$tgt\"; done; done && mkdir -p dist/plugin && (find dist/plugin -name '*codex-injection*.js' -exec cp {} dist/plugin/xray-codex-injection.js \\; 2>/dev/null || true) && cp -r src/opencode/ .opencode/ && mkdir -p .xray && for f in codex.json features.json features.schema.json config.json; do cp xray/$f .xray/$f 2>/dev/null || true; done",
     "build:all": "npm run build",
     "ci-install": "npm ci",
     "clean": "rm -rf dist tsconfig.tsbuildinfo tsconfig.*.tsbuildinfo",
@@ -94,6 +98,7 @@
     "test:dependency-scan": "npm run security-audit",
     "test:integration": "node scripts/mjs/test-consumer-readiness.mjs && node scripts/mjs/test-mcp-functionality.mjs",
     "test:e2e": "node scripts/node/validate-mcp-connectivity.js && node scripts/node/validate-external-processes.js",
+    "live-feedback-session": "npx --yes tsx scripts/live-taskhandler-feedback-session.ts",
     "validate": "echo \"[xray] Use 'npm test' or 'npm run test:comprehensive'.\"",
     "validate:quick": "npm run validate",
     "debug:inference:force": "XRAY_FORCE_MCP_GOVERNANCE=true XRAY_DEV_PATH=dist node dist/cli/index.js inference:run --force",
@@ -108,15 +113,18 @@
     "build:clean": "node scripts/build/utils.js clean",
     "build:verify": "node scripts/build/utils.js verify",
     "enforce:versions": "bash scripts/node/enforce-version-compliance.sh",
-    "version:sync": "node scripts/node/universal-version-manager.js",
-    "preversion": "npm run version:sync",
-    "release": "node scripts/node/release.js",
+    "version:sync": "node scripts/node/version-manager.mjs --artifacts-only",
+    "release": "node scripts/node/release.mjs patch",
     "release:minor": "node scripts/node/release.mjs minor",
     "release:major": "node scripts/node/release.mjs major",
-    "release:dry": "node scripts/node/release.js --dry-run",
+    "release:dry": "node scripts/node/release.mjs patch --dry-run",
+    "version:reconcile": "node scripts/node/reconcile-version.mjs",
+    "consumer:smoke": "node scripts/node/consumer-install-smoke.mjs",
+    "release:gate": "node scripts/node/release-gate.mjs",
+    "release:docs-check": "node scripts/node/validate-release-docs.mjs",
     "pre-publish-guard": "node scripts/node/pre-publish-guard.js",
     "safe-publish": "npm run prepare-consumer && npm run build",
-    "publish": "npm run pre-publish-guard && npm run safe-publish",
+    "publish": "npm run release:gate && npm run safe-publish && npm publish --access public",
     "release:patch": "node scripts/node/release.mjs patch"
   },
   "files": [
@@ -155,6 +163,13 @@
     "SKILLS.md",
     "xray/agents_template.md",
     "xray/codex.json",
+    "xray/features.json",
+    "xray/features.schema.json",
+    "xray/config.json",
+    ".xray/codex.json",
+    ".xray/features.json",
+    ".xray/features.schema.json",
+    ".xray/config.json",
     ".gitignore.default",
     "LICENSE"
   ],

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

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * consumer-install-smoke.mjs — Clean-room pack + install verification.
+ *
+ * Simulates what consumers receive from npm without publishing.
+ *
+ * Usage:
+ *   node scripts/node/consumer-install-smoke.mjs
+ */
+
+import { execSync } from "child_process";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { fileURLToPath } from "url";
+import { createRequire } from "module";
+
+const require = createRequire(import.meta.url);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(__dirname, "../..");
+
+const XRAY_MCP_NAMES = [
+  "xray-governance",
+  "xray-skills",
+  "xray-orchestrator",
+  "xray-enforcer",
+  "xray-researcher",
+  "xray-code-review",
+  "xray-architect-tools",
+];
+
+function run(cmd, cwd, { inherit = false } = {}) {
+  const result = execSync(cmd, {
+    cwd,
+    encoding: inherit ? undefined : "utf-8",
+    stdio: inherit ? "inherit" : "pipe",
+  });
+  return inherit ? "" : String(result).trim();
+}
+
+function main() {
+  console.log("\n=== Consumer Install Smoke ===\n");
+
+  const pkg = JSON.parse(fs.readFileSync(path.join(rootDir, "package.json"), "utf-8"));
+  const version = pkg.version;
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "0xray-smoke-"));
+  let tarball = null;
+
+  try {
+    console.log("📦 npm pack...");
+    const packOut = run("npm pack --silent", rootDir);
+    tarball = packOut.split("\n").filter(Boolean).pop();
+    const tarballPath = path.join(rootDir, tarball);
+    if (!fs.existsSync(tarballPath)) {
+      throw new Error(`Tarball not found: ${tarballPath}`);
+    }
+
+    const consumerPkg = {
+      name: "0xray-smoke-consumer",
+      private: true,
+      version: "1.0.0",
+      dependencies: {
+        "0xray": `file:${tarballPath}`,
+      },
+    };
+    fs.writeFileSync(
+      path.join(tmpRoot, "package.json"),
+      JSON.stringify(consumerPkg, null, 2) + "\n",
+    );
+
+    console.log("📥 npm install (runs postinstall)...");
+    run("npm install", tmpRoot, { inherit: true });
+
+    const nmRoot = path.join(tmpRoot, "node_modules", "0xray");
+    const requiredFiles = [
+      "scripts/node/install-bridges.cjs",
+      "scripts/node/postinstall.cjs",
+      "package.json",
+      "xray/features.json",
+      "xray/features.schema.json",
+    ];
+
+    for (const rel of requiredFiles) {
+      const full = path.join(nmRoot, rel);
+      if (!fs.existsSync(full)) {
+        throw new Error(`Missing in tarball install: ${rel}`);
+      }
+      console.log(`  ✅ ${rel}`);
+    }
+
+    const installedPkg = JSON.parse(fs.readFileSync(path.join(nmRoot, "package.json"), "utf-8"));
+    if (installedPkg.version !== version) {
+      throw new Error(`Installed version ${installedPkg.version} != packed ${version}`);
+    }
+
+    const bridges = require(path.join(nmRoot, "scripts/node/install-bridges.cjs"));
+    for (const exp of ["installAllBridges", "resolveConsumerTargetDir", "isConsumerInstall"]) {
+      if (typeof bridges[exp] !== "function") {
+        throw new Error(`install-bridges missing export: ${exp}`);
+      }
+    }
+    console.log("  ✅ install-bridges exports");
+
+    if (!bridges.isConsumerInstall(nmRoot, tmpRoot)) {
+      throw new Error("isConsumerInstall should be true for node_modules/0xray → project root");
+    }
+    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");
+    }
+    const mcp = JSON.parse(fs.readFileSync(mcpPath, "utf-8"));
+    const servers = Object.keys(mcp.mcpServers || {});
+    for (const name of XRAY_MCP_NAMES) {
+      if (!servers.includes(name)) {
+        throw new Error(`Missing MCP server in .mcp.json: ${name}`);
+      }
+      const entry = mcp.mcpServers[name];
+      if (entry.command !== "npx") {
+        throw new Error(`${name} should use npx, got ${entry.command}`);
+      }
+    }
+    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)");
+
+    const schemaInPackage = path.join(nmRoot, "xray", "features.schema.json");
+    if (!fs.existsSync(schemaInPackage)) {
+      throw new Error("xray/features.schema.json missing from installed package");
+    }
+    console.log("  ✅ xray/features.schema.json in package");
+
+    console.log("\n✅ Consumer install smoke passed\n");
+  } catch (err) {
+    console.error(`\n❌ Consumer smoke failed: ${err.message}\n`);
+    process.exit(1);
+  } finally {
+    if (tarball) {
+      try {
+        fs.unlinkSync(path.join(rootDir, tarball));
+      } catch {
+        /* best-effort */
+      }
+    }
+    try {
+      fs.rmSync(tmpRoot, { recursive: true, force: true });
+    } catch {
+      /* best-effort */
+    }
+  }
+}
+
+main();

package/scripts/node/install-bridges.cjs

@@ -397,18 +397,28 @@ function installOpenclawBridge(targetDir, packageRoot, log) {
   if (copied > 0) log("openclaw-bridge", `skills synced (${copied})`, "info", { path: "~/.openclaw/skills/" });
 }
 
+const XRAY_CONFIG_FILES = ["codex.json", "features.json", "features.schema.json", "config.json"];
+
+function resolveXrayConfigSource(packageRoot, file) {
+  // Shipped SSOT: xray/ template wins over dev .xray/ runtime copy (P0.2)
+  const xrayDir = path.join(packageRoot, "xray", file);
+  if (fs.existsSync(xrayDir)) return xrayDir;
+  const dotXray = path.join(packageRoot, ".xray", file);
+  if (fs.existsSync(dotXray)) return dotXray;
+  return null;
+}
+
 function deployXrayConfig(targetDir, packageRoot, log) {
-  const xraySourceDir = path.join(packageRoot, ".xray");
   const xrayTargetDir = path.join(targetDir, ".xray");
-  const configFiles = ["codex.json", "features.json", "config.json"];
-  if (!fs.existsSync(xraySourceDir)) return;
+  const hasAnySource = XRAY_CONFIG_FILES.some((file) => resolveXrayConfigSource(packageRoot, file));
+  if (!hasAnySource) return;
 
   if (!fs.existsSync(xrayTargetDir)) fs.mkdirSync(xrayTargetDir, { recursive: true });
   let copied = 0;
-  for (const file of configFiles) {
-    const src = path.join(xraySourceDir, file);
+  for (const file of XRAY_CONFIG_FILES) {
+    const src = resolveXrayConfigSource(packageRoot, file);
     const dst = path.join(xrayTargetDir, file);
-    if (!fs.existsSync(src)) continue;
+    if (!src) continue;
     const shouldCopy = !fs.existsSync(dst) || fs.statSync(src).mtime > fs.statSync(dst).mtime;
     if (shouldCopy) {
       fs.copyFileSync(src, dst);
@@ -416,6 +426,7 @@ function deployXrayConfig(targetDir, packageRoot, log) {
     }
   }
   if (copied > 0) log("xray-config", `${copied} files deployed`, "info", { path: ".xray/" });
+  return copied;
 }
 
 function installGitHooks(packageRoot, log) {
@@ -463,4 +474,7 @@ module.exports = {
   resolveConsumerTargetDir,
   syncBuiltinSkills,
   isConsumerInstall,
+  deployXrayConfig,
+  resolveXrayConfigSource,
+  XRAY_CONFIG_FILES,
 };