total-recall-brain 3.19.2 → 3.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.19.2",
+  "version": "3.20.0",
   "description": "Personal AI system — database-free, SSSS-powered intelligence engine deployable to any POSIX host.",
   "type": "module",
   "workspaces": [

package/scaffold/.agent/skills/total-recall/modules/agents/agents.yml

@@ -1,30 +1,66 @@
 agents:
-  - name: antigravity
-    binary: antigravity
-    flags: --sandbox=false --yolo -o json
+  # Google Antigravity CLI. The binary is `agy` (NOT `antigravity`) and it runs
+  # on the AI Ultra plan. Preferred agent for bulk work.
+  #   agy -p "prompt" --output-format json  ->  {status:"SUCCESS", response:"..."}
+  # Docs: https://antigravity.google/docs/cli/headless
+  - name: agy
+    binary: agy
+    flags: --output-format json -p
     priority: 1
     enabled: true
     exec: flag
 
-  - name: grok
-    binary: grok
-    # Grok Build TUI: -p single-turn, plain text for TR parser
-    flags: --output-format plain --always-approve --permission-mode bypassPermissions
-    priority: 2
-    enabled: true
-    exec: flag
-
+  # `-p` MUST be present (non-interactive requires --print) and MUST be LAST:
+  # `--tools` is variadic (`<tools...>`) in the shipped build, so anything after
+  # it — including the appended prompt — is swallowed as a tool name. Proven
+  # both ways on claude v2.1.201.
   - name: claude
     binary: claude
-    flags: --output-format json --permission-mode bypassPermissions --setting-sources local --tools ""
-    priority: 3
+    flags: --output-format json --permission-mode bypassPermissions --setting-sources local --tools "" -p
+    priority: 2
     enabled: true
     exec: flag
+
+  # `-m` is REQUIRED: ~/.codex/config.toml may pin a model the account cannot
+  # use (seen: gpt-5.6-sol -> HTTP 400 "not supported when using Codex with a
+  # ChatGPT account"). Account-supported slugs: ~/.codex/models_cache.json.
+  # `--full-auto` is hidden from --help but still works as a deprecated alias;
+  # the explicit `--sandbox` form is OpenAI's current recommendation.
   - name: codex
     binary: codex
-    flags: --full-auto --json --skip-git-repo-check
-    priority: 4
+    flags: -m gpt-5.5 --sandbox workspace-write --json --skip-git-repo-check
+    priority: 3
     enabled: true
     exec: subcommand
+
+  # DISABLED — `antigravity` on PATH is total-recall/bin/antigravity.mjs, a thin
+  # wrapper that POSTs to generativelanguage.googleapis.com with GOOGLE_API_KEY,
+  # i.e. the METERED Gemini API, not the Ultra plan. Verified 2026-08-01: every
+  # call returned 429 "You exceeded your current quota". Use `agy` above.
+  - name: antigravity
+    binary: antigravity
+    flags: --sandbox=false --yolo -o json
+    priority: 8
+    enabled: false
+    exec: flag
+
+  # DISABLED — this user has no Gemini CLI. Do not enable because a `gemini`
+  # binary resolves on PATH; their Google surface is `agy`.
+  - name: gemini
+    binary: gemini
+    flags: --sandbox=false --yolo -o json
+    priority: 9
+    enabled: false
+    exec: flag
+
+  # DISABLED — not installed. A stale binary may still resolve at
+  # ~/.grok/bin/grok; PATH presence is not proof an agent works.
+  - name: grok
+    binary: grok
+    flags: --output-format plain --always-approve --permission-mode bypassPermissions
+    priority: 10
+    enabled: false
+    exec: flag
+
 timeout: 300
 max_retries: 2

package/src/cli/recall.mjs

@@ -128,6 +128,7 @@ export default async function recall(args) {
     // Search all target brains and merge results
     let allResults = [];
     let isDegraded = false;
+    const searchErrors = [];
 
     for (const target of searchTargets) {
       const vaultDir = path.join(target.brainDir, 'memory-vault');
@@ -168,8 +169,16 @@ export default async function recall(args) {
           r._layer = target.label;
         }
         allResults = allResults.concat(results);
-      } catch {
-        // Skip brains that can't be searched (no embeddings, etc.)
+      } catch (err) {
+        // A brain that cannot be searched is skipped — but NEVER silently.
+        //
+        // This used to be a bare `catch {}`. A missing native binding for
+        // better-sqlite3 ("Could not locate the bindings file") made every
+        // semantic search throw, and the swallow turned a hard dependency
+        // crash into the message "No matching memory nodes found" — so a
+        // fully-populated vault looked empty and the real cause was invisible.
+        // Degrading to lexical-only results is fine; hiding why is not.
+        searchErrors.push({ label: target.label, message: String(err?.message || err) });
       }
     }
 
@@ -182,8 +191,27 @@ export default async function recall(args) {
       return;
     }
 
+    if (searchErrors.length > 0) {
+      // Surface the real cause. "No matches" and "search crashed" are very
+      // different problems and must never look the same.
+      console.log('');
+      for (const e of searchErrors) {
+        console.log(`  ⚠️  ${e.label} brain search failed: ${e.message.split('\n')[0]}`);
+      }
+      if (/bindings file|\.node|NODE_MODULE_VERSION|better-sqlite3/i.test(searchErrors.map(e => e.message).join(' '))) {
+        console.log('      A native module is missing or was built for a different Node version.');
+        console.log('      Fix: pnpm rebuild better-sqlite3   (or npm rebuild better-sqlite3)');
+        console.log('      With pnpm, the package must also be allowed to run build scripts.');
+      }
+      console.log('      Results below (if any) are lexical-only and may be incomplete.');
+    }
+
     if (allResults.length === 0) {
-      console.log('\n  🔍 No matching memory nodes found.');
+      console.log(
+        searchErrors.length > 0
+          ? '\n  🔍 No results — search failed above, so this is NOT proof the vault is empty.'
+          : '\n  🔍 No matching memory nodes found.',
+      );
       return;
     }
     if (isDegraded) {

package/src/core/runtime.mjs

@@ -47,11 +47,21 @@ export function findBinaryInPath(binaryName) {
 
 // ─── Default agent registry (used when agents.yml doesn't exist) ─────────────
 
+// NOTE ON FLAG ORDER AND MODEL PINS (verified by live probe 2026-08-01):
+//   agy    — the REAL Google Antigravity CLI (AI Ultra). The binary named
+//            `antigravity` is a metered Gemini API wrapper, NOT this. Disabled
+//            below; enabling it bills an exhausted API budget (429s).
+//   claude — `-p` is required for non-interactive AND must be LAST, because
+//            `--tools` is variadic and otherwise swallows the prompt.
+//   codex  — `-m` must be pinned; a config.toml model the account cannot use
+//            fails with HTTP 400 at exit code 0.
 const DEFAULT_AGENTS = [
-  { name: 'antigravity', binary: 'antigravity', flags: '--sandbox=false --yolo -o json', priority: 1, enabled: true, exec: 'flag' },
-  { name: 'grok',        binary: 'grok',        flags: '--output-format plain --always-approve --permission-mode bypassPermissions', priority: 2, enabled: true, exec: 'flag' },
-  { name: 'claude',      binary: 'claude',      flags: '--output-format json --permission-mode bypassPermissions --setting-sources local --tools ""', priority: 3, enabled: true, exec: 'flag' },
-  { name: 'codex',       binary: 'codex',       flags: '--sandbox workspace-write --json --skip-git-repo-check', priority: 4, enabled: true, exec: 'subcommand' },
+  { name: 'agy',         binary: 'agy',         flags: '--output-format json -p', priority: 1, enabled: true, exec: 'flag' },
+  { name: 'claude',      binary: 'claude',      flags: '--output-format json --permission-mode bypassPermissions --setting-sources local --tools "" -p', priority: 2, enabled: true, exec: 'flag' },
+  { name: 'codex',       binary: 'codex',       flags: '-m gpt-5.5 --sandbox workspace-write --json --skip-git-repo-check', priority: 3, enabled: true, exec: 'subcommand' },
+  { name: 'antigravity', binary: 'antigravity', flags: '--sandbox=false --yolo -o json', priority: 8, enabled: false, exec: 'flag' },
+  { name: 'gemini',      binary: 'gemini',      flags: '--sandbox=false --yolo -o json', priority: 9, enabled: false, exec: 'flag' },
+  { name: 'grok',        binary: 'grok',        flags: '--output-format plain --always-approve --permission-mode bypassPermissions', priority: 10, enabled: false, exec: 'flag' },
 ];
 
 /**
@@ -299,29 +309,65 @@ export async function callLocalRuntime(prompt, system, config) {
     }
   } catch {}
 
-  // Try agents in priority order with retry budget
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    const agent = attempt === 0 ? resolveAgent(config) : resolveAgent({
-      ...config,
-      agents: agents.filter(a => a.name !== lastError?.agentName),
-    });
+  // Try agents in priority order, never re-trying one that already failed.
+  //
+  // The old filter excluded only `lastError.agentName` — the MOST RECENT
+  // failure — so a chain of three could hand work back to an agent that had
+  // already failed while a healthy one further down was never reached. Track
+  // every failure instead.
+  //
+  // The iteration cap is `agents.length + maxRetries` so that each enabled
+  // agent gets a turn even when the retry budget is smaller than the chain;
+  // the loop exits as soon as the untried pool is empty.
+  const failedAgents = new Set();
+  const maxAttempts = agents.length + maxRetries;
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const remaining = agents.filter(a => !failedAgents.has(a.name));
+    const agent = remaining.length > 0
+      ? resolveAgent({ ...config, agents: remaining })
+      : null;
 
     if (!agent) {
-      throw new Error('No CLI agents available. Install antigravity, grok, claude, or codex.');
+      if (failedAgents.size > 0) {
+        throw new Error(
+          `All CLI agents failed (tried: ${[...failedAgents].join(', ')}). ` +
+          `Last error: ${lastError?.error || 'unknown'}`,
+        );
+      }
+      throw new Error(
+        'No CLI agents available. Install agy (Google Antigravity), claude, or codex.',
+      );
     }
 
+    // The prompt goes LAST, after every flag. Pushing it first (the old
+    // behaviour) broke the registry's own flag sets: it emitted a duplicate
+    // `-p` for agents whose flags already carry one, and it defeats the
+    // ordering that keeps a variadic flag (claude's `--tools <tools...>`) from
+    // swallowing the prompt as one of its values.
     const args = [];
     if (agent.exec === 'subcommand') {
-      args.push('exec', fullPrompt);
-    } else {
-      args.push('-p', fullPrompt);
+      args.push('exec');
     }
     if (agent.flags) {
-      args.push(...agent.flags.split(/\s+/).filter(Boolean));
+      // spawnSync does not go through a shell, so quotes in the registry are
+      // literal characters: `--tools ""` would pass a two-character string
+      // rather than an empty one. Strip matched surrounding quotes per token.
+      args.push(
+        ...agent.flags
+          .split(/\s+/)
+          .filter(Boolean)
+          .map(tok => tok.replace(/^(['"])(.*)\1$/, '$2')),
+      );
     }
     if (agent.model) {
       args.push('-m', agent.model);
     }
+    // `exec: flag` agents need an explicit `-p` only if their flags omit it.
+    if (agent.exec !== 'subcommand' && !args.includes('-p') && !args.includes('--print')) {
+      args.push('-p');
+    }
+    args.push(fullPrompt);
 
     const cmd = `${agent.binaryPath} ${args.map(a => a.includes(' ') || a.includes('\n') ? `"${a.replace(/"/g, '\\"')}"` : a).join(' ')}`;
 
@@ -373,11 +419,27 @@ export async function callLocalRuntime(prompt, system, config) {
       cwd: process.cwd(),
     });
 
-    if (result.status === 0) {
+    const softFailure = detectAgentFailure(result.stdout || '');
+
+    if (result.status === 0 && !softFailure) {
       const output = result.stdout?.trim() || '';
       return parseAgentOutput(output);
     }
 
+    if (softFailure) {
+      // Exit code 0 but the payload says the run failed. Auth and model-config
+      // failures are not transient, so record and move to the next agent
+      // instead of burning the remaining retries on the same broken agent.
+      logger.error({
+        subsystem: 'runtime',
+        message: `${agent.name} reported failure despite exit 0`,
+        error: softFailure.slice(0, 500),
+      });
+      lastError = { agentName: agent.name, error: softFailure.slice(0, 500) };
+      failedAgents.add(agent.name);
+      continue;
+    }
+
     const err = result.stderr || result.stdout || 'Unknown error';
     logger.error({
       subsystem: 'runtime',
@@ -385,9 +447,13 @@ export async function callLocalRuntime(prompt, system, config) {
       error: err.slice(0, 500),
     });
     lastError = { agentName: agent.name, error: err.slice(0, 500) };
+    failedAgents.add(agent.name);
   }
 
-  throw new Error(`All CLI agents failed. Last error: ${lastError?.error || 'unknown'}`);
+  throw new Error(
+    `All CLI agents failed (tried: ${[...failedAgents].join(', ') || 'none'}). ` +
+    `Last error: ${lastError?.error || 'unknown'}`,
+  );
 }
 
 /**
@@ -406,6 +472,57 @@ export async function callLocalRuntimeRaw(messages, config, _tools = undefined)
 /**
  * Parse JSON or text output from a CLI agent into plain text.
  */
+/**
+ * Control-frame `type` values in codex's `--json` event stream. None of them
+ * carry the model's answer.
+ */
+const STREAM_CONTROL_TYPES = new Set([
+  'thread.started', 'turn.started', 'turn.completed', 'turn.failed',
+  'item.started', 'item.updated', 'item.completed', 'error',
+]);
+
+/**
+ * Detects a failure the exit code did not report.
+ *
+ * CLI agents exit 0 on failed runs and describe the failure only in the
+ * payload (verified 2026-08-01):
+ *   claude → {"subtype":"success","is_error":true,"result":"Not logged in …"}
+ *   codex  → {"type":"turn.failed","error":{"message":"…"}}
+ *   agy    → {"status":"ERROR"|"CANCELED","error":"…"}
+ *
+ * Without this, `status === 0` accepts the error text as the model's answer —
+ * e.g. "Not logged in · Please run /login" gets stored as a memory node.
+ *
+ * @param {string} output raw stdout
+ * @returns {string|null} failure reason, or null if the run looks clean
+ */
+function detectAgentFailure(output) {
+  if (!output) return null;
+  for (const line of output.split('\n')) {
+    const t = line.trim();
+    if (!t.startsWith('{')) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(t);
+    } catch {
+      continue;
+    }
+    if (parsed.is_error === true) {
+      return typeof parsed.result === 'string' ? parsed.result : 'is_error: true';
+    }
+    if (parsed.type === 'turn.failed' || parsed.type === 'error') {
+      const msg = parsed.error?.message ?? parsed.message;
+      return typeof msg === 'string' ? msg : String(parsed.type);
+    }
+    if (typeof parsed.status === 'string' && parsed.status.toUpperCase() !== 'SUCCESS') {
+      return typeof parsed.error === 'string'
+        ? `${parsed.status}: ${parsed.error}`
+        : `status=${parsed.status}`;
+    }
+  }
+  return null;
+}
+
 function parseAgentOutput(output) {
   try {
     const parsed = JSON.parse(output);
@@ -418,7 +535,34 @@ function parseAgentOutput(output) {
       return last.content || last.text || last.response || JSON.stringify(last);
     }
   } catch {
-    // Not JSON — return raw text
+    // Not a single JSON document. It may still be a JSONL event stream —
+    // codex `--json` emits one frame per line, so a whole-output JSON.parse
+    // always throws and the raw stream used to be returned as the "answer".
+    const answers = [];
+    for (const line of output.split('\n')) {
+      const t = line.trim();
+      if (!t.startsWith('{')) continue;
+      let frame;
+      try {
+        frame = JSON.parse(t);
+      } catch {
+        continue;
+      }
+      // codex: the reply is item.text of the `agent_message` item.
+      if (frame.item?.type === 'agent_message' && typeof frame.item.text === 'string') {
+        answers.push(frame.item.text);
+        continue;
+      }
+      if (STREAM_CONTROL_TYPES.has(frame.type)) continue;
+      for (const key of ['response', 'result', 'content', 'text']) {
+        if (typeof frame[key] === 'string') {
+          answers.push(frame[key]);
+          break;
+        }
+      }
+    }
+    // Last message wins: earlier frames are partial or superseded.
+    if (answers.length > 0) return answers[answers.length - 1];
   }
   return output;
 }

package/src/core/throttled-fetch.mjs

@@ -552,6 +552,23 @@ export function resetGateStats() {
  * Reset internal rate-limit/concurrency state (for testing only).
  */
 export function resetGateStateForTests() {
+  // Tear down policy watchers FIRST. They are module-level singletons that
+  // outlive an individual test, and their callbacks call applyPolicy() +
+  // drainQueue() — so a watcher registered by an earlier test can fire in the
+  // middle of a later one, silently rewriting blockedDomains/domainMinInterval
+  // and draining the queue. That made the firewall-reject and minInterval
+  // tests fail intermittently under full-suite load while passing in
+  // isolation. Closing them here makes each test start from a quiet state.
+  for (const w of [policyWatcher, parentWatcher]) {
+    try {
+      w?.close();
+    } catch {
+      // already closed / never opened
+    }
+  }
+  policyWatcher = null;
+  parentWatcher = null;
+
   gateGeneration += 1;
   globalInFlight = 0;
   domainInFlight.clear();