0xray 4.0.30 → 4.0.31

package/.grok-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "0xray",
-  "version": "4.0.30",
+  "version": "4.0.31",
   "description": "0xRay suit for Grok, Hermes, OpenClaw, OpenCode: mill+inspect, Codex, 7 MCP servers. Costume 45/42 is opt-in foundry, not the default wear.",
   "author": {
     "name": "0xRay AI",

package/.opencode/skills/orchestrator/SKILL.md

@@ -53,6 +53,18 @@ When `multi_agent_orchestration.lead_dev_mode` is true in `features.json` (defau
 | Test failures | bug-triage |
 | Review | code-review |
 
+## Goggles
+
+Pushed on `feat/goggles-look`. Not merged. Not published. Grok CLI has not shipped this. Wear the local build. From the worn checkout run `node dist/integrations/hooks/goggles-pipeline.mjs`. Do not run `npx 0xray goggles`. If `dist` is older than `src/integrations/hooks/goggles-pipeline.mjs`, build that tree and wear that `dist`. A subagent wears this same local build.
+
+Kind 0 is actuality. It compares the list in the file to the same six names in the code. It speaks only when those lists differ. A match is quiet. It does not read the suit that is running. It is not a plate type.
+
+Kind 1 names one plane: dichotomy, syncopate, synthesis, or loop. The lens holds that plane. An action on that plane is quiet. An action on another plane, or on a pipeline drawing, is stopped. A pipeline drawing is not a scope stop. Ground is not a scope stop. Scope, when named, is ecosystem, part, one flow, or one artifact, and an action wider than that scope is stopped. One kind and one scope level at a time. Two planes, calling, ground, and a pipeline name do not arm the lens. `outer` without one plane is `Name one plane.` After 1 is empty. Nothing is picked. Calling stays off.
+
+`digest` and `triage` return the card already built by `assemblePlane`. The fields are from, digest, plate, entry, exit, files, skills, setup, teardown, and worn. Empty stays empty. The rows are ground, routing, house, boot, governance, memory-recall, orchestration, processor, and reporting. Those nine are not Kind 0. `digest` fills the card. Entry and exit are the plate's input and output box titles when that plate has them. Setup and teardown stay empty unless the row names them. The mill path is `scripts/foundry`. `triage` adds the empty fields and whether the row holds. Zoom after the card is the same ladder: ecosystem, part, one flow, one artifact. One file is one artifact. Several files are not narrowed to a guessed file.
+
+The hold lasts for the work that named the plane. It does not stop one tool and then forget. Work that says goggles clears the hold and stays quiet. The suit does not invent the plane.
+
 ## Hooks (rewired, not new MCPs)
 
 - **SessionStart** → `session-start.js` boots lead_dev_mode

package/.xray/features.json

@@ -1,6 +1,6 @@
 {
   "$schema": "./features.schema.json",
-  "version": "4.0.30",
+  "version": "4.0.31",
   "description": "0xRay Framework - Unified Feature Configuration",
   "suit_temperament": {
     "profile": "auto",

package/dist/CHANGELOG.md

@@ -7,6 +7,7 @@ The format is based on [Conventional Commits](https://www.conventionalcommits.or
 ## [Unreleased]
 
 ### Features
+- **Goggles.** Proposed plates for goggles, suit, kits, host pack, and glossary. Goggles views one plane. Recall opens a plate when speech names that plate. Plates only. Not a new skill.
 - **Plates.** Pipeline schematics live in `docs-site/docs/plates/` (routing, governance, boot, orchestration, processor, reporting, memory-recall). Station keeps one pointer line. Pre-compact and the `MEMORY_ROUTING` inject carry that one schematic. A lesson is an episode. A plate is the machine. Not a new skill.
 - **Vendored Repertoire 0.2.8.** `vendor/@0xray/repertoire` is that package. Lesson lines and retained ids stay at 20. Speech that names nothing mints a learned signal, and only those mints evict past 24. Not a new skill.
 - **Feat rebase.** When the mandated work turns into mantra, or the job has split across planes that no longer share one present, stop and answer the original message again from this seat. On `LEAD-CADENCE.md`, the orchestrator skill, and the ship-ready mill gate. Project dest grows the name `feat-rebase` from the stack overlay. Not a new skill.
@@ -41,6 +42,14 @@ The format is based on [Conventional Commits](https://www.conventionalcommits.or
 - Archive root `integrations/` costume SKILL dump → `docs/archive/integrations-costume/`. Live wear is `src/integrations`.
 - Archive root `commands/` stale copy → `docs/archive/commands-copy/`. Live wear is `src/opencode/commands`.
 
+## [4.0.31] - 2026-10-01
+
+Next patch after npm `4.0.30`. Not published from this commit.
+
+Goggles looks at one pipeline. Kind 0 name-checks the six outer names and stays quiet when the worn list matches the map. Digest and triage return one card. A leave is denied. Session boot hands the card through `handCard` and normalizes the workspace root, including a trailing slash. The mill path is `scripts/foundry`. Run `node dist/integrations/hooks/goggles-pipeline.mjs`. This cut also carries the plate docs and the live project-file signal count that landed on main after 4.0.30. Calling and confer stay off. Companion `@0xray/grok-bot` is unchanged at 0.1.8.
+
+---
+
 ## [4.0.30] - 2026-09-28
 
 Next patch after npm `4.0.29`. Released 2026-09-28.

package/dist/cli/commands/validate.js

@@ -25,6 +25,11 @@ export const VALIDATE_PACK_PATHS = [
     "dist/integrations/hooks/plates.cjs",
     "docs-site/docs/plates/memory-recall.md",
     "docs-site/docs/plates/processor.md",
+    "docs-site/docs/plates/goggles.md",
+    "docs-site/docs/plates/suit.md",
+    "docs-site/docs/plates/kits.md",
+    "docs-site/docs/plates/host-pack.md",
+    "docs-site/docs/plates/glossary.md",
 ];
 export const CONSUMER_WEAR_PATHS = [
     "AGENTS.md",

package/dist/cli/index.js

@@ -5,7 +5,7 @@
  * Provides commands for installing and managing xray framework
  */
 import { Command } from "commander";
-import { execSync, spawn } from "child_process";
+import { execSync, spawn, spawnSync } from "child_process";
 import { join, resolve } from "path";
 import { fileURLToPath } from "node:url";
 import { readFileSync, existsSync } from "fs";
@@ -76,6 +76,21 @@ program
         process.exit(1);
     }
 });
+program
+    .command("goggles")
+    .argument("[args...]", "plane, then examine, triage, cascade, or teardown")
+    .description("Glimpse every plane, or one plane's way in. A hit does not open the plane.")
+    .action((args) => {
+    const built = join(packageRoot, "dist", "integrations", "hooks", "goggles-pipeline.mjs");
+    const source = join(packageRoot, "src", "integrations", "hooks", "goggles-pipeline.mjs");
+    const script = existsSync(built) ? built : source;
+    const result = spawnSync(process.execPath, [script, ...(args ?? [])], { encoding: "utf8" });
+    if (result.stdout)
+        process.stdout.write(result.stdout);
+    if (result.stderr)
+        process.stderr.write(result.stderr);
+    process.exit(result.status ?? 1);
+});
 program
     .command("wear")
     .description("Wear the 0xray suit in this git checkout")

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

@@ -28,6 +28,7 @@ import {
   retainCompactFields,
   writeStationMarkdown,
 } from '../../hooks/station-hook-runtime.mjs';
+import { handCard } from '../../hooks/goggles-pipeline.mjs';
 
 export {
   checkPendingDelegationGate,
@@ -86,12 +87,18 @@ const WRITE_TOOLS = new Set([
   'EditNotebook',
 ]);
 
+export function normalizeWorkspaceRoot(root) {
+  const raw = String(root || '').trim();
+  if (!raw) return raw;
+  return path.resolve(raw);
+}
+
 export function workspaceRoot() {
-  return (
+  return normalizeWorkspaceRoot(
     process.env.GROK_WORKSPACE_ROOT ||
     process.env.CLAUDE_PROJECT_DIR ||
     process.env.XRAY_ROOT ||
-    process.cwd()
+    process.cwd(),
   );
 }
 
@@ -198,6 +205,7 @@ export function extractToolContext(event) {
 
   if (toolInput.path) paths.push(String(toolInput.path));
   if (toolInput.file_path) paths.push(String(toolInput.file_path));
+  if (toolInput.target_file) paths.push(String(toolInput.target_file));
   if (toolInput.target_notebook) paths.push(String(toolInput.target_notebook));
   if (Array.isArray(toolInput.paths)) paths.push(...toolInput.paths.map(String));
 
@@ -301,7 +309,7 @@ export function buildSessionBootPayload(root, source = '0xray/grok-session-start
       ? '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,
+    workspaceRoot: normalizeWorkspaceRoot(root),
     ...heat,
     ...(siblingRoots.length > 0 ? { siblingWorkspaceRoots: siblingRoots } : {}),
     ...(conferPending ? { conferPending: true, conferTrigger: 'analyze-complexity at synthesis checkpoint' } : {}),
@@ -322,6 +330,11 @@ export function writeSessionBoot(root, payload) {
     fs.mkdirSync(stateDir, { recursive: true });
     fs.writeFileSync(sessionBootPath(root), JSON.stringify(payload, null, 2));
     writeStationMarkdown(root, payload);
+    try {
+      handCard(root, payload && (payload.cardText || payload.intent));
+    } catch {
+      /* a missed card must not fail the boot */
+    }
     return sessionBootPath(root);
   } catch {
     return null;
@@ -333,9 +346,16 @@ export function sessionBootNeedsRefresh(existing, root) {
   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.workspaceRoot &&
+    normalizeWorkspaceRoot(existing.workspaceRoot) !== normalizeWorkspaceRoot(root)
+  ) {
+    return true;
+  }
   if (!existing.repertoireResume) return true;
   if (!existing.stationLine) return true;
+  const liveResume = buildRepertoireResume(root);
+  if (liveResume && existing.repertoireResume !== liveResume) return true;
   return false;
 }
 

package/dist/integrations/grok/hooks/post-tool-use.js

@@ -10,6 +10,7 @@ import {
   isSubagentTool,
   isWriteTool,
   loadFeatures,
+  normalizeWorkspaceRoot,
   readStdinJson,
   resolveSessionId,
   workspaceRoot,
@@ -33,7 +34,7 @@ function extractToolOutput(event) {
 }
 
 export function handlePostToolUse(event, root = workspaceRoot()) {
-  const eventRoot = event.workspaceRoot || event.cwd || root;
+  const eventRoot = normalizeWorkspaceRoot(event.workspaceRoot || event.cwd || root);
   const sessionId = resolveSessionId(event);
   const { toolName, toolInput } = extractToolContext(event);
 

package/dist/integrations/grok/hooks/pre-tool-use.js

@@ -15,11 +15,72 @@ import {
   isShellTool,
   isWriteTool,
   loadFeatures,
+  normalizeWorkspaceRoot,
   readStdinJson,
   resolveSessionId,
   workspaceRoot,
 } from './grok-hook-utils.js';
 import { appendHookActivity } from './grok-hook-activity.js';
+import { cardStop } from '../../hooks/goggles-pipeline.mjs';
+import { createRequire } from 'node:module';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const hookDir = dirname(fileURLToPath(import.meta.url));
+let scoreAndRouteFn;
+
+function loadScoreAndRoute() {
+  if (scoreAndRouteFn !== undefined) return scoreAndRouteFn;
+  scoreAndRouteFn = null;
+  const require = createRequire(import.meta.url);
+  const candidates = [
+    join(hookDir, '../../../nucleus/thin-dispatch.js'),
+    join(hookDir, '../../../../dist/nucleus/thin-dispatch.js'),
+  ];
+  for (const candidate of candidates) {
+    if (!existsSync(candidate)) continue;
+    try {
+      const loaded = require(candidate);
+      if (typeof loaded.scoreAndRoute === 'function') {
+        scoreAndRouteFn = loaded.scoreAndRoute;
+        return scoreAndRouteFn;
+      }
+    } catch {
+      /* next built copy */
+    }
+  }
+  return null;
+}
+
+/** Speak only when the organ changes the agent. A match that leaves the agent is quiet. */
+export function repertoireDecisionFields(routed) {
+  if (!routed?.memoryRouting?.overridden || !routed.agent) return null;
+  const signals = Array.isArray(routed.memoryRouting.signals)
+    ? routed.memoryRouting.signals.slice(0, 4).filter(Boolean)
+    : [];
+  const why = signals.length ? ` on ${signals.join(', ')}` : '';
+  return {
+    agent: routed.agent,
+    gate: 'repertoire',
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      additionalContext: `Repertoire changed the route to ${routed.agent}${why}. Follow that agent for this work.`,
+    },
+  };
+}
+
+function repertoireRoute(operation) {
+  const text = String(operation || '').slice(0, 500).trim();
+  if (!text) return null;
+  try {
+    const scoreAndRoute = loadScoreAndRoute();
+    if (!scoreAndRoute) return null;
+    return repertoireDecisionFields(scoreAndRoute(text, {}));
+  } catch {
+    return null;
+  }
+}
 
 function finish(root, decision, reason, hint, toolName, extra = {}) {
   const out = { decision, ...extra };
@@ -30,6 +91,7 @@ function finish(root, decision, reason, hint, toolName, extra = {}) {
     tool: toolName,
     reason: reason || hint || null,
     gate: extra.gate || null,
+    agent: extra.agent || null,
     livePath: true,
   });
   process.exit(0);
@@ -41,7 +103,7 @@ async function main() {
 
   try {
     const event = await readStdinJson();
-    const eventRoot = event.workspaceRoot || event.cwd || root;
+    const eventRoot = normalizeWorkspaceRoot(event.workspaceRoot || event.cwd || root);
     ensureSessionBoot(eventRoot, '0xray/grok-pre-tool-use-boot');
 
     const features = loadFeatures(eventRoot);
@@ -75,9 +137,28 @@ async function main() {
       if (extraBlock) finish(eventRoot, 'deny', extraBlock, null, toolName);
     }
 
+    const stop = cardStop(
+      eventRoot,
+      toolName,
+      [cmd, content, toolInput.pattern, toolInput.query, ...(ctx.paths || [])].filter(Boolean).join('\n'),
+      ctx.paths || [],
+      toolInput,
+    );
+    if (stop?.decision === 'deny') {
+      finish(eventRoot, 'deny', stop.reason, null, toolName, { gate: stop.gate });
+    }
+    if (stop?.decision === 'allow') {
+      finish(eventRoot, 'allow', null, null, toolName, {
+        gate: stop.gate,
+        hookSpecificOutput: stop.hookSpecificOutput,
+      });
+    }
+
+    const route = repertoireRoute([toolName, cmd, content].filter(Boolean).join(' '));
+
     if (isShellTool(toolName) && cmd) {
       const testHint = checkFullTestSuite(cmd, features);
-      if (testHint) finish(eventRoot, 'allow', null, testHint, toolName);
+      if (testHint) finish(eventRoot, 'allow', null, testHint, toolName, route || {});
     }
 
     if (gateBlock.reason) {
@@ -87,11 +168,11 @@ async function main() {
         gateBlock.reason,
         gateBlock.hint,
         toolName,
-        { gate: gateBlock.gate, warn: true },
+        { gate: gateBlock.gate, warn: true, ...(route || {}) },
       );
     }
 
-    finish(eventRoot, 'allow', null, null, toolName);
+    finish(eventRoot, 'allow', null, null, toolName, route || {});
   } catch (err) {
     appendHookActivity(root, 'grok-pre-tool-use', 'hook-error', 'error', {
       tool: toolName,
@@ -116,6 +197,7 @@ function extractFromEvent(event) {
 
   if (toolInput.path) paths.push(String(toolInput.path));
   if (toolInput.file_path) paths.push(String(toolInput.file_path));
+  if (toolInput.target_file) paths.push(String(toolInput.target_file));
   if (toolInput.target_notebook) paths.push(String(toolInput.target_notebook));
   if (Array.isArray(toolInput.paths)) paths.push(...toolInput.paths.map(String));
 
@@ -133,4 +215,7 @@ function extractFromEvent(event) {
   };
 }
 
-main();
+const launchedAsCli = Boolean(process.argv[1] && process.argv[1].endsWith('pre-tool-use.js'));
+if (launchedAsCli) {
+  main();
+}

package/dist/integrations/grok/hooks/session-start.js

@@ -10,6 +10,7 @@ import {
   ensureSessionBoot,
   readStdinJson,
   resolveSessionId,
+  normalizeWorkspaceRoot,
   workspaceRoot,
   writeSessionBoot,
 } from './grok-hook-utils.js';
@@ -21,6 +22,7 @@ import {
   scheduleAutonomousReportingMarker,
   runInferenceImprovementLight,
 } from '../../hooks/pipeline-hook-runtime.mjs';
+import { maintainLens } from '../../hooks/goggles-pipeline.mjs';
 
 function resolveHookEvent(event) {
   if (process.env.GROK_HOOK_EVENT) return process.env.GROK_HOOK_EVENT;
@@ -115,7 +117,7 @@ async function main() {
   try {
     const event = await readStdinJson();
     HOOK_EVENT = resolveHookEvent(event);
-    const eventRoot = event.workspaceRoot || event.cwd || root;
+    const eventRoot = normalizeWorkspaceRoot(event.workspaceRoot || event.cwd || root);
     const sessionId = resolveSessionId(event);
     if (HOOK_EVENT === 'user_prompt_submit' && sessionId) {
       recordSynthesisTurnSlice(eventRoot, sessionId);
@@ -149,7 +151,7 @@ async function main() {
     const payload = buildSessionBootPayload(eventRoot, source, {
       hookEvent: HOOK_EVENT,
       sessionId: event.sessionId || process.env.GROK_SESSION_ID || null,
-      ...(intent ? { intent } : {}),
+      ...(intent ? { intent, cardText: intent } : {}),
       ...(matchedSignals.length ? { matchedSignals } : {}),
     });
 
@@ -167,6 +169,9 @@ async function main() {
 
     try {
       scheduleAutonomousReportingMarker(eventRoot);
+      if (HOOK_EVENT === 'pre_compact' || HOOK_EVENT === 'post_compact') {
+        maintainLens(eventRoot);
+      }
       if (HOOK_EVENT === 'session_start') {
         maybeRunReflectionStub(eventRoot);
         runInferenceImprovementLight(eventRoot);