0xray 4.0.36 → 4.0.38

package/dist/enforcement/validators/architecture-validators.js

@@ -278,6 +278,108 @@ export class ErrorResolutionValidator extends BaseValidator {
         return this.createSuccessResult("Error resolution patterns are properly implemented");
     }
 }
+/** Code points matched by a non-unicode `\s` in this Node. */
+function isCallWhitespace(ch) {
+    const c = ch.charCodeAt(0);
+    if (c <= 32) {
+        return c === 9 || c === 10 || c === 11 || c === 12 || c === 13 || c === 32;
+    }
+    if (c >= 0x2000 && c <= 0x200a)
+        return true;
+    return (c === 0xa0 ||
+        c === 0x1680 ||
+        c === 0x2028 ||
+        c === 0x2029 ||
+        c === 0x202f ||
+        c === 0x205f ||
+        c === 0x3000 ||
+        c === 0xfeff);
+}
+/** Per-name scans are cheaper below this; one automaton wins above it. */
+const CALL_SCAN_NAME_THRESHOLD = 48;
+/**
+ * Counts `name\\s*\\(` for every name.
+ * Suffix hits count (`foo` inside `myfoo(`), matching a separate global regex per name.
+ */
+function countNameCallSites(code, names) {
+    if (names.length < CALL_SCAN_NAME_THRESHOLD) {
+        return names.map((funcName) => (code.match(new RegExp(`${funcName}\\s*\\(`, "g")) || []).length);
+    }
+    const counts = new Array(names.length).fill(0);
+    if (code.length === 0)
+        return counts;
+    const nodes = [{ next: new Map(), fail: 0, out: [] }];
+    for (let nameIndex = 0; nameIndex < names.length; nameIndex++) {
+        const name = names[nameIndex] ?? "";
+        let state = 0;
+        for (let i = 0; i < name.length; i++) {
+            const ch = name.charAt(i);
+            const current = nodes[state];
+            if (!current)
+                break;
+            let next = current.next.get(ch);
+            if (next === undefined) {
+                next = nodes.length;
+                nodes.push({ next: new Map(), fail: 0, out: [] });
+                current.next.set(ch, next);
+            }
+            state = next;
+        }
+        nodes[state]?.out.push(nameIndex);
+    }
+    const queue = [];
+    const root = nodes[0];
+    if (!root)
+        return counts;
+    for (const next of root.next.values())
+        queue.push(next);
+    let head = 0;
+    while (head < queue.length) {
+        const currentIndex = queue[head++];
+        const current = currentIndex === undefined ? undefined : nodes[currentIndex];
+        if (!current)
+            continue;
+        for (const [ch, childIndex] of current.next) {
+            queue.push(childIndex);
+            let fail = current.fail;
+            while (fail !== 0 && !nodes[fail]?.next.has(ch)) {
+                fail = nodes[fail]?.fail ?? 0;
+            }
+            const down = nodes[fail]?.next.get(ch);
+            const child = nodes[childIndex];
+            if (!child)
+                continue;
+            child.fail = down !== undefined && down !== childIndex ? down : 0;
+            const failOut = nodes[child.fail]?.out;
+            if (failOut && failOut.length > 0) {
+                child.out = child.out.concat(failOut);
+            }
+        }
+    }
+    let state = 0;
+    for (let i = 0; i < code.length; i++) {
+        const ch = code.charAt(i);
+        while (state !== 0 && !nodes[state]?.next.has(ch)) {
+            state = nodes[state]?.fail ?? 0;
+        }
+        const down = nodes[state]?.next.get(ch);
+        state = down === undefined ? 0 : down;
+        const outs = nodes[state]?.out;
+        if (!outs || outs.length === 0)
+            continue;
+        let k = i + 1;
+        while (k < code.length && isCallWhitespace(code.charAt(k)))
+            k++;
+        if (code.charAt(k) !== "(")
+            continue;
+        for (const nameIndex of outs) {
+            const current = counts[nameIndex];
+            if (current !== undefined)
+                counts[nameIndex] = current + 1;
+        }
+    }
+    return counts;
+}
 /**
  * Validates loop safety (Codex Term #8).
  * Prevents infinite loops by checking for proper termination conditions.
@@ -322,15 +424,19 @@ export class LoopSafetyValidator extends BaseValidator {
         // Check for recursion without base case detection (basic)
         const functionMatches = newCode.match(/function\s+\w+\s*\([^)]*\)/g);
         if (functionMatches) {
-            const functionNames = functionMatches
-                .map((match) => {
-                const nameMatch = match.match(/function\s+(\w+)/);
-                return nameMatch ? nameMatch[1] : null;
-            })
-                .filter(Boolean);
-            for (const funcName of functionNames) {
-                // Check if function calls itself (basic recursion detection)
-                const selfCalls = (newCode.match(new RegExp(`${funcName}\\s*\\(`, "g")) || []).length;
+            const functionNames = [];
+            for (const match of functionMatches) {
+                const name = match.match(/function\s+(\w+)/)?.[1];
+                if (name)
+                    functionNames.push(name);
+            }
+            const callCounts = countNameCallSites(newCode, functionNames);
+            for (let i = 0; i < functionNames.length; i++) {
+                const funcName = functionNames[i];
+                if (!funcName)
+                    continue;
+                // Same count a per-name /name\s*\(/g scan would return, including suffix hits.
+                const selfCalls = callCounts[i] ?? 0;
                 if (selfCalls > 1) {
                     // More than just the function definition
                     // Allow recursive functions with proper base cases (edge case)

package/dist/governance/codex-policy.service.d.ts

@@ -15,7 +15,8 @@
  *   - Returns ActiveCodexSnapshot compatible with the existing get_active_codex MCP tool.
  *   - Provides getTermCount() with safe 60-term fallback (preserves prior behavior of bypasses).
  *   - Full frameworkLogger discipline on every load/decision/error.
- *   - No caching in v1 skeleton (additive later); no mutation; no enforcement.
+ *   - Reuses one parsed codex while that file still wins and its mtime and size are unchanged.
+ *   - No mutation of the cached codex; no enforcement.
  *
  * First wired consumer: src/mcps/enforcer-tools.server.ts (getCodexTermCount bypass removed;
  * now delegates through this service).
@@ -34,9 +35,18 @@ import type { ActiveCodexSnapshot, ICodexPolicyProvider } from './governance-typ
  */
 export declare class CodexPolicyService implements ICodexPolicyProvider {
     private readonly component;
+    /**
+     * Winning parse. Invalid when a higher-priority path appears or mtime/size changes,
+     * so the next check still parses the bytes a fresh load would have read.
+     */
+    private codexCache;
+    private candidateKey;
+    private fileIdentity;
+    private cachedRaw;
     /**
      * Internal loader: resolves candidates, picks first existing, reads + parses.
-     * Always logs via frameworkLogger (success, error, fallback).
+     * Repeat calls skip the read and JSON.parse while the winning file is unchanged.
+     * Logs via frameworkLogger on load, error, and fallback (not on a cache hit).
      */
     private loadRaw;
     private computeTermCount;

package/dist/governance/codex-policy.service.js

@@ -15,7 +15,8 @@
  *   - Returns ActiveCodexSnapshot compatible with the existing get_active_codex MCP tool.
  *   - Provides getTermCount() with safe 60-term fallback (preserves prior behavior of bypasses).
  *   - Full frameworkLogger discipline on every load/decision/error.
- *   - No caching in v1 skeleton (additive later); no mutation; no enforcement.
+ *   - Reuses one parsed codex while that file still wins and its mtime and size are unchanged.
+ *   - No mutation of the cached codex; no enforcement.
  *
  * First wired consumer: src/mcps/enforcer-tools.server.ts (getCodexTermCount bypass removed;
  * now delegates through this service).
@@ -29,51 +30,125 @@
  */
 import { frameworkLogger } from '../core/framework-logger.js';
 import { resolveCodexPath } from '../core/config-paths.js';
-import { existsSync } from 'fs';
+import { existsSync, statSync } from 'fs';
 import * as fs from 'fs/promises';
+/** mtimeNs when the stat has it. mtimeMs only when it does not. */
+function codexClock(fileStat) {
+    const nanos = fileStat.mtimeNs;
+    if (typeof nanos === 'bigint')
+        return nanos.toString();
+    if (typeof nanos === 'number' && Number.isFinite(nanos))
+        return String(nanos);
+    if (typeof fileStat.mtimeMs === 'number' && Number.isFinite(fileStat.mtimeMs)) {
+        return String(fileStat.mtimeMs);
+    }
+    return null;
+}
 /**
  * Canonical implementation of the Governance Codex/Policy provider.
  * Single owner of the "first read" of any codex.json for the framework.
  */
 export class CodexPolicyService {
     component = 'codex-policy-service';
+    /**
+     * Winning parse. Invalid when a higher-priority path appears or mtime/size changes,
+     * so the next check still parses the bytes a fresh load would have read.
+     */
+    codexCache = null;
+    candidateKey(candidates) {
+        return JSON.stringify(candidates);
+    }
+    fileIdentity(sourcePath) {
+        try {
+            const fileStat = statSync(sourcePath);
+            if (!fileStat.isFile())
+                return null;
+            const clock = codexClock(fileStat);
+            if (clock === null)
+                return null;
+            return `${clock}:${fileStat.size}`;
+        }
+        catch {
+            return null;
+        }
+    }
+    cachedRaw(candidates) {
+        const cached = this.codexCache;
+        if (!cached || cached.candidateKey !== this.candidateKey(candidates))
+            return null;
+        for (let i = 0; i < cached.index; i++) {
+            const higher = candidates[i];
+            if (higher && existsSync(higher))
+                return null;
+        }
+        const identity = this.fileIdentity(cached.sourcePath);
+        if (!identity || identity !== cached.identity)
+            return null;
+        return cached.raw;
+    }
     /**
      * Internal loader: resolves candidates, picks first existing, reads + parses.
-     * Always logs via frameworkLogger (success, error, fallback).
+     * Repeat calls skip the read and JSON.parse while the winning file is unchanged.
+     * Logs via frameworkLogger on load, error, and fallback (not on a cache hit).
      */
     async loadRaw() {
-        const candidates = resolveCodexPath();
-        const resolvedPath = Array.isArray(candidates)
-            ? candidates.find((p) => existsSync(p)) || candidates[0] || null
-            : candidates || null;
-        if (!resolvedPath || !existsSync(resolvedPath)) {
+        const resolved = resolveCodexPath();
+        const candidates = Array.isArray(resolved)
+            ? resolved
+            : resolved
+                ? [resolved]
+                : [];
+        const hit = this.cachedRaw(candidates);
+        if (hit)
+            return hit;
+        const index = candidates.findIndex((candidate) => existsSync(candidate));
+        const indexed = index >= 0 ? candidates[index] : undefined;
+        const sourcePath = indexed ?? candidates[0] ?? null;
+        if (index < 0 || !sourcePath) {
+            this.codexCache = null;
             await frameworkLogger.log(this.component, 'codex-not-found', 'warning', {
                 candidates,
-                resolvedPath,
+                resolvedPath: sourcePath,
                 message: 'No codex.json found in standard locations; using fallback behavior',
             });
-            return { path: resolvedPath, data: this.getBuiltinFallback(), isFallback: true };
+            return { path: sourcePath, data: this.getBuiltinFallback(), isFallback: true };
         }
         try {
-            const content = await fs.readFile(resolvedPath, 'utf-8');
+            const before = this.fileIdentity(sourcePath);
+            const content = await fs.readFile(sourcePath, 'utf-8');
             const data = JSON.parse(content);
             const termCount = this.computeTermCount(data);
+            const raw = { path: sourcePath, data, isFallback: false };
+            const after = this.fileIdentity(sourcePath);
+            if (before && after && before === after) {
+                this.codexCache = {
+                    candidateKey: this.candidateKey(candidates),
+                    index,
+                    sourcePath,
+                    identity: after,
+                    raw,
+                };
+            }
+            else {
+                this.codexCache = null;
+            }
             await frameworkLogger.log(this.component, 'codex-loaded', 'success', {
-                source: resolvedPath,
+                source: sourcePath,
                 version: data?.version || 'unknown',
                 termCount,
                 lastUpdated: data?.lastUpdated,
             });
-            return { path: resolvedPath, data, isFallback: false };
+            return raw;
         }
         catch (error) {
+            this.codexCache = null;
             const msg = error instanceof Error ? error.message : String(error);
             await frameworkLogger.log(this.component, 'codex-load-error', 'error', {
-                source: resolvedPath,
+                source: sourcePath,
                 error: msg,
             });
             // Safe fallback (never break callers)
-            return { path: resolvedPath, data: this.getBuiltinFallback(), isFallback: true };
+            return { path: sourcePath, data: this.getBuiltinFallback(), isFallback: true };
         }
     }
     computeTermCount(data) {
@@ -121,7 +196,7 @@ export class CodexPolicyService {
                 ? 'Governance CodexPolicyService — builtin fallback (no external codex.json resolved)'
                 : 'Returned via Governance CodexPolicyService — V2 Single Source of Truth (S02-REAL)',
             dynamo_required: true,
-            ...(includeRaw ? { codex: data } : {}),
+            ...(includeRaw ? { codex: structuredClone(data) } : {}),
         };
         await frameworkLogger.log(this.component, 'get-current-codex', 'info', {
             source: path,

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

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
  * Grok SessionStart / UserPromptSubmit / PreCompact / PostCompact.
- * Grok ignores stdout here; station heat is session-boot.json + STATION.md.
+ * Compact prints nothing. Station heat is session-boot.json + STATION.md.
  */
 
 import {
@@ -148,9 +148,10 @@ async function main() {
           : '0xray/grok-session-start';
 
     const intent = extractIntent(event);
-    const matchedSignals =
-      HOOK_EVENT === 'user_prompt_submit' ? [] : await matchStationSignals(eventRoot, intent);
     const compact = COMPACT_EVENTS.has(HOOK_EVENT);
+    // The compact payload is the whole conversation. Do not match it and do not print it.
+    const matchedSignals =
+      compact || HOOK_EVENT === 'user_prompt_submit' ? [] : await matchStationSignals(eventRoot, intent);
     let freshnessLine = null;
     if (!compact) {
       try {
@@ -164,8 +165,7 @@ async function main() {
     const payload = buildSessionBootPayload(eventRoot, source, {
       hookEvent: HOOK_EVENT,
       sessionId: event.sessionId || process.env.GROK_SESSION_ID || null,
-      ...(intent ? { intent } : {}),
-      ...(!compact && intent ? { cardText: intent } : {}),
+      ...(!compact && intent ? { intent, cardText: intent } : {}),
       ...(matchedSignals.length ? { matchedSignals } : {}),
       ...(freshnessLine ? { freshnessLine } : {}),
     });
@@ -195,7 +195,7 @@ async function main() {
       /* non-blocking pipeline facets */
     }
 
-    console.log(JSON.stringify(payload));
+    if (!compact) process.stdout.write(`${JSON.stringify(payload)}\n`);
     process.exit(0);
   } catch (err) {
     appendHookActivity(root, 'grok-session-start', 'session-boot-error', 'error', {

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

@@ -4,7 +4,11 @@
  * The view keeps every field for the next look.
  * A held plane stays quiet. A leave is denied.
  * On this host a search is grep, glob, or a shell that runs one.
+ * A shell that reads a project source file is a search.
  * The lens file stays open. One later read may go on, then the next read stops.
+ * An opened source file that no lens lists is remembered.
+ * The next search stops until that file is on a lens and its plate is on disk.
+ * The hook does not author the plate.
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, unlinkSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
@@ -14,7 +18,7 @@ import { fileURLToPath } from 'node:url';
 const FIELD_ORDER = ['plate', 'entry', 'exit', 'files', 'skills', 'setup', 'teardown', 'worn'];
 const HERE = dirname(fileURLToPath(import.meta.url));
 const WORN_PLANES = ['dichotomy', 'syncopate', 'synthesis', 'digest', 'triage', 'loop'];
-const CARD_PLANES = ['ground', 'routing', 'house', 'boot', 'governance', 'memory-recall', 'orchestration', 'processor', 'reporting'];
+const CARD_PLANES = ['ground', 'routing', 'house', 'boot', 'governance', 'memory-recall', 'orchestration', 'processor', 'reporting', 'stamp-plate', 'record-map', 'write-home', 'activity-log', 'session-capture', 'suit-wear', 'suit-organs', 'station-card', 'notes-page', 'reflection-page', 'site-manual', 'package-face', 'suit-settings', 'trail-state', 'inference-files', 'grok-compact', 'payload-heat', 'station-heat', 'pickup-stamp', 'cursor-compact', 'work-fresh', 'kept-line', 'lens-gate', 'pre-tool', 'lens-page'];
 const CARD_FLAVORS = ['digest', 'triage'];
 const SCOPE_ZOOM = ['ecosystem', 'part', 'one flow', 'one artifact'];
 
@@ -58,6 +62,25 @@ function organDeny(reason) {
   return { gate: 'goggles', decision: 'deny', reason };
 }
 
+function plateIdsIn(spoken) {
+  const ids = [];
+  const re = /docs-site\/docs\/plates\/([a-z0-9-]+)\.md/ig;
+  let match;
+  while ((match = re.exec(String(spoken || '')))) ids.push(match[1]);
+  return ids;
+}
+
+function associatedPlates(plane) {
+  try {
+    const data = JSON.parse(readFileSync(planesFile(), 'utf8'));
+    const entry = data[plane];
+    const listed = entry && Array.isArray(entry.plates) ? entry.plates.map(String) : [];
+    return new Set([plane, ...listed]);
+  } catch {
+    return new Set([plane]);
+  }
+}
+
 function planeWord(name, text) {
   return new RegExp(`(?:^|[^A-Za-z0-9-])${String(name).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?:[^A-Za-z0-9-]|$)`, 'i').test(String(text || ''));
 }
@@ -75,8 +98,13 @@ export function organStop(held, action) {
   const paths = (action?.paths || []).map(String).filter(Boolean);
   const tool = String(action?.tool || '');
   const spoken = [text, ...paths].join('\n');
-  if (/docs-site\/docs\/plates\/[a-z0-9-]+\.md/i.test(spoken)) {
-    return organDeny(`The reading is ${plane}. That drawing is not the plane.`);
+  const drawn = plateIdsIn(spoken);
+  if (drawn.length) {
+    const allowed = associatedPlates(plane);
+    const foreign = drawn.filter((id) => !allowed.has(id));
+    if (foreign.length) {
+      return organDeny(`The reading is ${plane}. That drawing is not the plane.`);
+    }
   }
   const otherFile = otherPlaneFile(plane, spoken);
   if (otherFile) return organDeny(`The reading is ${plane}. The action is ${otherFile}.`);
@@ -252,6 +280,7 @@ function cardView(plane, scope, flavor, root) {
     from: plane.id === 'ground' ? '' : (plane.from || 'ground'),
     digest: plane.digest || '',
     plate: plane.plate || '',
+    plates: Array.isArray(plane.plates) ? plane.plates : [],
     entry: plane.entry || '',
     exit: plane.exit || '',
     files: listed,
@@ -268,12 +297,15 @@ function cardView(plane, scope, flavor, root) {
   return view;
 }
 
-function formatCardText(view) {
+function cardRows(view) {
   const rows = [
     ['Plane', view.plane],
     ['From', view.from],
     ['Digest', view.digest],
     ['Plate', view.plate],
+  ];
+  if (Array.isArray(view.plates) && view.plates.length) rows.push(['Plates', view.plates.join(', ')]);
+  rows.push(
     ['Entry', view.entry],
     ['Exit', view.exit],
     ['Files', view.files.join(', ')],
@@ -281,7 +313,12 @@ function formatCardText(view) {
     ['Setup', view.setup],
     ['Teardown', view.teardown],
     ['Worn', view.worn],
-  ];
+  );
+  return rows;
+}
+
+function formatCardText(view) {
+  const rows = cardRows(view);
   let text = rows.map(([key, value]) => `${key}: ${value}`.trimEnd()).join('\n');
   if (view.flavor === 'triage') {
     const lines = [];
@@ -295,19 +332,7 @@ function formatCardText(view) {
 }
 
 export function formatCardPane(view) {
-  const rows = [
-    ['Plane', view.plane],
-    ['From', view.from],
-    ['Digest', view.digest],
-    ['Plate', view.plate],
-    ['Entry', view.entry],
-    ['Exit', view.exit],
-    ['Files', view.files.join(', ')],
-    ['Skills', view.skills],
-    ['Setup', view.setup],
-    ['Teardown', view.teardown],
-    ['Worn', view.worn],
-  ];
+  const rows = cardRows(view);
   if (view.flavor === 'triage') {
     if (Array.isArray(view.empty) && view.empty.length) rows.push(['Empty', view.empty.join(', ')]);
     if (view.exam) rows.push(['', view.exam]);
@@ -524,6 +549,7 @@ export function assemblePlane(id, platesDir) {
     files,
     unpathed: extra.unpathed || null,
     skills: extra.skills || '',
+    plates: Array.isArray(extra.plates) ? extra.plates.map(String) : [],
     setup: extra.setup || sectionOf(src.body, 'Setup') || (flow && flow.setup) || '',
     teardown: extra.teardown || sectionOf(src.body, 'Teardown') || (flow && flow.teardown) || '',
     worn: extra.worn || '',
@@ -746,11 +772,117 @@ function opensLensFile(text) {
   return mapFiles().some((file) => spoken.includes(file));
 }
 
+const SOURCE_FILE = /(?:^|[^A-Za-z0-9_])((?:src|scripts|docs-site|\.agents|grok-bot)\/[\w./-]*\.[A-Za-z0-9]+)(?=$|[^A-Za-z0-9_./-])/g;
+const SOURCE_READER = /(?:^|[^A-Za-z0-9_])(?:python3|node|cat|head|tail|sed|less|more|bat|awk)(?=$|[^A-Za-z0-9_])/;
+const STAMP_TARGET = /docs-site\/docs\/plates\/[a-z0-9-]+\.md|goggles-planes\.json|\.agents\/skills\/[a-z0-9-]+\/SKILL\.md|src\/memory-routing\/plates\.ts|src\/integrations\/hooks\/plates\.cjs|docs-site\/sidebars\.ts|docs-site\/docs\/plates\/index\.md/;
+
+function isStampPath(file) {
+  return STAMP_TARGET.test(String(file || '').replace(/\\/g, '/'));
+}
+
+function openedSourcePaths(text) {
+  const spoken = `\n${String(text || '').replace(/\\/g, '/')}`;
+  const found = [];
+  for (const match of spoken.matchAll(SOURCE_FILE)) {
+    const file = match[1];
+    if (!file || isStampPath(file) || found.includes(file)) continue;
+    found.push(file);
+  }
+  return found;
+}
+
+function shellReadsSource(text) {
+  const spoken = String(text || '');
+  return SOURCE_READER.test(spoken) && openedSourcePaths(spoken).length > 0;
+}
+
+function isLensWrite(toolName) {
+  return /write|edit|replace/i.test(String(toolName || ''));
+}
+
+function debtFile(root) {
+  return join(root, '.xray', 'state', 'goggles-lens-debt.json');
+}
+
+function loadDebt(root) {
+  try {
+    const data = JSON.parse(readFileSync(debtFile(root), 'utf8'));
+    return Array.isArray(data.paths) ? data.paths.filter((file) => typeof file === 'string') : [];
+  } catch {
+    return [];
+  }
+}
+
+function saveDebt(root, paths) {
+  const unique = [];
+  for (const file of paths) {
+    if (!unique.includes(file)) unique.push(file);
+  }
+  const dest = debtFile(root);
+  if (!unique.length) {
+    try {
+      unlinkSync(dest);
+    } catch {
+      /* already clear */
+    }
+    return;
+  }
+  mkdirSync(dirname(dest), { recursive: true });
+  writeFileSync(dest, `${JSON.stringify({ paths: unique })}\n`);
+}
+
+function lensRecords() {
+  try {
+    const data = JSON.parse(readFileSync(planesFile(), 'utf8'));
+    const records = [];
+    if (!data || typeof data !== 'object') return records;
+    for (const [name, entry] of Object.entries(data)) {
+      if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
+      if (!Array.isArray(entry.files)) continue;
+      records.push([name, entry.files.filter((file) => typeof file === 'string')]);
+    }
+    return records;
+  } catch {
+    return [];
+  }
+}
+
+function plateIsOnDisk(root, name) {
+  const beside = findPlatesDir(HERE);
+  if (beside && existsSync(join(beside, `${name}.md`))) return true;
+  return existsSync(join(root, 'docs-site', 'docs', 'plates', `${name}.md`));
+}
+
+function lensCovers(root, file) {
+  for (const [name, files] of lensRecords()) {
+    if (!files.includes(file)) continue;
+    if (name === 'ground' || plateIsOnDisk(root, name)) return true;
+  }
+  return false;
+}
+
+function unsettledDebt(root) {
+  const prior = loadDebt(root);
+  const kept = prior.filter((file) => !lensCovers(root, file));
+  if (kept.length !== prior.length) saveDebt(root, kept);
+  return kept;
+}
+
+function rememberOpened(root, text) {
+  const fresh = openedSourcePaths(text).filter((file) => !lensCovers(root, file));
+  if (!fresh.length) return;
+  saveDebt(root, [...loadDebt(root), ...fresh]);
+}
+
+function debtReason(paths) {
+  return `Opened ${paths.join(', ')} has no lens.`;
+}
+
 function researchCall(toolName, text) {
   const tool = String(toolName || '');
   const spoken = String(text || '');
   if (/researcher|explorer|deep[- ]?research/i.test(tool) || DEEP_SEARCH.test(tool)) return true;
-  if (/bash|shell/i.test(tool) && (/researcher|explorer|deep[- ]?research/i.test(spoken) || DEEP_SEARCH.test(spoken) || shellSearches(spoken))) return true;
+  if (/bash|shell/i.test(tool) && (/researcher|explorer|deep[- ]?research/i.test(spoken) || DEEP_SEARCH.test(spoken) || shellSearches(spoken) || shellReadsSource(spoken))) return true;
   if (/^(grep|glob)$/i.test(tool)) return true;
   return /^read_file$/i.test(tool) && !opensLensFile(spoken);
 }
@@ -807,24 +939,33 @@ function stampPlane(root, id) {
   }
 }
 
-/** A search stays stopped. The lens file stays open. One later read may go on, then the next read stops. */
+/** Name one plane and the tool continues. Name none, or more than one, and the search stops. */
 export function lensBeforeResearch(root, toolName, text) {
   const spoken = String(text || '');
-  if (!researchCall(toolName, spoken)) return null;
+  const openDebt = unsettledDebt(root);
+  const research = researchCall(toolName, spoken);
+  if (openDebt.length && research) {
+    return { gate: 'lens', decision: 'deny', reason: debtReason(openDebt) };
+  }
+  if (openDebt.length && isLensWrite(toolName) && !isStampPath(spoken)) {
+    return { gate: 'lens', decision: 'deny', reason: debtReason(openDebt) };
+  }
+  if (!research) return null;
   const names = CARD_PLANES.filter((name) => intentWords(spoken).includes(name));
+  if (names.length === 1) {
+    stampPlane(root, names[0]);
+    rememberOpened(root, spoken);
+    return null;
+  }
   if (/^read_file$/i.test(String(toolName || ''))) {
     if (loadReadPass(root) === 'armed') {
       saveReadPass(root, true);
       return null;
     }
-    if (loadReadPass(root) !== 'spent') {
-      if (names.length === 1) stampPlane(root, names[0]);
-      saveReadPass(root, false);
-    }
-    return { gate: 'lens', decision: 'deny', reason: lensPage(root, names) };
+    if (loadReadPass(root) !== 'spent') saveReadPass(root, false);
+    return { gate: 'lens', decision: 'deny', reason: 'Name one plane.' };
   }
-  if (names.length === 1) stampPlane(root, names[0]);
-  return { gate: 'lens', decision: 'deny', reason: lensPage(root, names) };
+  return { gate: 'lens', decision: 'deny', reason: 'Name one plane.' };
 }
 
 function seenFields(plane, root) {