0xray 4.0.13 → 4.0.15

package/dist/integrations/grok/grok-cli.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Grok CLI Integration for 0xRay
+ *
+ * This module provides the integration points for using 0xRay with the official Grok CLI.
+ *
+ * Primary mechanism: MCP (Model Context Protocol)
+ * Grok CLI can consume MCP servers. By registering the 0xRay MCP servers,
+ * users get access to Governance, skills, and other capabilities directly inside Grok conversations.
+ *
+ * Recommended registration (via npx or Grok's tooling):
+ *   npx 0xray grok install
+ *
+ * This will help configure the user's Grok CLI to include the following MCP servers:
+ * - governance (Dynamo Solar SSOT + real skill deliberation)
+ * - All knowledge-skill MCP servers (code-review, security-audit, researcher, etc.)
+ */
+export interface GrokInstallOptions {
+    force?: boolean;
+    dryRun?: boolean;
+    env?: NodeJS.ProcessEnv;
+    machineHome?: string;
+    targetDir?: string;
+}
+export declare function installForGrokCLI(options?: GrokInstallOptions): Promise<void>;
+/** Grok TUI reads <project>/.grok/config.toml, not the package copy. */
+export declare function writeProjectRepertoireMcp(projectRoot: string): string | null;
+declare const _default: {
+    installForGrokCLI: typeof installForGrokCLI;
+    writeProjectRepertoireMcp: typeof writeProjectRepertoireMcp;
+};
+export default _default;

package/dist/integrations/grok/grok-cli.js

@@ -0,0 +1,223 @@
+/**
+ * Grok CLI Integration for 0xRay
+ *
+ * This module provides the integration points for using 0xRay with the official Grok CLI.
+ *
+ * Primary mechanism: MCP (Model Context Protocol)
+ * Grok CLI can consume MCP servers. By registering the 0xRay MCP servers,
+ * users get access to Governance, skills, and other capabilities directly inside Grok conversations.
+ *
+ * Recommended registration (via npx or Grok's tooling):
+ *   npx 0xray grok install
+ *
+ * This will help configure the user's Grok CLI to include the following MCP servers:
+ * - governance (Dynamo Solar SSOT + real skill deliberation)
+ * - All knowledge-skill MCP servers (code-review, security-audit, researcher, etc.)
+ */
+import { frameworkLogger } from '../../core/framework-logger.js';
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import { createRequire } from 'module';
+import { fileURLToPath } from 'node:url';
+import { syncBuiltinSkills } from '../../cli/commands/skill-install.js';
+import { mintAfterWear } from '../../cli/commands/foundry-mint-wear.js';
+// ESM-compatible __dirname (this file is compiled to ESM)
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, '..', '..', '..');
+const requireCjs = createRequire(import.meta.url);
+const { resolveConsumerTargetDir, patchGrokHooks } = requireCjs(path.join(packageRoot, 'scripts/node/install-bridges.cjs'));
+const { XRAY_MCP_SERVERS, resolveRepertoireMcp } = requireCjs(path.join(packageRoot, 'scripts/node/bridge-mcp-wiring.cjs'));
+function registerGrokMcpServers(targetDir) {
+    try {
+        execSync('which grok', { stdio: 'ignore' });
+    }
+    catch {
+        console.log('[Grok] grok CLI not on PATH — plugin .mcp.json still configured');
+        return;
+    }
+    for (const s of XRAY_MCP_SERVERS) {
+        try {
+            const envEntries = { ...s.env, XRAY_ROOT: targetDir };
+            const envFlags = Object.entries(envEntries)
+                .map(([k, v]) => `--env "${k}=${v}"`)
+                .join(' ');
+            execSync(`grok mcp add ${s.name} --command npx --args "-y" "0xray" "mcp" "${s.mcpCmd}" ${envFlags}`, { stdio: 'pipe' });
+        }
+        catch {
+            // already registered or grok config conflict — non-blocking
+        }
+    }
+}
+export async function installForGrokCLI(options = {}) {
+    frameworkLogger.log('grok-integration', 'install-start', 'info', {
+        options: { force: options.force, dryRun: options.dryRun },
+    });
+    const millSuit = requireCjs(path.join(packageRoot, 'scripts/foundry/mint-suit.cjs'));
+    const env = options.env || process.env;
+    const machine = options.machineHome || millSuit.machineHome();
+    const targetDir = options.targetDir || resolveConsumerTargetDir(packageRoot, process.cwd());
+    const dests = millSuit.resolveGrokPluginDests(targetDir, env, machine);
+    for (const dest of dests) {
+        if (millSuit.wouldClobberMachineGrok(dest, env, machine)) {
+            frameworkLogger.log('grok-integration', 'refuse-machine-grok-clobber', 'error', {
+                home: millSuit.processHome(env),
+                machineHome: machine,
+                dest,
+            });
+            throw new Error('foundry-inspect: isolated HOME must not clobber ~/.grok/plugins/0xray');
+        }
+    }
+    // Try to find the plugin source from the installed package
+    const possibleSources = [
+        path.join(__dirname, '..', '..', '..', 'src/integrations/grok/plugin/0xray'), // dev
+        path.join(__dirname, '..', '..', '..', '.grok/plugins/0xray'), // after build
+    ];
+    let sourceDir = possibleSources.find(p => fs.existsSync(p));
+    if (!sourceDir) {
+        console.error('[Grok] Could not locate the 0xray Grok plugin inside the package.');
+        return;
+    }
+    if (options.dryRun) {
+        console.log(`[Grok] Dry run: Would copy plugin from ${sourceDir} → ${dests.join(' , ')}`);
+        return;
+    }
+    const isolated = millSuit.isIsolatedHome(env, machine);
+    try {
+        for (const dest of dests) {
+            const pluginExists = fs.existsSync(dest);
+            if (pluginExists && !options.force) {
+                console.log(`[Grok] 0xray Grok plugin is already installed at ${dest}.`);
+                console.log('Use --force to reinstall plugin files.');
+            }
+            else {
+                fs.cpSync(sourceDir, dest, { recursive: true, force: true });
+                frameworkLogger.log('grok-integration', 'plugin-copied', 'info', { destination: dest });
+                console.log(`\x1b[32m✓ Copied Grok plugin to ${dest}\x1b[0m`);
+            }
+            if (millSuit.wantsCostume(targetDir)) {
+                const skillsCopied = syncBuiltinSkills(path.join(dest, 'skills'));
+                if (skillsCopied > 0) {
+                    console.log(`\x1b[32m✓ Synced ${skillsCopied} builtin skills to Grok plugin\x1b[0m`);
+                }
+                frameworkLogger.log('grok-integration', 'skills-synced', 'info', { count: skillsCopied });
+            }
+            pinGrokPluginToInstalledDist(dest, packageRoot, targetDir);
+            wearGrokHookCommands(dest, packageRoot, targetDir);
+        }
+        if (isolated && millSuit.wantsCostume(targetDir)) {
+            const home = millSuit.processHome(env);
+            const globalCopied = syncBuiltinSkills(path.join(home, '.grok', 'skills'));
+            if (globalCopied > 0) {
+                console.log(`\x1b[32m✓ Synced ${globalCopied} builtin skills to isolated ~/.grok/skills/\x1b[0m`);
+            }
+        }
+        writeProjectRepertoireMcp(targetDir);
+        mintAfterWear(targetDir);
+        const primary = dests[0];
+        try {
+            execSync(`grok plugins trust "${primary}"`, { stdio: 'ignore' });
+            console.log('\x1b[32m✓ Auto-trusted the 0xray plugin with Grok CLI\x1b[0m');
+        }
+        catch {
+            console.log('\nPlease run this command to fully trust the plugin:');
+            console.log(`  grok plugins trust "${primary}"`);
+        }
+        if (isolated) {
+            registerGrokMcpServers(targetDir);
+            console.log('\x1b[32m✓ Registered 7 xray MCP servers with Grok CLI (npx)\x1b[0m');
+        }
+        else {
+            console.log('\x1b[32m✓ Project-scoped Grok plugin worn (machine ~/.grok/plugins/0xray not written)\x1b[0m');
+        }
+        console.log('\n✅ 0xRay is now installed as a first-class Grok CLI plugin!');
+        console.log('Restart Grok or run `grok` to load the new hooks and MCP servers.');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        frameworkLogger.log('grok-integration', 'install-error', 'error', { error: message });
+        console.error('Failed to install Grok plugin:', message);
+    }
+    frameworkLogger.log('grok-integration', 'install-complete', 'info', {});
+}
+function wearGrokHookCommands(pluginDir, xrayRoot, targetDir) {
+    patchGrokHooks(pluginDir, xrayRoot, targetDir, (label, action, status, details) => {
+        const level = status === 'success' ||
+            status === 'error' ||
+            status === 'info' ||
+            status === 'debug' ||
+            status === 'warning'
+            ? status
+            : 'info';
+        frameworkLogger.log(label, action, level, details ?? {});
+    }, 'grok-install');
+}
+function pinGrokPluginToInstalledDist(pluginDir, xrayRoot, targetDir) {
+    const hookJs = path.join(xrayRoot, 'dist/integrations/grok/hooks/pre-tool-use.js');
+    const cliJs = path.join(xrayRoot, 'dist/cli/index.js');
+    const hooksPath = path.join(pluginDir, 'hooks', 'hooks.json');
+    if (fs.existsSync(hookJs) && fs.existsSync(hooksPath)) {
+        const text = fs.readFileSync(hooksPath, 'utf8');
+        fs.writeFileSync(hooksPath, text.split('${XRAY_AI_PATH:-node_modules/0xray}').join(xrayRoot));
+    }
+    const mcpPath = path.join(pluginDir, '.mcp.json');
+    if (!fs.existsSync(mcpPath))
+        return;
+    const mcp = JSON.parse(fs.readFileSync(mcpPath, 'utf8'));
+    for (const server of Object.values(mcp.mcpServers ?? {})) {
+        server.env = { ...server.env, XRAY_ROOT: targetDir };
+        if (fs.existsSync(cliJs) &&
+            server.command === 'npx' &&
+            Array.isArray(server.args) &&
+            server.args.includes('mcp')) {
+            const mcpIdx = server.args.indexOf('mcp');
+            const mcpCmd = server.args[mcpIdx + 1] ?? 'governance';
+            server.command = 'node';
+            server.args = [cliJs, 'mcp', mcpCmd];
+        }
+    }
+    const repertoireMcp = resolveRepertoireMcp(targetDir);
+    if (mcp.mcpServers) {
+        if (repertoireMcp) {
+            mcp.mcpServers.repertoire = {
+                command: 'node',
+                args: [repertoireMcp],
+            };
+        }
+        else {
+            delete mcp.mcpServers.repertoire;
+        }
+    }
+    fs.writeFileSync(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
+}
+/** Grok TUI reads <project>/.grok/config.toml, not the package copy. */
+export function writeProjectRepertoireMcp(projectRoot) {
+    const repertoireMcp = resolveRepertoireMcp(projectRoot);
+    if (!repertoireMcp)
+        return null;
+    const grokDir = path.join(projectRoot, '.grok');
+    fs.mkdirSync(grokDir, { recursive: true });
+    const tomlPath = path.join(grokDir, 'config.toml');
+    const block = `[mcp_servers.repertoire]
+command = "node"
+args = [${JSON.stringify(repertoireMcp)}]
+enabled = true
+`;
+    let existing = '';
+    if (fs.existsSync(tomlPath)) {
+        existing = fs.readFileSync(tomlPath, 'utf8');
+    }
+    if (/\[mcp_servers\.repertoire\]/.test(existing)) {
+        existing = existing.replace(/\[mcp_servers\.repertoire\][\s\S]*?(?=\n\[|$)/, block.trim());
+        fs.writeFileSync(tomlPath, existing.endsWith('\n') ? existing : `${existing}\n`);
+    }
+    else {
+        const prefix = existing.trim() ? `${existing.trim()}\n\n` : '';
+        fs.writeFileSync(tomlPath, `${prefix}${block}`);
+    }
+    return tomlPath;
+}
+export default {
+    installForGrokCLI,
+    writeProjectRepertoireMcp,
+};

package/dist/integrations/grok/hooks/grok-hook-activity.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * Sync activity.log writer for Grok hooks (hooks exit before frameworkLogger flush).
+ * Format matches frameworkLogger.bufferEntry output.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+function formatLine(component, action, status, details, jobId) {
+  const ts = new Date().toISOString();
+  const jobPart = jobId ? `[${jobId}] ` : '';
+  const detailsPart = details
+    ? ` | ${(() => {
+        try {
+          return JSON.stringify(details);
+        } catch {
+          return String(details);
+        }
+      })()}`
+    : '';
+  return `${ts} ${jobPart}[${component}] ${action} - ${status.toUpperCase()}${detailsPart}\n`;
+}
+
+export function appendHookActivity(root, component, action, status, details = {}) {
+  const workspace = root || process.cwd();
+  const logDir = path.join(workspace, 'logs', 'framework');
+  const logFile = path.join(logDir, 'activity.log');
+  try {
+    fs.mkdirSync(logDir, { recursive: true });
+    const jobId = `hook-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    fs.appendFileSync(logFile, formatLine(component, action, status, details, jobId));
+    return jobId;
+  } catch {
+    return null;
+  }
+}
+
+export function activityLogHasPattern(root, pattern, tailBytes = 65536) {
+  const logFile = path.join(root, 'logs', 'framework', 'activity.log');
+  if (!fs.existsSync(logFile)) return false;
+  try {
+    const stat = fs.statSync(logFile);
+    const start = Math.max(0, stat.size - tailBytes);
+    const fd = fs.openSync(logFile, 'r');
+    const buf = Buffer.alloc(stat.size - start);
+    fs.readSync(fd, buf, 0, buf.length, start);
+    fs.closeSync(fd);
+    return pattern.test(buf.toString('utf8'));
+  } catch {
+    return false;
+  }
+}

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

@@ -0,0 +1,372 @@
+#!/usr/bin/env node
+/**
+ * Shared utilities for Grok CLI hooks — codex load, features, surface checks.
+ * Pure JS (no TS build) so hooks run from dist/ without compilation surprises.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import {
+  checkPendingDelegationGate,
+  checkSubagentGate,
+  satisfyDelegationsFromToolInput,
+  isSubagentTool,
+  isOrchestrateToolEvent,
+  isReadOnlyTool,
+  isShellTool,
+  getActivePendingDelegations,
+  validateSpawnMatchesTodo,
+  updatePlanTodoStatusInPlace,
+  loadDelegationGateFeatures,
+} from '../../hooks/delegation-gate-runtime.mjs';
+import { isConferPendingForSession } from '../../hooks/confer-hook-runtime.mjs';
+import { getActiveUserAsideBoot } from '../../hooks/user-aside-hook-runtime.mjs';
+import {
+  applyStationHeat,
+  buildRepertoireResume as stationRepertoireResume,
+  readExistingBoot,
+  writeStationMarkdown,
+} from '../../hooks/station-hook-runtime.mjs';
+
+export {
+  checkPendingDelegationGate,
+  checkSubagentGate,
+  satisfyDelegationsFromToolInput,
+  isSubagentTool,
+  isOrchestrateToolEvent,
+  isReadOnlyTool,
+  isShellTool,
+  getActivePendingDelegations,
+  validateSpawnMatchesTodo,
+  updatePlanTodoStatusInPlace,
+};
+
+export const LEAD_DEV_RULES = [
+  'Phased plan + todos; assign best subagent; monitor output',
+  'Lead dev loops test→fix until green; no permission pings',
+  'Per-suite test triage; full suite last',
+  'Lead stays main; subagents execute; update todos',
+  'Read all output; triage fix rerun',
+  'No buck-passing — resolve every error',
+  'Zero open errors at phase completion',
+];
+
+/** Blocking codex patterns detectable in proposed edits (term → regex + message) */
+export const CODEX_BLOCK_PATTERNS = [
+  { terms: [11], pattern: /:\s*any\b|as\s+any\b/g, message: 'Codex 11 Type Safety: no `any` types' },
+  { terms: [11], pattern: /@ts-ignore|@ts-expect-error/g, message: 'Codex 11 Type Safety: no @ts-ignore / @ts-expect-error' },
+  { terms: [29], pattern: /\beval\s*\(/g, message: 'Codex 29 Security: eval() prohibited' },
+  { terms: [2], pattern: /\bTODO\b|\bFIXME\b|\bSTUB\b/g, message: 'Codex 2: no TODO/FIXME/STUB in production code' },
+  { terms: [7], pattern: /console\.log\s*\(/g, message: 'Codex 7: no console.log debugging' },
+];
+
+/** New-surface paths blocked when no_new_surface is on (codex 69) */
+export const SURFACE_DENY_PATTERNS = [
+  { pattern: /(?:^|\/)src\/mcps\/[^/]+\.server\.(ts|js)$/i, message: 'Codex 69: new MCP server — rewire existing mcps/' },
+  { pattern: /(?:^|\/)src\/skills\/[^/]+\/SKILL\.md$/i, message: 'Codex 69: new skill — extend orchestrator skill or existing mcps' },
+  { pattern: /(?:^|\/)src\/mcps\/orchestrator\/handlers\/[^/]+-handler\.(ts|js)$/i, message: 'Codex 69: new orchestrator handler — merge into complexity-handler' },
+  { pattern: /(?:^|\/)src\/nucleus\/autonomy-kernel\.(ts|js)$/i, message: 'Codex 69: parallel autonomy kernel — use existing nucleus' },
+  { pattern: /(?:^|\/)src\/mcps\/[^/]+\/handlers\/autonomy-handler\.(ts|js)$/i, message: 'Codex 69: autonomy-handler removed — use complexity-handler' },
+];
+
+const SUBAGENT_TOOLS = new Set([
+  'spawn_subagent',
+  'task',
+  'Task',
+]);
+
+const WRITE_TOOLS = new Set([
+  'search_replace',
+  'write',
+  'Write',
+  'Edit',
+  'MultiEdit',
+  'edit_notebook',
+  'EditNotebook',
+]);
+
+export function workspaceRoot() {
+  return (
+    process.env.GROK_WORKSPACE_ROOT ||
+    process.env.CLAUDE_PROJECT_DIR ||
+    process.env.XRAY_ROOT ||
+    process.cwd()
+  );
+}
+
+export function resolveFeaturesPath(root = workspaceRoot()) {
+  for (const p of [
+    path.join(root, '.xray', 'features.json'),
+    path.join(process.cwd(), '.xray', 'features.json'),
+  ]) {
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+export function resolveCodexPath(root = workspaceRoot()) {
+  for (const p of [
+    path.join(root, '.xray', 'codex.json'),
+    path.join(process.cwd(), '.xray', 'codex.json'),
+  ]) {
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+export function resolveSiblingWorkspaceRoots(root = workspaceRoot()) {
+  const featuresPath = resolveFeaturesPath(root);
+  if (!featuresPath) return [];
+  try {
+    const data = JSON.parse(fs.readFileSync(featuresPath, 'utf8'));
+    const siblings = data.multi_agent_orchestration?.sibling_repos ?? [];
+    if (!Array.isArray(siblings)) return [];
+    const resolved = [];
+    for (const entry of siblings) {
+      const rel = typeof entry === 'string' ? entry : entry?.path;
+      if (!rel || typeof rel !== 'string') continue;
+      const abs = path.isAbsolute(rel) ? rel : path.resolve(root, rel);
+      if (!fs.existsSync(abs)) continue;
+      resolved.push({
+        path: abs,
+        label: typeof entry === 'object' && entry.label ? entry.label : path.basename(abs),
+      });
+    }
+    return resolved;
+  } catch {
+    return [];
+  }
+}
+
+export function buildRepertoireResume(root = workspaceRoot()) {
+  return stationRepertoireResume(root);
+}
+
+export function loadFeatures(root = workspaceRoot()) {
+  const featuresPath = resolveFeaturesPath(root);
+  if (!featuresPath) {
+    return {
+      lead_dev_mode: true,
+      no_new_surface: true,
+      per_suite_triage: true,
+      grok_postprocessor_light: false,
+    };
+  }
+  try {
+    const data = JSON.parse(fs.readFileSync(featuresPath, 'utf8'));
+    const orch = data.multi_agent_orchestration ?? {};
+    return {
+      lead_dev_mode: orch.enabled !== false && orch.lead_dev_mode !== false,
+      no_new_surface: orch.no_new_surface !== false,
+      per_suite_test_triage: orch.per_suite_test_triage !== false,
+      auto_chain_delegations: orch.auto_chain_delegations !== false,
+      grok_postprocessor_light: data.grok_postprocessor_light === true,
+      sibling_repos: resolveSiblingWorkspaceRoots(root),
+    };
+  } catch {
+    return {
+      lead_dev_mode: true,
+      no_new_surface: true,
+      per_suite_triage: true,
+      auto_chain_delegations: true,
+      grok_postprocessor_light: false,
+      sibling_repos: [],
+    };
+  }
+}
+
+export function loadBlockingCodexTerms() {
+  const codexPath = resolveCodexPath();
+  if (!codexPath) return [];
+  try {
+    const data = JSON.parse(fs.readFileSync(codexPath, 'utf8'));
+    const terms = data.terms ?? {};
+    return Object.values(terms).filter(
+      (t) => t.enforcementLevel === 'blocking' || t.zeroTolerance === true,
+    );
+  } catch {
+    return [];
+  }
+}
+
+export function extractToolContext(event) {
+  const toolName = event.toolName || process.env.TOOL_NAME || 'unknown';
+  const toolInput = event.toolInput ?? {};
+  const paths = [];
+  let content = '';
+
+  if (toolInput.path) paths.push(String(toolInput.path));
+  if (toolInput.file_path) paths.push(String(toolInput.file_path));
+  if (toolInput.target_notebook) paths.push(String(toolInput.target_notebook));
+  if (Array.isArray(toolInput.paths)) paths.push(...toolInput.paths.map(String));
+
+  if (toolInput.new_string) content += String(toolInput.new_string);
+  if (toolInput.contents) content += String(toolInput.contents);
+  if (toolInput.command) content += String(toolInput.command);
+  if (toolInput.prompt) content += String(toolInput.prompt);
+
+  return { toolName, toolInput, paths, content, cmd: String(toolInput.command || '') };
+}
+
+export function checkCodexPatterns(content, options = {}) {
+  if (!content) return null;
+  const only = Array.isArray(options.terms) ? options.terms : null;
+  for (const { message, pattern, terms } of CODEX_BLOCK_PATTERNS) {
+    if (only && !terms.some((n) => only.includes(n))) continue;
+    if (pattern.test(content)) return message;
+    pattern.lastIndex = 0;
+  }
+  return null;
+}
+
+export function checkSurfaceArea(paths, root = workspaceRoot()) {
+  for (const rel of paths) {
+    const normalized = rel.replace(/\\/g, '/');
+    const abs = path.isAbsolute(rel) ? rel : path.join(root, rel);
+    if (fs.existsSync(abs)) continue;
+    for (const { pattern, message } of SURFACE_DENY_PATTERNS) {
+      if (pattern.test(normalized)) return `${message} (blocked: ${normalized})`;
+    }
+  }
+  return null;
+}
+
+export function checkFullTestSuite(cmd, features) {
+  if (!features.per_suite_test_triage) return null;
+  const cmdText = cmd.toLowerCase();
+  const isFullTestSuite =
+    /\b(npm\s+(run\s+)?test|vitest\s+run|pnpm\s+test|yarn\s+test)\b/.test(cmdText) &&
+    !/--\s+\S+\.test/.test(cmdText) &&
+    !/vitest\s+run\s+\S+\.test/.test(cmdText);
+  if (!isFullTestSuite) return null;
+  return (
+    'Lead-dev test protocol: run individual test files first; ' +
+    'full suite only after per-suite passes (override with focused test path)'
+  );
+}
+
+export function isWriteTool(toolName) {
+  return WRITE_TOOLS.has(toolName) || /write|edit|replace/i.test(toolName);
+}
+
+export async function readStdinJson() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const raw = Buffer.concat(chunks).toString('utf8').trim();
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+export function sessionBootPath(root = workspaceRoot()) {
+  return path.join(root, '.xray', 'state', 'session-boot.json');
+}
+
+export function loadConferPending(root = workspaceRoot(), sessionId = null) {
+  try {
+    return isConferPendingForSession(root, sessionId);
+  } catch {
+    return false;
+  }
+}
+
+export function buildSessionBootPayload(root, source = '0xray/grok-session-start', extra = {}) {
+  const features = loadFeatures(root);
+  const blockingTerms = loadBlockingCodexTerms();
+  const siblingRoots = features.sibling_repos ?? resolveSiblingWorkspaceRoots(root);
+  const sessionId =
+    extra.sessionId || process.env.GROK_SESSION_ID || process.env.GROK_SESSION || null;
+  const conferPending = loadConferPending(root, sessionId);
+  const userAsideBoot = getActiveUserAsideBoot(root, sessionId);
+  const gateFeatures = loadDelegationGateFeatures(root, 'grok');
+  const frontier = gateFeatures.ceremony === 'lite';
+  const existing = readExistingBoot(root);
+  const heat = applyStationHeat(root, extra.host || 'grok', extra, existing);
+  return {
+    hook: source,
+    lead_dev_mode: features.lead_dev_mode,
+    no_new_surface: features.no_new_surface,
+    host: extra.host || 'grok',
+    suit_profile: gateFeatures.suit_profile ?? 'guided',
+    ceremony: gateFeatures.ceremony ?? 'full',
+    spawn_plan_mode: gateFeatures.spawn_plan_mode ?? 'deny',
+    codexBlockingTermCount: blockingTerms.length,
+    codexTerms: [59, 67, 68, 69],
+    rules: features.lead_dev_mode ? LEAD_DEV_RULES : [],
+    mcpIntake: frontier
+      ? 'xray-orchestrator analyze-complexity optional on frontier (spawn warns, does not deny)'
+      : 'xray-orchestrator → analyze-complexity (required before spawn_subagent)',
+    enforcement: 'PreToolUse hook — Codex constitution always on; ceremony scales by suit_temperament',
+    workspaceRoot: root,
+    ...heat,
+    ...(siblingRoots.length > 0 ? { siblingWorkspaceRoots: siblingRoots } : {}),
+    ...(conferPending ? { conferPending: true, conferTrigger: 'analyze-complexity at synthesis checkpoint' } : {}),
+    ...(userAsideBoot ?? {}),
+    sessionId,
+    timestamp: new Date().toISOString(),
+    source,
+    ...extra,
+    ...heat,
+  };
+}
+
+export function writeSessionBoot(root, payload) {
+  try {
+    const stateDir = path.join(root, '.xray', 'state');
+    fs.mkdirSync(stateDir, { recursive: true });
+    fs.writeFileSync(sessionBootPath(root), JSON.stringify(payload, null, 2));
+    writeStationMarkdown(root, payload);
+    return sessionBootPath(root);
+  } catch {
+    return null;
+  }
+}
+
+export function sessionBootNeedsRefresh(existing, root) {
+  if (!existing || typeof existing !== 'object') return true;
+  if (existing.lead_dev_mode === undefined) return true;
+  if (existing.host !== 'grok') return true;
+  if (!existing.suit_profile) return true;
+  if (existing.workspaceRoot && existing.workspaceRoot !== root) return true;
+  if (!existing.repertoireResume) return true;
+  if (!existing.stationLine) return true;
+  return false;
+}
+
+/** Boot on SessionStart, UserPromptSubmit, or first PreToolUse if missing/stale. */
+export function ensureSessionBoot(root = workspaceRoot(), source = '0xray/grok-boot') {
+  const bootPath = sessionBootPath(root);
+  if (fs.existsSync(bootPath)) {
+    try {
+      const existing = JSON.parse(fs.readFileSync(bootPath, 'utf8'));
+      if (!sessionBootNeedsRefresh(existing, root)) return bootPath;
+    } catch {
+      /* rewrite corrupt boot */
+    }
+  }
+  return writeSessionBoot(root, buildSessionBootPayload(root, source));
+}
+
+export function resolveSessionId(event) {
+  return (
+    event.sessionId ||
+    process.env.GROK_SESSION_ID ||
+    null
+  );
+}
+
+export function clearPendingDelegationsForSessionChange(newSessionId, root = workspaceRoot()) {
+  const filePath = path.join(root, '.xray', 'state', 'pending-delegations.json');
+  if (!fs.existsSync(filePath)) return false;
+  try {
+    const state = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    if (newSessionId && state.sessionId === newSessionId) return false;
+    fs.unlinkSync(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}