0xray 4.0.41 → 4.1.0

package/dist/governance/local-confer.d.ts

@@ -1,10 +1,13 @@
-import type { GovernanceRole, GovernanceVote } from "./llm-governance-provider.js";
+import type { GovernanceMiss, GovernanceRole, GovernanceVote } from "./llm-governance-provider.js";
 export type LocalConferInput = {
     role: GovernanceRole;
     highConfidenceTrapPresent?: boolean | undefined;
     recommendedAgent?: string | null | undefined;
     llmConfigured?: boolean | undefined;
+    miss?: GovernanceMiss | undefined;
 };
 /** Receipt when nested LLM is absent or returned no vote. Never approve — analyze_proposal feeds mergeVotes. */
 export declare function localConferVote(input: LocalConferInput): GovernanceVote;
+/** Stop a model from planting a second DECISION or Verdict line inside the reasoning body. */
+export declare function sanitizeGovernanceReasoning(reasoning: string): string;
 export declare function formatGovernanceVoteText(vote: GovernanceVote, extra?: string): string;

package/dist/governance/local-confer.js

@@ -1,6 +1,13 @@
 /** Receipt when nested LLM is absent or returned no vote. Never approve — analyze_proposal feeds mergeVotes. */
 export function localConferVote(input) {
     const role = input.role;
+    if (input.miss && input.miss !== "not-configured") {
+        return {
+            decision: "abstain",
+            confidence: 0.5,
+            reasoning: `Local confer (${role}); nested LLM did not produce a vote (${input.miss}).`,
+        };
+    }
     if (input.llmConfigured) {
         return {
             decision: "abstain",
@@ -22,6 +29,20 @@ export function localConferVote(input) {
         reasoning: `Local confer (${role}); nested LLM not configured.`,
     };
 }
+function abstainedWithoutUsableVote(vote) {
+    if (vote.decision !== "abstain")
+        return false;
+    return /nested LLM not configured|did not produce a vote|returned no vote/i.test(vote.reasoning);
+}
+/** Stop a model from planting a second DECISION or Verdict line inside the reasoning body. */
+export function sanitizeGovernanceReasoning(reasoning) {
+    return reasoning
+        .split("\n")
+        .map((line) => /^\s*(?:[-*•]\s*)?(?:Verdict:|DECISION:)/i.test(line) ? `> ${line.trim()}` : line)
+        .join("\n");
+}
 export function formatGovernanceVoteText(vote, extra = "") {
-    return `DECISION: ${vote.decision}\nCONFIDENCE: ${vote.confidence.toFixed(2)}\nREASONING: ${vote.reasoning}${extra}`;
+    const reviewLine = abstainedWithoutUsableVote(vote) ? "\nVerdict: UNREVIEWED" : "";
+    const reasoning = sanitizeGovernanceReasoning(vote.reasoning);
+    return `DECISION: ${vote.decision}\nCONFIDENCE: ${vote.confidence.toFixed(2)}\nREASONING: ${reasoning}${reviewLine}${extra}`;
 }

package/dist/integrations/cursor/hooks/hooks.json

@@ -3,7 +3,8 @@
   "hooks": {
     "preToolUse": [
       {
-        "command": ".cursor/hooks/pre-tool-use.sh"
+        "command": ".cursor/hooks/pre-tool-use.sh",
+        "failClosed": true
       }
     ],
     "preCompact": [
@@ -18,12 +19,14 @@
     ],
     "beforeShellExecution": [
       {
-        "command": ".cursor/hooks/before-shell-execution.sh"
+        "command": ".cursor/hooks/before-shell-execution.sh",
+        "failClosed": true
       }
     ],
     "beforeReadFile": [
       {
-        "command": ".cursor/hooks/before-read-file.sh"
+        "command": ".cursor/hooks/before-read-file.sh",
+        "failClosed": true
       }
     ]
   }

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

@@ -5,23 +5,40 @@
  * Does not rely on sessionStart (unavailable on managed cloud).
  */
 
-import {
-  appendHookActivity,
-  checkCodexPatterns,
-  checkFullTestSuite,
-  cursorGateRoot,
-  cursorHeatRoots,
-  cursorSessionId,
-  cursorToolContext,
-  cursorWorkspaceRoot,
-  ensureCursorSessionBoot,
-  evaluatePreToolGate,
-  isShellTool,
-  isWriteTool,
-  loadDelegationGateFeatures,
-  loadFeatures,
-  readStdinJson,
-} from './cursor-hook-utils.js';
+// Gate modules load inside main()'s try (dynamic import): a missing or broken module must deny, not crash
+// before the handler with no JSON (Cursor would then fail open). Nothing here may import them statically.
+let appendHookActivity = () => {};
+
+/** Deny JSON on stdout and exit 0. Used when the gate cannot run at all. */
+function denyHard(reason) {
+  try {
+    process.stdout.write(`${JSON.stringify({ permission: 'deny', user_message: reason, agent_message: reason })}\n`);
+  } finally {
+    process.exit(0);
+  }
+}
+
+export function cursorHookErrorPermission(err) {
+  if (err?.code === 'EACCES') return 'allow';   // code only: a message mentioning EACCES is not a permission error
+  return 'deny';
+}
+
+// Bootstrap: a fresh checkout has no build yet, so gate modules can be missing.
+// Only the exact build commands may run then, so the hook cannot block the build that creates it.
+const BOOTSTRAP_CMDS = new Set(['npm ci', 'npm run build', 'npm ci && npm run build', 'npm install && npm run build']);
+export function cursorBootstrapPermission(err, event) {
+  if (err?.code !== 'ERR_MODULE_NOT_FOUND') return 'deny';
+  const cmd = String(event?.tool_input?.command ?? event?.command ?? '').trim().replace(/\s+/g, ' ');
+  return BOOTSTRAP_CMDS.has(cmd) ? 'allow' : 'deny';
+}
+
+async function readRawEvent() {
+  try {
+    let raw = '';
+    for await (const c of process.stdin) raw += c;
+    return JSON.parse(raw);
+  } catch { return null; }
+}
 
 function finish(root, permission, reason, hint, toolName, extra = {}) {
   const out = { permission };
@@ -32,22 +49,38 @@ function finish(root, permission, reason, hint, toolName, extra = {}) {
   if (hint && permission === 'allow') {
     out.user_message = hint;
   }
+  if (extra.hookSpecificOutput) out.hookSpecificOutput = extra.hookSpecificOutput;
   console.log(JSON.stringify(out));
-  appendHookActivity(root, 'cursor-pre-tool-use', permission, permission === 'deny' ? 'error' : 'info', {
-    tool: toolName,
-    reason: reason || hint || null,
-    gate: extra.gate || null,
-    livePath: true,
-  });
+  try {
+    appendHookActivity(root, 'cursor-pre-tool-use', permission, permission === 'deny' ? 'error' : 'info', {
+      tool: toolName,
+      reason: reason || hint || null,
+      gate: extra.gate || null,
+      livePath: true,
+    });
+  } catch { /* the verdict is already on stdout; activity logging must not change it */ }
   process.exit(0);
 }
 
 async function main() {
-  const fallbackRoot = cursorWorkspaceRoot();
+  let fallbackRoot = process.cwd();
   let toolName = 'unknown';
 
   try {
+    const u = await import('./cursor-hook-utils.js');
+    const { lensDecision, repertoireRoute } = await import('../../hooks/pre-tool-speak.mjs');
+    const {
+      checkCodexPatterns, checkFullTestSuite, cursorGateRoot, cursorHeatRoots, cursorSessionId, cursorToolContext,
+      cursorWorkspaceRoot, ensureCursorSessionBoot, evaluatePreToolGate, isShellTool, isWriteTool,
+      loadDelegationGateFeatures, loadFeatures, readStdinJson,
+    } = u;
+    appendHookActivity = u.appendHookActivity;
+    fallbackRoot = cursorWorkspaceRoot();
     const event = await readStdinJson();
+    // readStdinJson returns {} for empty or malformed stdin; Cursor always sends a JSON object, so deny those.
+    if (!event || typeof event !== 'object' || Array.isArray(event) || Object.keys(event).length === 0) {
+      finish(fallbackRoot, 'deny', 'preToolUse: empty or malformed hook input — denied', null, toolName, { gate: 'bad-input' });
+    }
     const eventRoot = cursorWorkspaceRoot(event);
     const sessionId = cursorSessionId(event);
     const heatRoots = cursorHeatRoots(event);
@@ -60,7 +93,7 @@ async function main() {
     const gateFeatures = loadDelegationGateFeatures(gateRoot, 'cursor');
     const ctx = cursorToolContext(event);
     toolName = ctx.toolName;
-    const { content, cmd, toolInput } = ctx;
+    const { content, cmd, toolInput, paths } = ctx;
 
     const gateBlock = evaluatePreToolGate(toolName, toolInput, {
       projectRoot: gateRoot,
@@ -77,35 +110,65 @@ async function main() {
       if (extraBlock) finish(gateRoot, 'deny', extraBlock, null, toolName);
     }
 
+    const spoken = [content, cmd, toolInput.pattern, toolInput.query, ...(paths || [])].filter(Boolean).join('\n');
+    const lensStop = lensDecision(gateRoot, toolName, spoken);
+    if (lensStop?.decision === 'deny') {
+      finish(gateRoot, 'deny', lensStop.reason, null, toolName, { gate: lensStop.gate });
+    }
+    const route = repertoireRoute([toolName, cmd, content].filter(Boolean).join(' '));
+
     if (isShellTool(toolName) && cmd) {
       const testHint = checkFullTestSuite(cmd, features);
-      if (testHint) finish(gateRoot, 'allow', null, testHint, toolName);
+      if (testHint) finish(gateRoot, 'allow', null, testHint, toolName, { ...(route || {}) });
     }
 
     if (gateBlock.reason) {
       finish(gateRoot, 'allow', gateBlock.reason, gateBlock.hint, toolName, {
         gate: gateBlock.gate,
         warn: true,
+        ...(route || {}),
       });
     }
 
-    finish(gateRoot, 'allow', null, null, toolName);
+    finish(gateRoot, 'allow', null, null, toolName, { ...(route || {}) });
   } catch (err) {
-    appendHookActivity(fallbackRoot, 'cursor-pre-tool-use', 'hook-error', 'error', {
-      tool: toolName,
-      error: err.message,
-      failOpen: true,
-    });
-    // Dest EACCES on a Cloud workspace wrapper must not deny every tool.
+    if (err?.code === 'ERR_MODULE_NOT_FOUND' && cursorBootstrapPermission(err, await readRawEvent()) === 'allow') {
+      console.log(JSON.stringify({ permission: 'allow', user_message: 'preToolUse: build not present — bootstrap build allowed' }));
+      process.exit(0);
+    }
+    const failOpen = cursorHookErrorPermission(err) === 'allow';
+    try {
+      appendHookActivity(fallbackRoot, 'cursor-pre-tool-use', 'hook-error', 'error', {
+        tool: toolName,
+        error: err.message,
+        failOpen,
+      });
+    } catch { /* logging must not turn a deny into a crash */ }
+    if (failOpen) {
+      // Dest EACCES on a Cloud workspace wrapper must not deny every tool.
+      finish(
+        fallbackRoot,
+        'allow',
+        `preToolUse hook error — fail open: ${err.message}`,
+        null,
+        toolName,
+        { gate: 'hook-error-fail-open' },
+      );
+    }
     finish(
       fallbackRoot,
-      'allow',
-      `preToolUse hook error — fail open: ${err.message}`,
+      'deny',
+      `preToolUse hook error blocked the tool: ${err.message}`,
       null,
       toolName,
-      { gate: 'hook-error-fail-open' },
+      { gate: 'hook-error' },
     );
   }
 }
 
-main();
+const launchedAsCli = Boolean(process.argv[1] && process.argv[1].endsWith('pre-tool-use.js'));
+if (launchedAsCli) {
+  process.on('uncaughtException', (err) => denyHard(`preToolUse hook crashed — denied: ${err?.message || err}`));
+  process.on('unhandledRejection', (err) => denyHard(`preToolUse hook crashed — denied: ${err?.message || err}`));
+  main().catch((err) => denyHard(`preToolUse hook crashed — denied: ${err?.message || err}`));
+}

package/dist/integrations/cursor/hooks/xray-cloud-hook.sh

@@ -110,7 +110,15 @@ if [ -n "$MILL" ]; then
 fi
 
 if [ -z "$NODE_BIN" ] || [ -z "$MILL" ] || [ ! -f "${MILL}/${REL}" ]; then
-  printf '{"permission":"allow","user_message":"xray-cloud-hook: mill missing — fail open"}\n'
+  # Gate events fail closed: no node or no hook file means the gate cannot run, so the tool is denied.
+  case "$EVENT" in
+    preToolUse|beforeShellExecution|beforeReadFile)
+      printf '{"permission":"deny","user_message":"xray-cloud-hook: node or hook file missing — denied (fail closed)","agent_message":"xray-cloud-hook: node or hook file missing — denied (fail closed)"}\n'
+      ;;
+    *)
+      printf '{"permission":"allow","user_message":"xray-cloud-hook: node or hook file missing — %s skipped"}\n' "$EVENT"
+      ;;
+  esac
   exit 0
 fi
 

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

@@ -17,7 +17,6 @@
 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';
@@ -27,27 +26,13 @@ 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, resolveGogglesMcp } = 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
-        }
-    }
+const { resolveRepertoireMcp, resolveGogglesMcp } = requireCjs(path.join(packageRoot, 'scripts/node/bridge-mcp-wiring.cjs'));
+function registerGrokMcpServers(targetDir, env) {
+    const wiring = requireCjs(path.join(packageRoot, 'scripts/node/bridge-mcp-wiring.cjs'));
+    const tomlPath = wiring.writeProjectSuitMcp(targetDir);
+    const trustPath = wiring.trustGrokFolder(targetDir, env);
+    process.stdout.write(`Project Grok MCP written to ${tomlPath}\n`);
+    process.stdout.write(`Grok folder trust written to ${trustPath}\n`);
 }
 export async function installForGrokCLI(options = {}) {
     frameworkLogger.log('grok-integration', 'install-start', 'info', {
@@ -115,21 +100,9 @@ export async function installForGrokCLI(options = {}) {
         writeProjectRepertoireMcp(targetDir);
         writeProjectGogglesMcp(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');
+        registerGrokMcpServers(targetDir, env);
+        if (!isolated) {
+            process.stdout.write('Project-scoped Grok plugin worn (machine ~/.grok/plugins/0xray not written)\n');
         }
         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.');

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

@@ -19,7 +19,7 @@ import {
   updatePlanTodoStatusInPlace,
   loadDelegationGateFeatures,
 } from '../../hooks/delegation-gate-runtime.mjs';
-import { isConferPendingForSession } from '../../hooks/confer-hook-runtime.mjs';
+import { isConferPendingForSession, readConferReviewHint } from '../../hooks/confer-hook-runtime.mjs';
 import { getActiveUserAsideBoot } from '../../hooks/user-aside-hook-runtime.mjs';
 import {
   applyStationHeat,
@@ -308,6 +308,7 @@ export function buildSessionBootPayload(root, source = '0xray/grok-session-start
   const sessionId =
     extra.sessionId || process.env.GROK_SESSION_ID || process.env.GROK_SESSION || null;
   const conferPending = loadConferPending(root, sessionId);
+  const conferReview = readConferReviewHint(root);
   const userAsideBoot = getActiveUserAsideBoot(root, sessionId);
   const gateFeatures = loadDelegationGateFeatures(root, 'grok');
   const frontier = gateFeatures.ceremony === 'lite';
@@ -332,6 +333,12 @@ export function buildSessionBootPayload(root, source = '0xray/grok-session-start
     ...heat,
     ...(siblingRoots.length > 0 ? { siblingWorkspaceRoots: siblingRoots } : {}),
     ...(conferPending ? { conferPending: true, conferTrigger: 'analyze-complexity at synthesis checkpoint' } : {}),
+    ...(conferReview
+      ? {
+          conferReview,
+          conferReviewHint: 'UNREVIEWED — abstain without a governance LLM blocks the consult todo',
+        }
+      : {}),
     ...(userAsideBoot ?? {}),
     sessionId,
     ...extra,

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

@@ -22,65 +22,9 @@ import {
 } from './grok-hook-utils.js';
 import { appendHookActivity } from './grok-hook-activity.js';
 import { cardStop, lensBeforeResearch } 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.`,
-    },
-  };
-}
+import { repertoireDecisionFields, repertoireRoute } from '../../hooks/pre-tool-speak.mjs';
 
-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;
-  }
-}
+export { repertoireDecisionFields };
 
 function finish(root, decision, reason, hint, toolName, extra = {}) {
   const out = { decision, ...extra };

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

@@ -914,9 +914,22 @@ async function handleDelegationGate(command, projectRoot, logDir) {
         logDir,
         `[delegation-gate] deny tool=${tool} gate=${outcome.gate} reason=${outcome.reason}`,
       );
+      return { phase: "pre", ...outcome };
     }
 
-    return { phase: "pre", ...outcome };
+    const spoken = `${tool} ${JSON.stringify(args)}`.slice(0, 500);
+    const { lensDecision, repertoireRoute } = await import("../hooks/pre-tool-speak.mjs");
+    const lens = lensDecision(projectRoot, tool, spoken);
+    if (lens) {
+      return {
+        allow: false,
+        phase: "pre",
+        gate: lens.gate || "lens",
+        reason: lens.reason,
+      };
+    }
+    const route = repertoireRoute(spoken);
+    return { phase: "pre", ...outcome, ...(route || {}) };
   } catch (error) {
     const message = `delegation-gate failed: ${error.message || error}`;
     logToActivity(logDir, `[delegation-gate] error ${message}`);

package/dist/integrations/hooks/confer-hook-runtime.mjs

@@ -3,7 +3,7 @@
  * Lazy-load confer SSOT for Grok session-boot hints.
  */
 import { createRequire } from 'node:module';
-import { existsSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -46,4 +46,26 @@ export function isConferPendingForSession(projectRoot, sessionId = null) {
   const mod = loadConfer();
   if (!mod?.isConferPending) return false;
   return mod.isConferPending(projectRoot, sessionId);
+}
+
+/** 'UNREVIEWED' when a consult receipt recorded abstain-without-model. */
+export function readConferReviewHint(projectRoot) {
+  const stateDir = join(projectRoot, '.xray', 'state');
+  if (!existsSync(stateDir)) return null;
+  let names;
+  try {
+    names = readdirSync(stateDir);
+  } catch {
+    return null;
+  }
+  for (const name of names) {
+    if (!name.startsWith('synthesis-consult-') || !name.endsWith('.json')) continue;
+    try {
+      const receipt = JSON.parse(readFileSync(join(stateDir, name), 'utf8'));
+      if (receipt && receipt.verdict === 'UNREVIEWED') return 'UNREVIEWED';
+    } catch {
+      /* unreadable receipt is not a hint */
+    }
+  }
+  return null;
 }

package/dist/integrations/hooks/delegation-gate-runtime.mjs

@@ -68,8 +68,9 @@ function loadDelegationGate() {
   ].filter(Boolean);
   const found = candidates.find((p) => existsSync(p));
   if (!found) {
-    throw new Error(
-      'delegation-gate.js missing — run npm run build in 0xray or npm install 0xray',
+    throw Object.assign(
+      new Error('delegation-gate.js missing — run npm run build in 0xray or npm install 0xray'),
+      { code: 'ERR_MODULE_NOT_FOUND' },
     );
   }
   return createRequire(import.meta.url)(found);

package/dist/integrations/hooks/goggles-mcp.mjs

@@ -3,7 +3,7 @@
  * Tools: look, status_lens. Same organ as the CLI.
  */
 import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
-import { basename, dirname, join, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { pathToFileURL, fileURLToPath } from 'node:url';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -12,17 +12,9 @@ import * as bundled from './goggles-pipeline.mjs';
 
 const HERE = fileURLToPath(new URL('.', import.meta.url));
 const SERVER_NAME = 'goggles';
-const CARD_PLANES = [
-  'ground',
-  'routing',
-  'house',
-  'boot',
-  'governance',
-  'memory-recall',
-  'orchestration',
-  'processor',
-  'reporting',
-];
+/** Card planes come from the organ, not a hand-kept copy. */
+const CARD_PLANES = Array.isArray(bundled.CARD_PLANES) ? bundled.CARD_PLANES : [];
+const CARD_OUTERS = ['digest', 'triage'];
 const SCOPES = ['ecosystem', 'part', 'one flow', 'one artifact'];
 
 const LOOK_SCHEMA = {
@@ -31,7 +23,7 @@ const LOOK_SCHEMA = {
   properties: {
     kind: {
       type: 'string',
-      description: 'Optional. Use "0" or "actuality" for the lens. Omit when naming an outer.',
+      description: 'Use "0" or "actuality" for the lens. Send kind, outer, or plane: an empty look is refused. Never with outer: kind and outer together is refused.',
       enum: ['0', 'actuality'],
     },
     outer: {
@@ -46,7 +38,7 @@ const LOOK_SCHEMA = {
     },
     plane: {
       type: 'string',
-      description: 'Card plane for digest or triage only. Not the lens.',
+      description: 'Card plane for digest or triage only. Not the lens. A plane with any other outer is refused.',
       enum: CARD_PLANES,
     },
   },
@@ -55,7 +47,7 @@ const LOOK_SCHEMA = {
 export const TOOLS = [
   {
     name: 'look',
-    description: 'Kind 0 is quiet on a match. It checks the six outer names. One outer is a reading. digest and triage return a card.',
+    description: 'Kind 0 is quiet on a match. It checks the six outer names, then sweeps every card plane for missing shipped files and names the first drift. One outer is a reading. digest and triage return a card. Refused: an empty look; kind with outer; a plane with an outer other than digest or triage.',
     inputSchema: LOOK_SCHEMA,
   },
   {
@@ -152,6 +144,15 @@ function checkArgs(args) {
   if (args.plane != null && !CARD_PLANES.includes(args.plane)) {
     return deny('invalid_args', 'plane is a card plane.');
   }
+  if (args.kind == null && args.outer == null && args.plane == null) {
+    return deny('invalid_args', 'Name a kind, one outer, or one plane.');
+  }
+  if (args.kind != null && args.outer != null) {
+    return deny('invalid_args', 'Send kind or outer, not both.');
+  }
+  if (args.plane != null && args.outer != null && !CARD_OUTERS.includes(args.outer)) {
+    return deny('invalid_args', 'plane goes with digest or triage only.');
+  }
   return null;
 }
 
@@ -161,7 +162,7 @@ function publicCard(view) {
     if (Array.isArray(view.empty) && view.empty.length) notes.push(`Empty: ${view.empty.join(', ')}`);
     if (view.exam) notes.push(view.exam);
   }
-  const skills = view.skills ? basename(String(view.skills)) : '';
+  const skills = view.skills ? String(view.skills) : '';
   const cascade = view.cascade
     ? {
       plane: view.cascade.plane,
@@ -227,7 +228,8 @@ export async function answerLook(raw, root) {
   const here = projectRoot(root);
   if (pureKind0(args)) {
     api.maintainLens(here);
-    const line = api.actualityLine();
+    const line = api.actualityLine() || cardDrift(api, here);
+    if (line) writeLens(api, here, line);
     if (!line) return quiet('kind0');
     return { ok: true, quiet: false, mode: 'kind0', content: line };
   }
@@ -269,6 +271,22 @@ export async function answerLook(raw, root) {
   };
 }
 
+/** Kind 0 card sweep: triage's file check on every card plane, shipped paths only. */
+function cardDrift(api, here) {
+  if (typeof api.shippedDrift !== 'function') return '';
+  try {
+    return api.shippedDrift(here);
+  } catch {
+    return '';
+  }
+}
+
+function writeLens(api, here, line) {
+  const file = api.lensPath(here);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${line}\n`);
+}
+
 function lensBody(root) {
   const file = join(root, '.xray', 'state', 'LENS.md');
   if (!existsSync(file)) return { found: false, text: '' };