total-recall-brain 3.41.3 → 3.41.4

package/src/core/preflight-gate.mjs

@@ -0,0 +1,77 @@
+/**
+ * Harness-neutral gate decision. Every harness adapter normalises its native
+ * hook payload into `{ tool, command, path, cwd }` and asks `decide`; the answer
+ * is the same in every harness.
+ *
+ * Rules, in order:
+ *   1. Tools that only display or discover (`meta`, `ui`) are always open.
+ *   2. Reads of skill files are open: reading them is how the preflight is earned.
+ *   3. A single plain Total Recall preflight, context, recall or help command is
+ *      open, so the gate can always be satisfied or repaired. Chaining, piping,
+ *      substitution and redirects are not plain, so the exemption cannot carry
+ *      other work and a capsule cannot be truncated through a pipe.
+ *   4. Everything else needs a fresh receipt for the directory.
+ *   5. With a receipt, a repository-wide source sweep still needs a recent
+ *      Total Recall consult (the rule DSH enforced alone until now).
+ * Any error inside the gate denies: most harnesses fail open when a hook crashes.
+ */
+import { ACK_COMMAND } from './preflight-receipt.mjs';
+
+export const TOOL_CLASSES = ['shell', 'read', 'write', 'search', 'web', 'mcp', 'agent', 'meta', 'ui', 'other'];
+export const SWEEP_CONSULT_MS = 15 * 60 * 1000;
+
+const SKILL_PATH = /\/\.(agent|claude)\/skills\//;
+const SATISFYING = /^(cd\s+\S+\s*&&\s*)?(npx\s+)?(total-recall|node\s+\S*bin\/total-recall\.mjs)\s+(tr-preflight|preflight|context|recall|help|--help)(\s+[^;&|`<>$\n]*)?$/;
+
+/** True when the whole command is one plain Total Recall invocation that satisfies or repairs the gate. */
+export function isSatisfyingCommand(command) {
+  return SATISFYING.test(String(command || '').trim());
+}
+
+/** A repository-wide search used to answer a question, as the DSH `tr-first.sh` rule defined it. */
+export function isRepoSweep(command) {
+  const c = String(command || '');
+  if (c.includes('total-recall')) return false;
+  const sweep = /(^|[\s;&|(])(rg|ripgrep|ag)\s/.test(c)
+    || /(^|[\s;&|(])grep\s+(-[A-Za-z]*[rR][A-Za-z]*|--recursive)(\s|$)/.test(c)
+    || /(^|[\s;&|(])find\s+(\.|\/Users)/.test(c)
+    || /(^|[\s;&|(])git\s+grep(\s|$)/.test(c);
+  if (!sweep) return false;
+  if (/\|\s*(grep|rg|ag)(\s|$)/.test(c)) return false; // filtering command output is not a source question
+  if (/node_modules|\.agent\/skills|\/tmp\/|\.git\//.test(c)) return false;
+  return true;
+}
+
+const allow = (rule) => ({ decision: 'allow', rule });
+const deny = (rule, reason, fix = ACK_COMMAND) => ({ decision: 'deny', rule, reason, fix });
+
+/**
+ * @param {{ tool: string, command?: string, path?: string, cwd?: string }} call
+ * @param {{ check: () => { ok: boolean, problems: string[] }, recentConsult?: () => boolean, readablePaths?: RegExp[] }} deps
+ */
+export function decide(call, deps) {
+  try {
+    const tool = TOOL_CLASSES.includes(call?.tool) ? call.tool : 'other';
+    if (tool === 'meta' || tool === 'ui') return allow(`class:${tool}`);
+    if (tool === 'read') {
+      const target = String(call.path || '');
+      if (SKILL_PATH.test(target)) return allow('read:skill-file');
+      // Persisted output of an allowed command is readable; each adapter names its host's paths (audit F-019).
+      if ((deps.readablePaths || []).some((re) => re.test(target))) return allow('read:persisted-output');
+    }
+    if (tool === 'shell' && isSatisfyingCommand(call.command)) return allow('shell:satisfying-command');
+
+    const receipt = deps.check();
+    if (!receipt.ok) {
+      return deny('receipt', `TR-PREFLIGHT gate: ${receipt.problems[0] || 'check failed'} (directory: ${call.cwd || 'unknown'}). `
+        + 'No work may start until it passes. Read the complete context capsule (never pipe or truncate it), then acknowledge.');
+    }
+    if (tool === 'shell' && isRepoSweep(call.command) && !(deps.recentConsult ? deps.recentConsult() : false)) {
+      return deny('sweep', 'TR-PREFLIGHT gate: do not sweep the repository for an answer; Total Recall owns it. Run `total-recall help "<task>"` to find the owning command, or `total-recall recall "<topic>" --local`, then repeat this call.',
+        'total-recall help "<task>"');
+    }
+    return allow('receipt:fresh');
+  } catch (err) {
+    return deny('gate-error', `TR-PREFLIGHT gate error: ${err.message}. The gate fails closed.`);
+  }
+}

package/src/core/preflight-receipt.mjs

@@ -0,0 +1,123 @@
+/**
+ * Preflight receipt: the attestation that an agent read the mandatory skills and
+ * received a ready capsule for one repository. It is an ephemeral per-machine
+ * file (mode 0600), not application state: every hook reads it on every tool
+ * call, so it stays a plain file. Gate decisions are what go to the event log.
+ *
+ * The file location and fields are unchanged from the original `tr-preflight`
+ * command, so receipts written before this module remain valid.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+export const SKILLS = ['.agent/skills/total-recall/SKILL.md', '.agent/skills/ssss/SKILL.md'];
+export const DEFAULT_MAX_AGE_MS = 30 * 60 * 1000;
+export const ACK_COMMAND = 'total-recall tr-preflight --ack --task "<task>" --action read,edit,test';
+
+const BIN = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'bin', 'total-recall.mjs');
+
+/**
+ * The nearest ancestor holding `.agent`, else the directory itself, with symlinks
+ * resolved. A harness may report a symlinked path (`/var` for `/private/var`)
+ * where the shell reports the real one; both must find the same receipt.
+ */
+export function findRoot(cwd = process.cwd()) {
+  const resolve = (p) => { try { return fs.realpathSync(p); } catch { return path.resolve(p); } };
+  const start = resolve(cwd);
+  let dir = start;
+  for (let i = 0; i < 40; i += 1) {
+    if (fs.existsSync(path.join(dir, '.agent'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return start;
+}
+
+const rootKey = (root) => crypto.createHash('sha256').update(root).digest('hex').slice(0, 16);
+const stateDir = (home) => path.join(home, '.agent', 'tr-preflight');
+export const receiptPath = (root, home = os.homedir()) => path.join(stateDir(home), `${rootKey(root)}.json`);
+export const consultPath = (root, home = os.homedir()) => path.join(stateDir(home), `consult-${rootKey(root)}.stamp`);
+
+const sha256 = (file) => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+
+/** Hashes of the mandatory skills, or the list of ones that are missing. */
+export function skillHashes(root) {
+  const hashes = {};
+  const missing = [];
+  for (const rel of SKILLS) {
+    const full = path.join(root, rel);
+    if (fs.existsSync(full)) hashes[rel] = sha256(full);
+    else missing.push(rel);
+  }
+  return { hashes, missing };
+}
+
+export function readReceipt(root, home = os.homedir()) {
+  try { return JSON.parse(fs.readFileSync(receiptPath(root, home), 'utf8')); } catch { return null; }
+}
+
+/**
+ * @returns {{ ok: boolean, problems: string[], receipt: object|null, ageMs: number|null }}
+ * `problems` read the same as the original command so existing guidance still fits.
+ */
+export function checkReceipt(root, { now = Date.now(), maxAgeMs, home = os.homedir() } = {}) {
+  const { hashes, missing } = skillHashes(root);
+  if (missing.length) return { ok: false, problems: missing.map((rel) => `missing mandatory skill: ${rel}`), receipt: null, ageMs: null };
+  const receipt = readReceipt(root, home);
+  if (!receipt) return { ok: false, problems: ['no preflight receipt for this repository'], receipt: null, ageMs: null };
+  const problems = [];
+  const ageMs = now - Date.parse(receipt.at || 0);
+  // The window is decided when the receipt is written, so the hot path never loads configuration.
+  const limit = maxAgeMs ?? (Number.isFinite(receipt.max_age_ms) && receipt.max_age_ms > 0 ? receipt.max_age_ms : DEFAULT_MAX_AGE_MS);
+  if (!Number.isFinite(ageMs) || ageMs > limit) problems.push('preflight receipt is stale; re-run --ack');
+  for (const [rel, hash] of Object.entries(hashes)) {
+    if (!receipt.skills || receipt.skills[rel] !== hash) problems.push(`${rel} changed since the receipt; re-read and re-run --ack`);
+  }
+  if (receipt.ready !== true) problems.push('receipt does not record ready:true');
+  return { ok: problems.length === 0, problems, receipt, ageMs: Number.isFinite(ageMs) ? ageMs : null };
+}
+
+/** Run this package's own CLI, so `ack` uses exactly the semantics every caller gets. */
+function runSelf(args, cwd) {
+  const r = spawnSync(process.execPath, [BIN, ...args], { cwd, encoding: 'utf8', timeout: 60000 });
+  return { ok: r.status === 0, out: r.stdout || '', err: r.stderr || '', code: r.status };
+}
+
+/**
+ * Record a receipt after proving the capsule is ready and the rules verify.
+ * `run` is injectable so the specs need no child process.
+ */
+export function acknowledge({ root, task = '', actions = 'read,edit,test', maxAgeMs, run = runSelf, now = Date.now(), home = os.homedir() }) {
+  const { hashes, missing } = skillHashes(root);
+  if (missing.length) return { ok: false, problems: missing.map((rel) => `missing mandatory skill: ${rel}`) };
+  const context = run(['context', task || '(no task given)', '--action', actions], root);
+  if (!/ready:true/.test(context.out)) {
+    return { ok: false, problems: ['total-recall context did not return ready:true',
+      context.code === 2 ? 'exit 2: capsule overflow; raise --budget or curate applicability, then retry' : `context exit=${context.code ?? '?'}`] };
+  }
+  const version = (context.out.match(/version:([0-9a-f]+)/) || [])[1] || null;
+  const rules = run(['rules', 'verify'], root);
+  if (!rules.ok) return { ok: false, problems: ['total-recall rules verify failed', (rules.out || rules.err).trim().split('\n').slice(-3).join(' | ')] };
+  const receipt = { at: new Date(now).toISOString(), repo: root, task, actions, ready: true, capsule_version: version, skills: hashes, rules_verify: 'ok',
+    ...(Number.isFinite(maxAgeMs) && maxAgeMs > 0 ? { max_age_ms: maxAgeMs } : {}) };
+  const file = receiptPath(root, home);
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(file, `${JSON.stringify(receipt, null, 2)}\n`, { mode: 0o600 });
+  return { ok: true, problems: [], receipt, file };
+}
+
+/** Marks that Total Recall was consulted just now; read by the repository-sweep policy. */
+export function touchConsult(root, { now = Date.now(), home = os.homedir() } = {}) {
+  const file = consultPath(root, home);
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(file, String(now), { mode: 0o600 });
+}
+
+export function lastConsultMs(root, { home = os.homedir() } = {}) {
+  try { return Number(fs.readFileSync(consultPath(root, home), 'utf8')) || 0; } catch { return 0; }
+}

package/src/core/runtime.mjs

@@ -162,10 +162,8 @@ export function loadRuntimeConfig(_configPath) {
       const checkPaths = [
         instructionsFilePath(),
         path.join(surfaceDir(), 'AGENTS.md'),
-        path.join(surfaceDir(), 'GEMINI.md'),
         path.join(agentDir, 'INSTRUCTIONS.md'),
         path.join(agentDir, 'AGENTS.md'),
-        path.join(agentDir, 'GEMINI.md'),
         path.join(path.dirname(agentDir), 'INSTRUCTIONS.md'),
         path.join(path.dirname(agentDir), 'AGENTS.md'),
         path.join(process.cwd(), 'INSTRUCTIONS.md'),
@@ -173,7 +171,6 @@ export function loadRuntimeConfig(_configPath) {
         path.join(process.cwd(), 'Claude.md'),
         // legacy mistaken brainDir locations (kept as last resort)
         path.join(brainDir, 'INSTRUCTIONS.md'),
-        path.join(brainDir, 'GEMINI.md'),
         path.join(brainDir, 'AGENTS.md'),
       ];
       for (const p of checkPaths) {

package/src/core/surface.mjs

@@ -500,6 +500,30 @@ async function writeShim(shimPath, skillsDir, nodes = [], { vaultDir, derivedDir
   const fullContent = prependDirectives(`${mdcHeader}${baseline}`, rulesBlock);
 
   try {
+    const normShim = path.normalize(shimPath);
+    // Antigravity rules deduplication: .agents/rules/AGENTS.md should be a relative
+    // symlink to ../../AGENTS.md so Antigravity resolves realpath and loads it once.
+    if (normShim.endsWith(path.normalize('.agents/rules/AGENTS.md'))) {
+      if (!fs.existsSync(shimDir)) {
+        fs.mkdirSync(shimDir, { recursive: true });
+      }
+      const relTarget = path.join('..', '..', 'AGENTS.md');
+      try {
+        const stat = fs.lstatSync(shimPath, { throwIfNoEntry: false });
+        if (stat) {
+          if (!stat.isSymbolicLink() || fs.readlinkSync(shimPath) !== relTarget) {
+            fs.unlinkSync(shimPath);
+            fs.symlinkSync(relTarget, shimPath);
+          }
+        } else {
+          fs.symlinkSync(relTarget, shimPath);
+        }
+        return true;
+      } catch {
+        // Fall through to regular write if symlink cannot be created
+      }
+    }
+
     const stat = fs.lstatSync(shimPath, { throwIfNoEntry: false });
     if (stat) {
       if (stat.isSymbolicLink()) {
@@ -552,7 +576,6 @@ const CLIENT_SHIMS = {
   roo:                ['.roo/rules/total-recall.md', '.clinerules/total-recall.md'],
   'roo-code':         ['.roo/rules/total-recall.md', '.clinerules/total-recall.md'],
   antigravity:        ['AGENTS.md', '.agents/rules/AGENTS.md'],
-  gemini:             ['GEMINI.md', '.agents/rules/GEMINI.md'],
   codex:              ['AGENTS.md'],
   grok:               ['AGENTS.md'],
   replit:             ['replit.md'],
@@ -647,6 +670,20 @@ async function compilePointers(instructionsFile, skillsDir, nodes = [], { vaultD
   // plugin-store.mjs likewise), so the peel was never correct for either.
   const baseDir = agentDir;
 
+  // Eradicate deprecated Gemini shims so they do not consume context budgets or inject obsolete rules
+  const deprecatedGeminiPaths = [
+    path.join(baseDir, 'GEMINI.md'),
+    path.join(baseDir, '.agent', 'GEMINI.md'),
+    path.join(baseDir, '.agents', 'rules', 'GEMINI.md')
+  ];
+  for (const depPath of deprecatedGeminiPaths) {
+    try {
+      if (fs.existsSync(depPath)) {
+        fs.unlinkSync(depPath);
+      }
+    } catch {}
+  }
+
   // Determine which client shims to write.
   // `baseDir/.agent/skills/...` only holds for a PROJECT brain. For the global
   // brain baseDir already IS the agent dir, so that path became