0xray 4.0.13 → 4.0.14

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

@@ -0,0 +1,1060 @@
+#!/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);
+});