0xray 4.0.11 → 4.0.13

package/dist/integrations/hermes-agent/bridge.mjs

@@ -1,1060 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Xray Framework Bridge for Hermes Agent
- *
- * Provides direct access to Xray framework components
- * (ProcessorManager, QualityGate, StateManager) from Python.
- * Uses JSON stdin/stdout protocol for IPC.
- *
- * Commands:
- *   pre-process   - Run quality gate + pre-processors before tool execution
- *   post-process  - Run post-processors after tool execution
- *   validate      - Run validation on files
- *   health        - Quick framework health check
- *   codex-check   - Check code against codex rules
- *   stats         - Return bridge/framework statistics
- *   hooks         - Manage git hooks (install, uninstall, list, status)
- *   session-start - Session boot: archive stale lead-dev plans (synthesis exempt)
- *   govern        - Govern inference proposals through weighted voting
- *   apply         - Govern + apply approved inference proposals
- *
- * Usage:
- *   echo '{"command":"health"}' | node bridge.mjs [--cwd /path]   # stdin mode
- *   node bridge.mjs health --cwd /path                           # positional mode (no pipe needed)
- *   node bridge.mjs validate --cwd /path --json '{"files":["a.ts"]}'  # positional + payload
- */
-
-import {
-  existsSync,
-  readFileSync,
-  writeFileSync,
-  appendFileSync,
-  mkdirSync,
-  readdirSync,
-  lstatSync,
-  symlinkSync,
-  unlinkSync,
-  renameSync,
-} from "fs";
-import { join, dirname, relative, resolve } from "path";
-import { fileURLToPath, pathToFileURL } from "url";
-import { homedir } from "os";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-/** Resolve find-project-root from plugin install, dist layout, or consumer node_modules. */
-function resolveFindProjectRootPath() {
-  const candidates = [];
-  const marker = join(__dirname, "xray-consumer-root.txt");
-  if (existsSync(marker)) {
-    try {
-      const marked = readFileSync(marker, "utf-8").trim();
-      if (marked) {
-        candidates.push(
-          join(marked, "node_modules", "0xray", "scripts", "helpers", "find-project-root.mjs"),
-        );
-      }
-    } catch {
-      /* fall through */
-    }
-  }
-  candidates.push(
-    join(__dirname, "scripts", "helpers", "find-project-root.mjs"),
-    join(__dirname, "..", "..", "..", "scripts", "helpers", "find-project-root.mjs"),
-    join(__dirname, "../../../scripts/helpers/find-project-root.mjs"),
-  );
-  for (const candidate of candidates) {
-    const abs = resolve(candidate);
-    if (existsSync(abs)) return abs;
-  }
-  throw new Error("find-project-root.mjs not found — re-run: npx 0xray hermes install --force");
-}
-
-const { findProjectRoot } = await import(pathToFileURL(resolveFindProjectRootPath()).href);
-
-// ── Framework components (lazy-loaded) ───────────────────────
-let ProcessorManager = null;
-let XrayStateManager = null;
-let featuresConfigLoader = null;
-let runQualityGateWithLogging = null;
-let enforcerValidators = null;
-let frameworkReady = false;
-let frameworkLoadAttempted = false;
-
-// ── Project root detection ───────────────────────────────────
-function resolveBridgeProjectRoot() {
-  const consumerMarker = join(__dirname, "xray-consumer-root.txt");
-  if (existsSync(consumerMarker)) {
-    try {
-      const marked = readFileSync(consumerMarker, "utf-8").trim();
-      if (marked && existsSync(join(marked, "package.json"))) {
-        return marked;
-      }
-    } catch {
-      // fall through to shared SSOT
-    }
-  }
-  return findProjectRoot([join(dirname(__dirname), "..", "..", "..", "..")]);
-}
-
-// ── Log directory ────────────────────────────────────────────
-function ensureLogDir(projectRoot) {
-  const logDir = join(projectRoot, "logs", "framework");
-  if (!existsSync(logDir)) {
-    mkdirSync(logDir, { recursive: true });
-  }
-  return logDir;
-}
-
-function logToActivity(logDir, message) {
-  try {
-    const activityPath = join(logDir, "activity.log");
-    const timestamp = new Date().toISOString();
-    const entry = `${timestamp} [bridge] ${message}\n`;
-    appendFileSync(activityPath, entry, "utf-8");
-  } catch {
-    // Silent fail
-  }
-}
-
-function logRoutingOutcome(logDir, outcome) {
-  try {
-    const routingPath = join(logDir, "routing-outcomes.json");
-    let entries = [];
-    if (existsSync(routingPath)) {
-      try { entries = JSON.parse(readFileSync(routingPath, "utf-8")); } catch { entries = []; }
-    }
-    if (!Array.isArray(entries)) entries = [];
-    entries.push({
-      taskId: outcome.taskId || `bridge-${Date.now()}`,
-      taskDescription: outcome.taskDescription || outcome.tool || "unknown",
-      routedAgent: outcome.routedAgent || "direct",
-      routedSkill: outcome.routedSkill || outcome.tool || "unknown",
-      confidence: outcome.confidence || 0.8,
-      success: outcome.success !== false,
-      routingMethod: outcome.routingMethod || "bridge",
-      timestamp: new Date().toISOString(),
-    });
-    writeFileSync(routingPath, JSON.stringify(entries, null, 2), "utf-8");
-  } catch {
-    // Silent fail
-  }
-}
-
-function logToolEvent(logDir, eventType, tool, args = {}, result = null) {
-  try {
-    const eventsPath = join(logDir, "plugin-tool-events.log");
-    const timestamp = new Date().toISOString();
-    const jobId = `plugin-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;
-
-    if (eventType === "start") {
-      const entry = `${timestamp} [${jobId}] [agent] tool-started - INFO | {"tool":"${tool}","args":${JSON.stringify(Object.keys(args))}}\n`;
-      appendFileSync(eventsPath, entry, "utf-8");
-    } else {
-      const success = !result?.error;
-      const level = success ? "SUCCESS" : "ERROR";
-      const entry = `${timestamp} [${jobId}] [agent] tool-complete - ${level} | {"tool":"${tool}","duration":${result?.duration || 0}${result?.error ? `,"error":"${result.error}"` : ""}}\n`;
-      appendFileSync(eventsPath, entry, "utf-8");
-    }
-  } catch {
-    // Silent fail
-  }
-}
-
-// ── Framework loading ────────────────────────────────────────
-async function loadFramework(projectRoot) {
-  if (frameworkReady) return true;
-  if (frameworkLoadAttempted) return false;
-  frameworkLoadAttempted = true;
-
-  const distDirs = [
-    join(projectRoot, "dist"),
-    join(projectRoot, "node_modules", "0xray", "dist"),
-  ];
-
-  for (const distDir of distDirs) {
-    try {
-      // Quality gate (standalone, no deps)
-      if (!runQualityGateWithLogging) {
-        const qgPath = join(distDir, "plugin", "quality-gate.js");
-        if (existsSync(qgPath)) {
-          const qgModule = await import(qgPath);
-          runQualityGateWithLogging = qgModule.runQualityGateWithLogging;
-        }
-      }
-
-      // Heavy framework components
-      if (!ProcessorManager) {
-        const pmPath = join(distDir, "processors", "processor-manager.js");
-        if (existsSync(pmPath)) {
-          const pm = await import(pmPath);
-          ProcessorManager = pm.ProcessorManager;
-        }
-      }
-
-      if (!XrayStateManager) {
-        const smPath = join(distDir, "state", "state-manager.js");
-        if (existsSync(smPath)) {
-          const sm = await import(smPath);
-          XrayStateManager = sm.XrayStateManager;
-        }
-      }
-
-      if (!featuresConfigLoader) {
-        const fmPath = join(distDir, "core", "features-config.js");
-        if (existsSync(fmPath)) {
-          const fm = await import(fmPath);
-          featuresConfigLoader = fm.featuresConfigLoader;
-        }
-      }
-
-      // RuleEnforcer — full code analysis (security, quality, architecture)
-      if (!enforcerValidators) {
-        const rePath = join(distDir, "enforcement", "index.js");
-        if (existsSync(rePath)) {
-          try {
-            const reModule = await import(rePath);
-            // Use ValidatorRegistry directly to bypass RuleExecutor dependency chain
-            // which cascades failures when validators lack full project context
-            const ValidatorRegistry = reModule.ValidatorRegistry;
-            if (ValidatorRegistry) {
-              enforcerValidators = new ValidatorRegistry();
-              // Validators are pre-registered in constructor — no registerAllValidators needed
-            }
-          } catch (e) {
-            logToActivity(join(projectRoot, "logs", "framework"), `ValidatorRegistry load skipped: ${e.message}`);
-          }
-        }
-      }
-
-      frameworkReady = !!(runQualityGateWithLogging || ProcessorManager);
-      if (frameworkReady) return true;
-    } catch (e) {
-      continue;
-    }
-  }
-  return false;
-}
-
-// ── Quality Gate ─────────────────────────────────────────────
-class BridgeLogger {
-  constructor(logDir) {
-    this.logDir = logDir;
-  }
-
-  log(msg) {
-    logToActivity(this.logDir, msg);
-  }
-
-  error(msg, err) {
-    const detail = err instanceof Error ? `: ${err.message}` : "";
-    logToActivity(this.logDir, `ERROR: ${msg}${detail}`);
-  }
-}
-
-async function runQualityGateCheck(context, projectRoot, logDir) {
-  const logger = new BridgeLogger(logDir);
-
-  if (!runQualityGateWithLogging) {
-    return { passed: true, violations: [], note: "quality-gate module not available" };
-  }
-
-  try {
-    const result = await runQualityGateWithLogging(context, logger);
-    return {
-      passed: result.passed,
-      violations: result.violations,
-      checks: result.checks,
-    };
-  } catch (e) {
-    return { passed: false, violations: [{ id: "quality-gate-error", severity: "error", message: `Quality gate failed: ${e.message}` }], error: e.message };
-  }
-}
-
-// ── Processor Pipeline ───────────────────────────────────────
-async function runProcessors(tool, args, phase, projectRoot, logDir) {
-  if (!ProcessorManager || !XrayStateManager) {
-    return { ran: false, reason: "framework modules not loaded" };
-  }
-
-  const logger = new BridgeLogger(logDir);
-
-  try {
-    const stateDir = join(projectRoot, ".xray", "state");
-    const stateManager = new XrayStateManager(stateDir);
-    const processorManager = new ProcessorManager(stateManager);
-
-    // Register processors matching OpenCode plugin
-    if (phase === "pre") {
-      processorManager.registerProcessor({
-        name: "preValidate",
-        type: "pre",
-        priority: 10,
-        enabled: true,
-      });
-      processorManager.registerProcessor({
-        name: "codexCompliance",
-        type: "pre",
-        priority: 20,
-        enabled: true,
-      });
-      processorManager.registerProcessor({
-        name: "versionCompliance",
-        type: "pre",
-        priority: 25,
-        enabled: true,
-      });
-    }
-
-    if (phase === "post") {
-      processorManager.registerProcessor({
-        name: "testAutoCreation",
-        type: "post",
-        priority: 5,
-        enabled: true,
-      });
-      processorManager.registerProcessor({
-        name: "testExecution",
-        type: "post",
-        priority: 10,
-        enabled: true,
-      });
-      processorManager.registerProcessor({
-        name: "coverageAnalysis",
-        type: "post",
-        priority: 20,
-        enabled: true,
-      });
-      processorManager.registerProcessor({
-        name: "agentsMdValidation",
-        type: "post",
-        priority: 30,
-        enabled: true,
-      });
-      processorManager.registerProcessor({
-        name: "nudge",
-        type: "post",
-        priority: 78,
-        enabled: true,
-      });
-    }
-
-    let results;
-    if (phase === "pre") {
-      if (typeof processorManager.executePreProcessors !== "function") {
-        return { ran: false, reason: "executePreProcessors not available" };
-      }
-      results = await processorManager.executePreProcessors({
-        tool,
-        args: args || {},
-        context: {
-          directory: projectRoot,
-          operation: "tool_execution",
-          filePath: args?.filePath || args?.path,
-        },
-      });
-    } else {
-      if (typeof processorManager.executePostProcessors !== "function") {
-        return { ran: false, reason: "executePostProcessors not available" };
-      }
-      results = await processorManager.executePostProcessors(tool, {
-        directory: projectRoot,
-        operation: tool,
-        filePath: args?.filePath || args?.path,
-        success: true,
-        metadata: {
-          hook: "hermes_tool_execution",
-          toolName: tool,
-          timestamp: Date.now(),
-        },
-      }, []);
-    }
-
-    const allSuccess = Array.isArray(results)
-      ? results.every((r) => r.success)
-      : results.success;
-
-    const details = Array.isArray(results)
-      ? results.map((r) => ({
-          name: r.processorName || r.name,
-          success: r.success,
-          error: r.error,
-        }))
-      : [];
-
-    return {
-      ran: true,
-      success: allSuccess,
-      processorCount: details.length,
-      details,
-    };
-  } catch (e) {
-    return { ran: false, reason: e.message };
-  }
-}
-
-// ── Command handlers ─────────────────────────────────────────
-
-async function handleHealth(input) {
-  const projectRoot = resolveBridgeProjectRoot();
-  const loaded = await loadFramework(projectRoot);
-
-  const components = {
-    qualityGate: !!runQualityGateWithLogging,
-    processorManager: !!ProcessorManager,
-    stateManager: !!XrayStateManager,
-    featuresConfig: !!featuresConfigLoader,
-  };
-
-  const pkgPath = join(projectRoot, "package.json");
-  let version = "unknown";
-  if (existsSync(pkgPath)) {
-    try {
-      version = JSON.parse(readFileSync(pkgPath, "utf-8")).version;
-    } catch {}
-  }
-
-  return {
-    status: "ok",
-    framework: loaded ? "loaded" : "not_loaded",
-    version,
-    projectRoot,
-    components,
-    nodeVersion: process.version,
-  };
-}
-
-async function handleSessionStart(input, projectRoot, logDir) {
-  const sessionId = input.sessionId || `bridge-${Date.now()}`;
-  let planArchive = { archived: false };
-
-  try {
-    const { archiveStaleLeadDevPlan } = await import('../hooks/plan-hook-runtime.mjs');
-    planArchive = archiveStaleLeadDevPlan(projectRoot);
-    if (planArchive.archived) {
-      logToActivity(
-        logDir,
-        `session-start: stale-plan-archived path=${planArchive.archivePath ?? 'unknown'}`,
-      );
-    }
-  } catch {
-    /* non-blocking — dist may be absent during dev */
-  }
-
-  try {
-    const gate = await import('../hooks/delegation-gate-runtime.mjs');
-    if (typeof gate.writeSuitSessionBoot === 'function') {
-      const compact =
-        input.compact === true ||
-        input.hookEvent === 'pre_compact' ||
-        input.hookEvent === 'post_compact';
-      gate.writeSuitSessionBoot(projectRoot, 'hermes', {
-        source: compact ? '0xray/hermes-compact' : '0xray/hermes-session-start',
-        sessionId,
-        hookEvent: compact ? 'post_compact' : 'session_start',
-        ...(input.intent ? { intent: input.intent } : {}),
-      });
-    }
-  } catch {
-    /* dist may be absent during dev */
-  }
-
-  logToActivity(logDir, `session-start: session=${sessionId} source=bridge`);
-  return { ok: true, sessionId, planArchive };
-}
-
-async function handlePreProcess(input, projectRoot, logDir) {
-  const { tool, args } = input;
-  const startTime = Date.now();
-
-  logToolEvent(logDir, "start", tool, args);
-  logToActivity(logDir, `pre-process: tool=${tool}`);
-
-  // 1. Quality gate check
-  const qualityResult = await runQualityGateCheck(
-    { tool, args: args || {} },
-    projectRoot,
-    logDir,
-  );
-
-  // 2. Pre-processors (for code-producing tools only)
-  let processorResult = { ran: false };
-  const codeTools = ["write_file", "patch", "execute_code", "write", "edit"];
-  if (codeTools.includes(tool)) {
-    processorResult = await runProcessors(tool, args, "pre", projectRoot, logDir);
-  }
-
-  const duration = Date.now() - startTime;
-
-  logToActivity(logDir, `pre-process: complete duration=${duration}ms quality=${qualityResult.passed}`);
-
-  return {
-    passed: qualityResult.passed,
-    duration,
-    qualityGate: qualityResult,
-    processors: processorResult,
-  };
-}
-
-async function handlePostProcess(input, projectRoot, logDir) {
-  const { tool, args, result, error } = input;
-  const startTime = Date.now();
-
-  logToActivity(logDir, `post-process: tool=${tool}`);
-
-  // 1. Post-processors (for code-producing tools only)
-  let processorResult = { ran: false };
-  const codeTools = ["write_file", "patch", "execute_code", "write", "edit"];
-  if (codeTools.includes(tool)) {
-    processorResult = await runProcessors(tool, args, "post", projectRoot, logDir);
-  }
-
-  const duration = Date.now() - startTime;
-
-  logToolEvent(logDir, "complete", tool, args, {
-    duration,
-    error: error || (processorResult.ran && !processorResult.success ? "processor-failed" : null),
-  });
-
-  logToActivity(logDir, `post-process: complete duration=${duration}ms processors=${processorResult.success}`);
-  logToActivity(logDir, `[nudge] post-process tool=${tool}`);
-
-  // Log routing outcome for test verification
-  logRoutingOutcome(logDir, {
-    tool,
-    taskDescription: `[post-process] ${tool}`,
-    routedAgent: "bridge",
-    routedSkill: tool,
-    success: processorResult.success !== false,
-  });
-
-  return {
-    duration,
-    processors: processorResult,
-  };
-}
-
-async function handleValidate(input, projectRoot, logDir) {
-  const { files, operation } = input;
-  logToActivity(logDir, `validate: files=${JSON.stringify(files)} operation=${operation}`);
-
-  // Use quality gate on each file
-  const results = [];
-  for (const filePath of files || []) {
-    const qualityResult = await runQualityGateCheck(
-      { tool: "write", args: { filePath } },
-      projectRoot,
-      logDir,
-    );
-    results.push({ file: filePath, ...qualityResult });
-  }
-
-  const allPassed = results.every((r) => r.passed);
-  return {
-    passed: allPassed,
-    operation: operation || "validate",
-    fileResults: results,
-  };
-}
-
-async function handleCodexCheck(input, projectRoot, logDir) {
-  const { code, focusAreas, operation } = input;
-  const codeLen = code?.length || 0;
-  logToActivity(logDir, `codex-check: code_length=${codeLen} focus=${focusAreas} operation=${operation}`);
-
-  // Collect violations from both systems
-  const allViolations = [];
-  const allChecks = [];
-  let enforcerRan = false;
-
-  // Phase 1: Quality gate (fast meta-checks + basic patterns)
-  const qualityResult = await runQualityGateCheck(
-    { tool: "write", args: { content: code } },
-    projectRoot,
-    logDir,
-  );
-
-  if (qualityResult.checks) {
-    allChecks.push(...qualityResult.checks);
-  }
-  if (qualityResult.violations?.length) {
-    allViolations.push(...qualityResult.violations);
-  }
-
-  // Phase 2: Enforcement validators (deep code analysis — security, quality, architecture)
-  //    Use ValidatorRegistry directly instead of RuleEnforcer.validateOperation()
-  //    to avoid the dependency chain cascade that blocks validators on snippet analysis.
-  //    Only run content-analysis validators — skip project-level validators that
-  //    require full context (docs, tests, CI, package.json) and always fail on snippets.
-  const SNIPPET_SAFE_RULES = new Set([
-    "security-by-design",
-    "input-validation",
-    "clean-debug-logs",
-    "console-log-usage",
-    "no-duplicate-code",
-    "loop-safety",
-    "no-over-engineering",
-    "single-responsibility",
-    "error-resolution",
-    "module-system-consistency",
-  ]);
-
-  if (enforcerValidators && codeLen > 0) {
-    try {
-      const ctx = { operation: "write", newCode: code, files: [] };
-      const validators = enforcerValidators.getAllValidators();
-      let enforcerViolations = 0;
-
-      for (const v of validators) {
-        // Only run snippet-safe validators, or respect focus areas
-        if (!SNIPPET_SAFE_RULES.has(v.ruleId)) {
-          // Still run if focus area explicitly requests this category
-          if (focusAreas && focusAreas !== "all" && Array.isArray(focusAreas)) {
-            if (focusAreas.includes(v.category)) {
-              // Fall through to validate
-            } else {
-              continue;
-            }
-          } else {
-            continue;
-          }
-        }
-
-        try {
-          const result = await v.validate(ctx);
-          if (!result.passed) {
-            enforcerViolations++;
-            allViolations.push({
-              id: v.ruleId,
-              severity: v.severity || "error",
-              message: result.message,
-              suggestions: result.suggestions,
-            });
-            allChecks.push({ id: v.ruleId, passed: false, message: result.message });
-          }
-        } catch {
-          // Skip broken validators gracefully
-        }
-      }
-
-      enforcerRan = true;
-      logToActivity(logDir, `codex-check: Validators ran against ${validators.length} rules (${SNIPPET_SAFE_RULES.size} snippet-safe), ${enforcerViolations} violations`);
-    } catch (e) {
-      logToActivity(logDir, `codex-check: Validator error: ${e.message}`);
-    }
-  } else if (!enforcerValidators) {
-    logToActivity(logDir, `codex-check: Validators not available, quality gate only`);
-  }
-
-  const passed = allViolations.length === 0;
-
-  return {
-    passed,
-    violations: allViolations,
-    checks: allChecks,
-    focusAreas: focusAreas || "all",
-    enforcerRan,
-  };
-}
-
-function handleHooks(input, projectRoot) {
-  const { action, hooks } = input;
-  const hookTypes = hooks || ["pre-commit", "post-commit", "pre-push", "post-push"];
-  const gitHooksDir = join(projectRoot, ".git", "hooks");
-  const xrayHooksDir = join(projectRoot, "hooks");
-
-  if (!existsSync(gitHooksDir)) {
-    return { error: "Not a git repository — no .git/hooks directory" };
-  }
-
-  const result = { managed: [], missing: [], external: [], stale: [] };
-
-  // ── list / status ───────────────────────────────────────
-  if (action === "list" || action === "status") {
-    for (const hookName of hookTypes) {
-      const gitHook = join(gitHooksDir, hookName);
-      const xrayHook = join(xrayHooksDir, hookName);
-
-      if (!existsSync(gitHook)) {
-        result.missing.push(hookName);
-      } else {
-        try {
-          const content = readFileSync(gitHook, "utf-8");
-          if (content.includes("Xray") || content.includes("xray") || false || content.includes("run-hook.js")) {
-            result.managed.push(hookName);
-          } else {
-            result.external.push(hookName);
-          }
-        } catch {
-          result.external.push(hookName);
-        }
-      }
-
-      // Check if xray source hook exists
-      if (!existsSync(xrayHook)) {
-        result.stale.push(hookName);
-      }
-    }
-
-    return {
-      status: "ok",
-      action,
-      hooks: result,
-      gitHooksDir,
-      xrayHooksDir,
-    };
-  }
-
-  // ── install ─────────────────────────────────────────────
-  if (action === "install") {
-    const installed = [];
-    const skipped = [];
-    const errors = [];
-
-    for (const hookName of hookTypes) {
-      const src = join(xrayHooksDir, hookName);
-      const dst = join(gitHooksDir, hookName);
-
-      if (!existsSync(src)) {
-        skipped.push(hookName);
-        continue;
-      }
-
-      try {
-        // Backup existing non-xray hooks
-        if (existsSync(dst)) {
-          const content = readFileSync(dst, "utf-8");
-          if (!content.includes("Xray") && !content.includes("xray") && !false && !content.includes("run-hook.js")) {
-            renameSync(dst, `${dst}.xray-backup`);
-          } else {
-            unlinkSync(dst);
-          }
-        }
-
-        // Create symlink
-        const rel = relative(join(gitHooksDir), src);
-        try {
-          // symlinkSync with 'junction' on Windows
-          symlinkSync(rel, dst);
-        } catch {
-          // Symlink may fail (permissions, cross-device) — copy instead
-          const srcContent = readFileSync(src, "utf-8");
-          writeFileSync(dst, srcContent, { mode: 0o755 });
-        }
-        installed.push(hookName);
-      } catch (err) {
-        errors.push({ hook: hookName, error: err.message });
-      }
-    }
-
-    return { status: "ok", action: "install", installed, skipped, errors };
-  }
-
-  // ── uninstall ───────────────────────────────────────────
-  if (action === "uninstall") {
-    const removed = [];
-    const restored = [];
-
-    for (const hookName of hookTypes) {
-      const dst = join(gitHooksDir, hookName);
-      const backup = `${dst}.xray-backup`;
-
-      if (!existsSync(dst)) continue;
-
-      try {
-        const content = readFileSync(dst, "utf-8");
-        const isXray = content.includes("Xray") || content.includes("xray") || false || content.includes("run-hook.js");
-
-        if (isXray || lstatSync(dst).isSymbolicLink()) {
-          unlinkSync(dst);
-
-          // Restore backup if exists
-          if (existsSync(backup)) {
-            renameSync(backup, dst);
-            restored.push(hookName);
-          } else {
-            removed.push(hookName);
-          }
-        }
-      } catch {
-        // Skip unremovable hooks
-      }
-    }
-
-    return { status: "ok", action: "uninstall", removed, restored };
-  }
-
-  return { error: `Unknown hooks action: ${action}. Use: install, uninstall, list, status` };
-}
-
-function handleStats() {
-  return {
-    frameworkReady,
-    qualityGateAvailable: !!runQualityGateWithLogging,
-    processorsAvailable: !!ProcessorManager,
-    nodeVersion: process.version,
-    projectRoot: resolveBridgeProjectRoot(),
-  };
-}
-
-async function handleGovern(input, projectRoot, logDir) {
-  const proposals = input.proposals || [];
-  logToActivity(logDir, `govern: ${proposals.length} proposals`);
-
-  try {
-    const { InferenceCycle } = await import("../../inference/inference-cycle.js");
-    const cycle = InferenceCycle.getInstance(projectRoot, { skipApply: true });
-    const result = await cycle.governExternalProposals(proposals);
-    return {
-      cycleId: result.cycleId,
-      approved: result.votes.filter((v) => v.decision === "approve").length,
-      rejected: result.votes.filter((v) => v.decision !== "approve").length,
-      votes: result.votes,
-      proposals: result.proposals.map((p) => ({ id: p.id, title: p.title, type: p.type, status: p.status })),
-      duration: result.duration,
-    };
-  } catch (error) {
-    return { error: `Governance failed: ${error.message || error}` };
-  }
-}
-
-async function handleApply(input, projectRoot, logDir) {
-  const proposals = input.proposals || [];
-  logToActivity(logDir, `apply: ${proposals.length} proposals`);
-
-  try {
-    const { InferenceCycle } = await import("../../inference/inference-cycle.js");
-    const cycle = InferenceCycle.getInstance(projectRoot);
-    const result = await cycle.governExternalProposals(proposals);
-    return {
-      cycleId: result.cycleId,
-      applied: result.proposals.filter((p) => p.status === "applied").length,
-      approved: result.votes.filter((v) => v.decision === "approve").length,
-      proposals: result.proposals.map((p) => ({ id: p.id, title: p.title, type: p.type, status: p.status })),
-      duration: result.duration,
-    };
-  } catch (error) {
-    return { error: `Apply failed: ${error.message || error}` };
-  }
-}
-
-// ── Known commands for positional-arg mode ──────────────────
-const KNOWN_COMMANDS = new Set([
-  "health", "stats", "pre-process", "post-process", "validate", "codex-check", "hooks", "govern", "apply",
-  "skill-install", "skill-registry", "delegation-gate", "session-start",
-]);
-
-async function recordHermesSynthesisTurn(projectRoot, sessionId) {
-  if (!sessionId) return;
-  try {
-    const { recordSynthesisTurnSlice } = await import("../hooks/synthesis-hook-runtime.mjs");
-    recordSynthesisTurnSlice(projectRoot, sessionId);
-  } catch {
-    /* optional */
-  }
-}
-
-async function handleDelegationGate(command, projectRoot, logDir) {
-  try {
-    const gate = await import("../hooks/delegation-gate-runtime.mjs");
-    const phase = command.phase || "pre";
-    const tool = command.tool || command.toolName || "unknown";
-    const args = command.args || command.toolInput || {};
-    const sessionId = command.sessionId || command.taskId || null;
-    const host = command.host || "hermes";
-
-    if (phase === "post") {
-      if (!gate.isSubagentTool(tool)) {
-        return { allow: true, phase: "post", skipped: true };
-      }
-      const toolOutput =
-        command.toolOutput ?? command.result ?? command.output ?? args?.result ?? null;
-      const result = gate.evaluatePostToolSpawn(tool, args, projectRoot, {
-        sessionId,
-        toolOutput,
-      });
-      if (result.satisfied.length > 0) {
-        logToActivity(
-          logDir,
-          `[delegation-gate-post] satisfied=${result.satisfied.map((d) => d.id).join(",")} clearedAll=${result.clearedAll}`,
-        );
-      }
-      return { allow: true, phase: "post", ...result };
-    }
-
-    if (command.recordTurn === true || command.event === 'user_prompt_submit') {
-      await recordHermesSynthesisTurn(projectRoot, sessionId);
-    }
-
-    const features = gate.loadDelegationGateFeatures(projectRoot, host);
-    const outcome = gate.evaluatePreToolGate(tool, args, {
-      projectRoot,
-      sessionId,
-      features,
-      host,
-    });
-
-    if (!outcome.allow) {
-      logToActivity(
-        logDir,
-        `[delegation-gate] deny tool=${tool} gate=${outcome.gate} reason=${outcome.reason}`,
-      );
-    }
-
-    return { phase: "pre", ...outcome };
-  } catch (error) {
-    const message = `delegation-gate failed: ${error.message || error}`;
-    logToActivity(logDir, `[delegation-gate] error ${message}`);
-    return {
-      allow: false,
-      phase: "pre",
-      gate: "delegation-gate-error",
-      reason: message,
-      error: message,
-    };
-  }
-}
-
-// ── Skill management ──────────────────────────────────────────
-
-async function handleSkillInstall(command, projectRoot, logDir) {
-  try {
-    const source = command.source;
-    if (!source) {
-      return { error: "Missing 'source' — specify a source name or git URL" };
-    }
-    const { execSync } = await import("child_process");
-    const output = execSync(`npx 0xray skill:install "${source}"`, { cwd: projectRoot, timeout: 120000 }).toString();
-    return { status: "ok", output: output.trim() };
-  } catch (error) {
-    return { error: `Skill install failed: ${error.message || error}` };
-  }
-}
-
-async function handleSkillRegistry(command, projectRoot, logDir) {
-  try {
-    const action = command.action || "list";
-    const { execSync } = await import("child_process");
-    const args = command.source ? `"${command.source}"` : "";
-    const output = execSync(`npx 0xray skill:registry ${action} ${args}`, { cwd: projectRoot, timeout: 30000 }).toString();
-    return { status: "ok", output: output.trim() };
-  } catch (error) {
-    return { error: `Skill registry command failed: ${error.message || error}` };
-  }
-}
-
-// ── Main ─────────────────────────────────────────────────────
-async function main() {
-  // Parse --cwd flag and detect positional command arg
-  let cwdOverride = null;
-  let positionalCommand = null;
-  let positionalPayload = null;
-  const argv = process.argv.slice(2);
-
-  for (let i = 0; i < argv.length; i++) {
-    if (argv[i] === "--cwd" && argv[i + 1]) {
-      cwdOverride = argv[i + 1];
-      process.chdir(cwdOverride);
-      i++;
-    } else if (argv[i] === "--json" && argv[i + 1]) {
-      // Inline JSON payload: node bridge.mjs health --json '{"key":"val"}'
-      positionalPayload = argv[i + 1];
-      i++;
-    } else if (!argv[i].startsWith("-") && !positionalCommand && KNOWN_COMMANDS.has(argv[i])) {
-      positionalCommand = argv[i];
-    } else if (!argv[i].startsWith("-") && positionalCommand && !positionalPayload) {
-      // Inline JSON payload after command: node bridge.mjs hooks '{"action":"install"}'
-      positionalPayload = argv[i];
-    }
-  }
-
-  let command;
-  if (positionalCommand) {
-    // Positional mode — no stdin needed (avoids security scanner blocks)
-    command = { command: positionalCommand };
-    if (positionalPayload) {
-      try {
-        command = { ...command, ...JSON.parse(positionalPayload) };
-      } catch {
-        process.stdout.write(JSON.stringify({ error: "Invalid --json payload" }));
-        process.exit(1);
-      }
-    }
-  } else {
-    // Stdin mode — read JSON from pipe (original behavior)
-    let input = "";
-    for await (const chunk of process.stdin) {
-      input += chunk;
-    }
-
-    try {
-      command = JSON.parse(input);
-    } catch {
-      process.stdout.write(JSON.stringify({ error: "Invalid JSON input" }));
-      process.exit(1);
-    }
-  }
-
-  const projectRoot = resolveBridgeProjectRoot();
-  const logDir = ensureLogDir(projectRoot);
-
-  // Lazy-load framework on first call
-  if (!frameworkReady && !frameworkLoadAttempted) {
-    await loadFramework(projectRoot);
-  }
-
-  let response;
-  const cmd = command.command || "health";
-
-  switch (cmd) {
-    case "health":
-      response = await handleHealth(command);
-      break;
-    case "pre-process":
-      response = await handlePreProcess(command, projectRoot, logDir);
-      break;
-    case "post-process":
-      response = await handlePostProcess(command, projectRoot, logDir);
-      break;
-    case "validate":
-      response = await handleValidate(command, projectRoot, logDir);
-      break;
-    case "codex-check":
-      response = await handleCodexCheck(command, projectRoot, logDir);
-      break;
-    case "stats":
-      response = handleStats();
-      break;
-    case "hooks":
-      response = handleHooks(command, projectRoot);
-      break;
-    case "govern":
-      response = await handleGovern(command, projectRoot, logDir);
-      break;
-    case "apply":
-      response = await handleApply(command, projectRoot, logDir);
-      break;
-    case "skill-install":
-      response = await handleSkillInstall(command, projectRoot, logDir);
-      break;
-    case "skill-registry":
-      response = await handleSkillRegistry(command, projectRoot, logDir);
-      break;
-    case "session-start":
-      response = await handleSessionStart(command, projectRoot, logDir);
-      break;
-    case "delegation-gate":
-      response = await handleDelegationGate(command, projectRoot, logDir);
-      break;
-    default:
-      response = { error: `Unknown command: ${cmd}` };
-  }
-
-  process.stdout.write(JSON.stringify(response));
-}
-
-main().catch((e) => {
-  process.stdout.write(JSON.stringify({ error: e.message }));
-  process.exit(1);
-});