total-recall-brain 3.47.0 → 3.47.2

package/src/cli/preflight.mjs

@@ -7,7 +7,7 @@ import { globalBrainDirFor, isBrainEnabled } from '../core/brain-registry.mjs';
 import { GATE_MODES, gateConfigPath, projectBrainDir, readGateLayers, resolveGateMode, writeGateMode } from '../core/gate-mode.mjs';
 import { installHarnessHooks, loadGateAdapters } from '../core/harness-hooks.mjs';
 import { ackDirectory, capsuleVerb, decide, gatePackageBroken, isAckCommand, isCheckCommand, isRouteCommand, isSubagentPayload, nativeToolOf, sessionOf, SWEEP_CONSULT_MS, whenGateFails } from '../core/preflight-gate.mjs';
-import { ACK_COMMAND, acknowledge, checkAgentReceipt, checkAnyReceipt, findRoot, forgetCapsuleDeliveries, lastArrivalMs, lastCapsuleDelivery, lastConsultMs, lastRoutedMs, lastRouteWarnedMs, lastSessionAck, markArrival, markDelegated, markRouted, markRouteWarned, markSessionAck, noteCaller, recordDecision, sessionHasStanding, sessionKey, readDecisions, takeCaller } from '../core/preflight-receipt.mjs';
+import { ACK_COMMAND, acknowledge, checkAgentReceipt, checkAnyReceipt, findRoot, forgetCapsuleDeliveries, lastArrivalMs, lastCapsuleDelivery, lastConsultMs, lastRoutedMs, lastRouteSelection, lastRouteWarnedMs, lastSessionAck, markArrival, markDelegated, markRouted, markRouteSelection, markRouteWarned, markSessionAck, noteCaller, recordDecision, sessionHasStanding, sessionKey, readDecisions, takeCaller } from '../core/preflight-receipt.mjs';
 
 const USAGE = `Usage: total-recall preflight <command>
   ack --task "<task>" [--action read,edit,test] [--json]   Record a receipt after context ready:true and rules verify, and print the capsule.
@@ -19,9 +19,9 @@ const USAGE = `Usage: total-recall preflight <command>
   remind [--json]                                           Prompt-hook entry: advisory text when the receipt is missing; always exits 0
   session-start                                             Session-hook entry: after compaction or clear, the next ack prints the capsule; always exits 0
   install [--harness <id>|--all] [--dry-run]                Install the gate for a harness, or for every harness here. Install and update do this. No off switch.
-  mode [off|warn|enforce|clear] [--plugin <id>|--router] [--repo] [--json]
-                                                            Show or set what happens when work goes around a plugin. Default is warn.
-                                                            The preflight receipt itself has no off switch.
+  mode [enforce] [--plugin <id>|--router] [--repo] [--json]
+                                                            Show gate enforcement status. All plugin and routing gates are permanently
+                                                            enforced; off, warn, and clear bypasses are disabled.
   coverage [--dir <folder>] [--json]                        List plugins as declared or missing; exit 1 on a gap. Default: the shared plugin folder
   verify | report                                           Harness adapters, owned by the cli-agents plugin
 Aliases: total-recall tr-preflight --ack | --check. A receipt lasts 30 minutes (config preflight_max_age_minutes).
@@ -397,6 +397,33 @@ function projectBrainRoot(dir) {
   return brain && isBrainEnabled(brain.brainDir) ? brain.projectRoot : null;
 }
 
+/** How long a route's selection binds when the receipt names no window: the default receipt lifetime. */
+const ROUTE_SELECTION_MS = 30 * 60000;
+
+/**
+ * Records which harness a router command selected, so the gate can deny writes from the others.
+ * Called after the router plugin's own command runs, with what it printed. Output that is not a
+ * route result records nothing. Bookkeeping only: it never throws.
+ * @returns {string|null|undefined} the selected harness, null when the route chose none, undefined when nothing was recorded
+ */
+export function noteRouteSelection({ manifest, args = [], stdout = '', cwd = process.cwd() } = {}) {
+  try {
+    const router = manifest?.gate?.router;
+    if (!router?.pattern) return undefined;
+    const command = `${manifest.cli?.command || manifest.id} ${args.map(String).join(' ')}`;
+    if (!new RegExp(`(?:^|\\s)(?:${router.pattern})(\\s|$)`).test(command)) return undefined;
+    const text = String(stdout || '').trim();
+    let result;
+    try { result = JSON.parse(text); } catch { result = JSON.parse(text.split('\n').pop()); }
+    if (!result || typeof result !== 'object' || !('selected' in result)) return undefined;
+    const selected = typeof result.selected === 'string' && result.selected ? result.selected : null;
+    const root = findRoot(cwd);
+    markRouted(root);
+    markRouteSelection(root, selected);
+    return selected;
+  } catch { return undefined; }
+}
+
 /** The gate's answer to a call. Nothing here may throw, because an answer is all that keeps its repair reachable. */
 function evaluate(call, options = {}) {
   try {
@@ -450,6 +477,13 @@ function judge(call, { harness, readablePaths, session = null, subagent = false,
     ownerHealthy: (plugin, use) => ownerRuns(plugin, use, root),
     // A subagent or a run the router started reports to whoever routed the work.
     dispatched: runByRouter || subagent || Boolean(session && !ownAck),
+    // Only a named harness can be told apart from the one the router chose.
+    harness: harness && harness !== 'generic' ? harness : null,
+    routerRun: runByRouter,
+    selection: (receipt) => {
+      const chosen = lastRouteSelection(root);
+      return chosen && Date.now() - chosen.at < (limit ?? receipt?.limitMs ?? ROUTE_SELECTION_MS) ? chosen : null;
+    },
     check,
     recentConsult: () => {
       const now = Date.now();
@@ -569,14 +603,14 @@ async function mode(args) {
   const repo = args.includes('--repo');
   const brain = repo ? projectBrainDir(root) : globalBrainDirFor();
   if (value !== undefined) {
-    if (value !== 'clear' && !GATE_MODES.includes(value)) return fail(`Unknown mode "${value}". Choose ${GATE_MODES.join(', ')} or clear.`);
+    if (value !== 'enforce') return fail(`✖ Plugin and routing gates are permanently enforced and have no "${value}" bypass.`);
     const plugin = flag(args, '--plugin');
     const router = args.includes('--router');
     if (plugin && router) return fail('Choose --plugin or --router, not both.');
     if (plugin && !plugins.includes(plugin)) return fail(`No plugin here declares raw commands under "${plugin}". Declared: ${plugins.join(', ') || 'none'}.`);
     if (router && !declared.router) return fail('No plugin here declares a router.');
     if (repo && !fs.existsSync(brain)) return fail(`${root} has no project brain to hold this setting. Run total-recall init there, or leave off --repo.`);
-    writeGateMode(brain, { mode: value === 'clear' ? null : value, plugin, router });
+    writeGateMode(brain, { mode: 'enforce', plugin, router });
   }
   const layers = readGateLayers({ globalBrainDir: globalBrainDirFor(), root });
   const { adapters } = await loadGateAdapters(root);

package/src/cli/update.mjs

@@ -17,7 +17,7 @@ import {
 } from '../core/package-auto-update.mjs';
 import { brainDir } from '../core/config.mjs';
 import { installAutoPull } from '../core/autopull-install.mjs';
-import { updateAllBrains } from '../core/brain-updates.mjs';
+import { updateAllBrains, ensureBrainDefaults } from '../core/brain-updates.mjs';
 import { installHarnessHooks } from '../core/harness-hooks.mjs';
 import { automaticUpdateStatus, runAutomaticBrainUpdates } from '../core/automatic-brain-updates.mjs';
 import { runningServerStatus } from '../core/running-server.mjs';
@@ -38,6 +38,7 @@ export function parseArgs(args) {
     automatic: false,
     status: false,
     localOnly: false,
+    defaults: false,
   };
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
@@ -55,6 +56,7 @@ export function parseArgs(args) {
     else if (a === '--automatic') opts.automatic = true;
     else if (a === '--status') opts.status = true;
     else if (a === '--local-only') opts.localOnly = true;
+    else if (a === '--defaults') opts.defaults = true;
   }
   return opts;
 }
@@ -85,6 +87,12 @@ function printHelp() {
         installed plugin from its recorded source and refresh surfaces. Where a
         per-user service (LaunchAgent, systemd user unit) runs the server from
         the global install, also restart a stale server and verify /health.
+        When this run installed a release newer than the running code, that release
+        refreshes the defaults with its own code (update --defaults) in the same pass.
+    total-recall update --defaults [--repo <path>] [--json]
+        Refresh the shared default plugins from this release's bundled copies (a
+        linked owner checkout is left alone) and provision every registered brain.
+        Exit 1 when any brain fails.
     total-recall update --status [--json]
         Read the actual last automatic maintenance report without starting work.
         Also reports what the server on this host runs against the release.
@@ -121,6 +129,17 @@ export default async function update(args = []) {
     console.log(JSON.stringify(status,null,2));
     return status;
   }
+  if (opts.defaults) {
+    const report = ensureBrainDefaults({ brainDir, roots: opts.repos });
+    if (opts.json) console.log(JSON.stringify(report, null, 2));
+    else {
+      console.log(`\n  Default plugins: ${report.results.length - report.failed} brain(s) ready, ${report.failed} failed`);
+      for (const row of report.results) console.log(`    ${row.status === 'ready' ? '✓' : '✗'} ${row.root}${row.error ? `: ${row.error}` : ''}`);
+      console.log('');
+    }
+    if (report.failed) process.exitCode = 1;
+    return report;
+  }
   if(opts.automatic){
     const report=await runAutomaticBrainUpdates({brainDir,force:opts.force,fleet:!opts.localOnly});
     console.log(JSON.stringify(report,null,2));

package/src/core/automatic-brain-updates.mjs

@@ -14,6 +14,7 @@ import { updateSourceBrainPackages } from './source-brain-updates.mjs';
 import { updateInstalledPlugins } from './plugin-updates.mjs';
 import { runningServerStatus } from './running-server.mjs';
 import { replaceStaleServer } from './server-restart.mjs';
+import { handOffDefaultsToRelease } from './release-defaults-handoff.mjs';
 
 export function automaticUpdateStatus(brainDir) {
   let last;
@@ -38,7 +39,7 @@ export function startAutomaticBrainUpdates({brainDir,intervalMs=60*60*1000,run=r
   return {tick,stop(){stopped=true;clearInterval(timer);}};
 }
 
-export async function runAutomaticBrainUpdates({brainDir,fleet=false,force=false,skipThrottle=false,intervalMs=60*60*1000,update=updateAllBrains,compile=maintainCliSurfaces,globalUpdate=updateGlobalBrainPackages,meshUpdate=updateMeshBrainPackages,sourceUpdate=updateSourceBrainPackages,pluginUpdate=updateInstalledPlugins,skillMaintenance=maintainPortableSkills,serverCheck=runningServerStatus,replaceServer=replaceStaleServer,now=Date.now}={}) {
+export async function runAutomaticBrainUpdates({brainDir,fleet=false,force=false,skipThrottle=false,intervalMs=60*60*1000,update=updateAllBrains,compile=maintainCliSurfaces,globalUpdate=updateGlobalBrainPackages,meshUpdate=updateMeshBrainPackages,sourceUpdate=updateSourceBrainPackages,pluginUpdate=updateInstalledPlugins,defaultsHandoff=handOffDefaultsToRelease,skillMaintenance=maintainPortableSkills,serverCheck=runningServerStatus,replaceServer=replaceStaleServer,now=Date.now}={}) {
   if(!force && !isPackageAutoUpdateEnabled())return {skipped:true,reason:'disabled',results:[]};
   const file=path.join(brainDir,'memory-derived/automatic-brain-updates.json');
   let saved;try{saved=JSON.parse(fs.readFileSync(file,'utf8'));}catch{}
@@ -62,10 +63,13 @@ export async function runAutomaticBrainUpdates({brainDir,fleet=false,force=false
       const summary=await update({brainDir,dryRun:false,ensureDefaults:true});
       const global=summary.versions?await globalUpdate({versions:summary.versions}):{failed:1,results:[],error:'Cannot maintain global packages without verified published versions'};
       const sources=summary.versions?await sourceUpdate({brainDir,versions:summary.versions}):{failed:1,results:[]};
+      // The defaults above came from the running code, which is the release being replaced. A newer
+      // release installed just now refreshes them with its own code and bundled copies, this pass.
+      const defaults=await defaultsHandoff({global,sources});
       // The shared plugin folder follows the source each plugin was installed from (git, mesh peer, directory).
       const plugins=await pluginUpdate({roots:[path.resolve(brainDir,'../../..')]});
       const mesh=fleet && summary.versions?await meshUpdate({versions:summary.versions,version:summary.versions['total-recall-brain']}):{failed:0,results:[],scope:'local-only'};
-      const changed=summary.updated>0 || plugins.updated>0 || global.results.some(row=>row.status==='updated') || sources.results.some(row=>row.status==='updated') || JSON.stringify(saved?.versions)!==JSON.stringify(summary.versions);
+      const changed=summary.updated>0 || plugins.updated>0 || defaults.status==='refreshed' || global.results.some(row=>row.status==='updated') || sources.results.some(row=>row.status==='updated') || JSON.stringify(saved?.versions)!==JSON.stringify(summary.versions);
       const skills=await skillMaintenance({brainDir});
       const surfaces=await compile({brainDir,force:changed || skills.updated > 0});
       // Last, so a replaced server starts on everything this run moved. Where maintenance cannot
@@ -79,8 +83,8 @@ export async function runAutomaticBrainUpdates({brainDir,fleet=false,force=false
       // local_failed is this node's own maintenance. Peers judge a node by it, not by
       // `failed`, which also counts the node's view of its peers: judging by that made
       // every fleet pass mark every peer failed forever, each because the others had.
-      const local_failed=(summary.failed || 0)+global.failed+sources.failed+plugins.failed+(skills.failed || 0)+(surfaces.ok?0:surfaces.results.filter(row=>row.status==='failed').length)+serverFailed;
-      report={...summary,global,sources,plugins,mesh,server,skills,surfaces,local_failed,failed:local_failed+mesh.failed,checkedAt:now()};
+      const local_failed=(summary.failed || 0)+global.failed+sources.failed+(defaults.status==='failed'?1:0)+plugins.failed+(skills.failed || 0)+(surfaces.ok?0:surfaces.results.filter(row=>row.status==='failed').length)+serverFailed;
+      report={...summary,global,sources,defaults,plugins,mesh,server,skills,surfaces,local_failed,failed:local_failed+mesh.failed,checkedAt:now()};
     }catch(error){report={failed:1,error:error.message,checkedAt:now(),results:[]};}
     const temporary=`${file}.${process.pid}.tmp`;fs.writeFileSync(temporary,JSON.stringify(report,null,2));fs.renameSync(temporary,file);
     return report;

package/src/core/brain-updates.mjs

@@ -217,18 +217,37 @@ export function installEnv(env = process.env) {
   return kept;
 }
 
+/** The brains maintenance provisions: each update root that has a brain, plus the selected brain. */
+function maintainedBrains(roots, brainDir) {
+  const brains = roots.map(root => ({ root, brain: path.join(root, '.agent', 'skills', 'total-recall') }))
+    .filter(({ brain }) => fs.existsSync(brain));
+  if (brainDir) brains.push({ root: brainDir, brain: brainDir });
+  return brains;
+}
+
+/**
+ * Refresh the shared default plugins from this package's bundled copies and provision every
+ * registered brain, reporting each brain's outcome instead of throwing. `update --defaults` runs
+ * this, so a release maintenance has just installed can do it with its own code and its own
+ * bundled copies (release-defaults-handoff.mjs).
+ */
+export function ensureBrainDefaults(opts = {}, { ensure = ensureRequiredPlugins } = {}) {
+  const roots = listUpdateRoots(opts).map(row => row.root);
+  const results = maintainedBrains(roots, opts.brainDir).map(({ root, brain }) => {
+    try { ensure(brain); return { root, status: 'ready' }; }
+    catch (error) { return { root, status: 'failed', error: error.message }; }
+  });
+  return { failed: results.filter(row => row.status === 'failed').length, results };
+}
+
 export async function updateAllBrains(opts = {}) {
   const dryRun = opts.dryRun !== false;
   const installMissing = opts.installMissing === true;
   const exec = opts.exec || spawnSync;
   const roots = listUpdateRoots(opts).map(row => row.root);
   const errors = [];
-  const brains = roots.map(root => ({ root, brain: path.join(root, '.agent', 'skills', 'total-recall') }))
-    .filter(({ brain }) => fs.existsSync(brain));
-  if (opts.brainDir) {
-    brains.push({ root: opts.brainDir, brain: opts.brainDir });
-    roots.push(opts.brainDir);
-  }
+  const brains = maintainedBrains(roots, opts.brainDir);
+  if (opts.brainDir) roots.push(opts.brainDir);
   for (const { root, brain } of brains) {
     if (!dryRun && opts.ensureDefaults === true) {
       try { ensureRequiredPlugins(brain); }

package/src/core/gate-mode.mjs

@@ -1,19 +1,15 @@
 /**
  * Modes for the gate rules that steer work toward a plugin: raw commands a plugin owns, and
- * routing. `off` does nothing, `warn` lets the call run and tells the agent, `enforce` blocks.
- * The preflight receipt is not one of these rules and has no mode.
+ * routing. Gates are permanently enforced (`enforce`): there is no `off` or `warn` bypass.
  *
- * Settings live in `config/gate.json` in a brain:
- *   { "default": "warn", "router": "enforce", "plugins": { "git": "enforce" } }
- * The repository's brain wins over the machine's. This runs on every tool call, so it reads the
- * files directly, and an unreadable file or unknown value counts as unset: a bad settings file
- * must never be what blocks work.
+ * Settings live in `config/gate.json` in a brain. Any legacy `off` or `warn` values in
+ * `gate.json` are ignored so enforcement cannot be disabled on disk.
  */
 import fs from 'node:fs';
 import path from 'node:path';
 
-export const GATE_MODES = ['off', 'warn', 'enforce'];
-export const DEFAULT_GATE_MODE = 'warn';
+export const GATE_MODES = ['enforce'];
+export const DEFAULT_GATE_MODE = 'enforce';
 
 export const gateConfigPath = (brainDir) => path.join(brainDir, 'config', 'gate.json');
 export const projectBrainDir = (root) => path.join(root, '.agent', 'skills', 'total-recall');
@@ -30,39 +26,32 @@ export function readGateLayers({ globalBrainDir, root }) {
   return [readSettings(projectBrainDir(root)), readSettings(globalBrainDir)];
 }
 
-const known = (value) => (GATE_MODES.includes(value) ? value : undefined);
-
 /**
  * @param {object[]} layers from readGateLayers
  * @param {'router'|'owned'} kind
  * @param {string} [plugin] the owning plugin, for `owned`
  */
-export function resolveGateMode(layers, kind, plugin) {
-  for (const layer of layers) {
-    const specific = kind === 'router' ? known(layer.router) : known(layer.plugins?.[plugin]);
-    const mode = specific ?? known(layer.default);
-    if (mode) return mode;
-  }
+export function resolveGateMode(_layers, _kind, _plugin) {
   return DEFAULT_GATE_MODE;
 }
 
 /**
- * Change one setting and leave the others alone. A `mode` of null removes the setting, so
- * that level follows the next layer again.
+ * Persist `enforce` mode. `off`, `warn`, and clearing are refused.
  * @param {string} brainDir
  * @param {{ mode: string|null, plugin?: string, router?: boolean }} change
  */
 export function writeGateMode(brainDir, { mode, plugin, router }) {
+  if (mode !== 'enforce') {
+    throw new Error('Plugin and routing gates are permanently enforced and cannot be set to off, warn, or cleared.');
+  }
   const settings = readSettings(brainDir);
   if (router) {
-    if (mode === null) delete settings.router; else settings.router = mode;
+    settings.router = 'enforce';
   } else if (plugin) {
     settings.plugins = settings.plugins && typeof settings.plugins === 'object' ? settings.plugins : {};
-    if (mode === null) delete settings.plugins[plugin]; else settings.plugins[plugin] = mode;
-  } else if (mode === null) {
-    delete settings.default;
+    settings.plugins[plugin] = 'enforce';
   } else {
-    settings.default = mode;
+    settings.default = 'enforce';
   }
   const file = gateConfigPath(brainDir);
   fs.mkdirSync(path.dirname(file), { recursive: true });

package/src/core/plugin-distribution.mjs

@@ -12,7 +12,41 @@ function describePluginWithShare(plugin, projectRoot) {
   return result;
 }
 
-async function resolveBundle(source, { peerDeps, publicDeps } = {}) {
+async function resolveStoreBundle(id, { storeUrl = process.env.TR_STORE_URL || 'http://127.0.0.1:3000', fetchImpl = fetch, licenseKey } = {}) {
+  const base = storeUrl.replace(/\/+$/, '');
+  const headers = {};
+  const resolvedKey = licenseKey || process.env[`${id.toUpperCase().replace(/-/g, '_')}_LICENSE_KEY`] || process.env.TR_LICENSE_KEY;
+  if (resolvedKey) headers['x-license-key'] = resolvedKey;
+  const listRes = await fetchImpl(`${base}/api/store/plugins?q=${encodeURIComponent(id)}`);
+  if (!listRes.ok) throw new Error(`Store catalog unavailable (HTTP ${listRes.status})`);
+  const listData = await listRes.json();
+  const entry = (listData.plugins || []).find((p) => p.id === id);
+  if (!entry) throw new Error(`Plugin '${id}' not found in Store catalog`);
+  const bundleRes = await fetchImpl(`${base}/api/store/plugins/${encodeURIComponent(id)}/bundle`, { headers });
+  if (!bundleRes.ok) {
+    let reason = `HTTP ${bundleRes.status}`;
+    try { const err = await bundleRes.json(); if (err?.error) reason = err.error; } catch {}
+    throw new Error(`Store install denied for '${id}': ${reason}`);
+  }
+  const bundle = Buffer.from(await bundleRes.arrayBuffer());
+  const sha256 = bundleRes.headers?.get?.('x-plugin-sha256') || entry.sha256;
+  return { bundle, sha256, sourceRecord: { kind: 'store', ref: `store:${id}`, store_url: base }, expectedId: id };
+}
+
+async function resolveBundle(source, { peerDeps, publicDeps, storeDeps } = {}) {
+  if (typeof source === 'string' && source.startsWith('store:')) {
+    const id = source.slice('store:'.length).trim();
+    if (!id) throw new Error('Missing plugin id in store:<id>');
+    const { bundle, sha256, sourceRecord, expectedId } = await resolveStoreBundle(id, storeDeps);
+    const decoded = decodeBundle(bundle, sha256 ? { expectedSha256: sha256 } : {});
+    const entry = decoded.entries.find(e => e.path === 'plugin.json');
+    if (!entry) throw new Error('Store plugin bundle has no plugin.json');
+    const manifest = JSON.parse(entry.data.toString('utf8'));
+    const validation = validatePluginManifest(manifest);
+    if (!validation.valid) throw new Error(`Invalid plugin manifest: ${validation.errors.join('; ')}`);
+    if (manifest.id !== expectedId) throw new Error(`Requested '${expectedId}' but bundle contained '${manifest.id}'`);
+    return { manifest, entries: decoded.entries, sha256: decoded.sha256, source: sourceRecord };
+  }
   const peerModule = typeof source === 'string' && source.startsWith('peer:')
     ? await import('./plugin-peers.mjs') : null;
   const peer = peerModule?.parsePeerSource(source);

package/src/core/preflight-gate.mjs

@@ -29,6 +29,10 @@
  *      (`gate.router`). Reading, searching and native subagents stay open, as does any
  *      plain Total Recall command, so routing can always run. A process the router
  *      started has already been routed. It warns once per receipt, not on every call.
+ *   8. With a receipt, once the router has selected a harness for this repository, a write from
+ *      any other harness is denied, whatever the mode. Only a run the router started may write
+ *      for it. A selection lasts as long as a receipt, and routing again replaces it. A call with
+ *      no named harness is not judged by this rule, because it cannot be told apart.
  * Rules 6 and 7 follow a mode (see gate-mode.mjs): `off`, `warn` (the default) or `enforce`.
  * `enforce` blocks only while the owner passes its health check, so a broken plugin can
  * never trap an agent. Warnings are statements of fact, because harnesses treat
@@ -154,6 +158,13 @@ export function ackDirectory(command, cwd) {
   return target ? path.resolve(cwd || process.cwd(), target.replace(/^(["'])([\s\S]*)\1$/, '$2')) : cwd;
 }
 
+export function isBlockedGrep(command) {
+  const text = runnableText(command);
+  if (/(^|[\s;&|(])(grep|egrep|fgrep|rg|ripgrep|ag)(\s|$)/.test(text)) return true;
+  if (/(^|[\s;&|(])git\s+grep(\s|$)/.test(text)) return true;
+  return false;
+}
+
 /** 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 || '');
@@ -235,10 +246,7 @@ const staleness = (receipt) => (receipt.ageMs > receipt.limitMs
  * What a rule that steers work toward a plugin does with a call it matched: nothing (null),
  * a denial, or a warning to carry.
  */
-function steer(deps, { kind, plugin, name, reason, note, use }) {
-  const mode = deps.mode ? deps.mode(kind, plugin) : DEFAULT_GATE_MODE;
-  if (mode === 'off') return null;
-  if (mode !== 'enforce') return { name, warning: note };
+function steer(deps, { plugin, name, reason, note, use }) {
   if (!deps.ownerHealthy || deps.ownerHealthy(plugin, use)) return deny(name, reason, use);
   return { name, warning: `${note} The ${plugin} plugin failed its health check, so this call was not blocked.` };
 }
@@ -287,7 +295,7 @@ export function whenGateFails(call, err) {
 
 /**
  * @param {{ tool: string, command?: string, path?: string, cwd?: string }} call
- * @param {{ check: () => { ok: boolean, problems: string[], ageMs?: number|null, limitMs?: number }, recentConsult?: () => boolean, readablePaths?: RegExp[], ownedCommands?: () => { plugin: string, pattern: string, use: string }[], router?: () => ({ plugin: string, pattern: string, use: string } | null), routed?: (receipt: object) => boolean, routeWarned?: (receipt: object) => boolean, sessionAcknowledged?: (receipt: object) => boolean, sessionLapsed?: () => boolean, arrival?: () => (string | null), dispatched?: boolean, mode?: (kind: 'router'|'owned', plugin: string) => string, ownerHealthy?: (plugin: string, use: string) => boolean }} deps
+ * @param {{ check: () => { ok: boolean, problems: string[], ageMs?: number|null, limitMs?: number }, recentConsult?: () => boolean, readablePaths?: RegExp[], ownedCommands?: () => { plugin: string, pattern: string, use: string }[], router?: () => ({ plugin: string, pattern: string, use: string } | null), routed?: (receipt: object) => boolean, routeWarned?: (receipt: object) => boolean, sessionAcknowledged?: (receipt: object) => boolean, sessionLapsed?: () => boolean, arrival?: () => (string | null), dispatched?: boolean, harness?: string|null, routerRun?: boolean, selection?: (receipt: object) => ({ harness: string|null, at: number } | null), mode?: (kind: 'router'|'owned', plugin: string) => string, ownerHealthy?: (plugin: string, use: string) => boolean }} deps
  */
 export function decide(call, deps) {
   try {
@@ -313,14 +321,26 @@ export function decide(call, deps) {
         : `this session has not acknowledged (directory: ${call.cwd || 'unknown'}). A receipt from another agent does not count.`;
       return deny('receipt:session', `TR-PREFLIGHT gate: ${state} ${nextStep(call)}`);
     }
-    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.',
+    if (tool === 'shell' && isBlockedGrep(call.command)) {
+      return deny('grep', 'TR-PREFLIGHT gate: `grep`/`rg`/`ag` is blocked. Use Total Recall OpenWiki (`total-recall openwiki` / `openwiki/`) or `total-recall recall "<topic>" --local` instead.',
+        'total-recall openwiki hubs --json');
+    }
+    if ((tool === 'search' || (tool === 'shell' && isRepoSweep(call.command))) && !(deps.recentConsult ? deps.recentConsult() : false)) {
+      return deny('sweep', 'TR-PREFLIGHT gate: do not sweep or search the repository before consulting Total Recall / OpenWiki. Run `total-recall openwiki hubs --json`, `total-recall recall "<topic>" --local`, or `total-recall help "<task>"` first.',
         'total-recall help "<task>"');
     }
+    const router = deps.router ? deps.router() : null;
+    if (tool === 'write' && deps.harness && !deps.routerRun) {
+      const chosen = deps.selection ? deps.selection(receipt) : null;
+      if (chosen?.harness && chosen.harness !== deps.harness) {
+        const by = router?.plugin || 'the router';
+        return deny('route:selected', `TR-PREFLIGHT gate: ${by} selected ${chosen.harness} for this task, so ${deps.harness} may not write here. Only a run ${by} started may write: hand the task over with its --execute form, or route it again.`,
+          router?.use || 'route the task again');
+      }
+    }
     const notes = [];
     const arrival = deps.arrival ? deps.arrival() : null;
     if (arrival) notes.push({ name: 'arrival', warning: arrival });
-    const router = deps.router ? deps.router() : null;
     if (router && !deps.dispatched) {
       const open = ['read', 'search', 'web', 'agent'].includes(tool) || (tool === 'shell' && isPlainTotalRecall(call.command));
       if (!open && !(deps.routed ? deps.routed(receipt.receipt) : false)) {

package/src/core/preflight-receipt.mjs

@@ -339,6 +339,17 @@ export function lastRouteWarnedMs(root, { home = os.homedir(), session = null }
   return readStamp(routeWarnedPath(root, home, session));
 }
 
+const selectionPath = (root, home) => path.join(stateDir(home), scoped('route-selected', root));
+
+/** The harness the router chose for work in this repository, or null when it chose none. */
+export function markRouteSelection(root, harness, { home = os.homedir(), now = Date.now() } = {}) {
+  writeBookkeeping(selectionPath(root, home), (target) => fs.writeFileSync(target, JSON.stringify({ at: now, harness: harness || null, root }), { mode: 0o600 }));
+}
+
+export function lastRouteSelection(root, { home = os.homedir() } = {}) {
+  return newestRecord(selectionPath(root, home));
+}
+
 const sessionAckPath = (session, home) => path.join(stateDir(home), `session-ack-${sessionKey(session)}.stamp`);
 const delegatedPath = (root, home) => path.join(stateDir(home), scoped('delegated', root));
 

package/src/core/release-defaults-handoff.mjs

@@ -0,0 +1,89 @@
+/**
+ * Automatic maintenance refreshes the default plugins before it installs a new release: the code
+ * that runs it is the old release, and so are its bundled copies. A default is replaced only by a
+ * higher bundled version, so that pass changed nothing and a release's defaults arrived one pass
+ * (about an hour) later. After the global and source updates, the newest installed release of this
+ * package refreshes the defaults itself, with its own code and its own bundled copies.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { PACKAGE_ROOT } from './plugin-loader.mjs';
+import { comparePackageVersions } from './package-version.mjs';
+import { findLinkedSourceCheckout } from './global-brain-updates.mjs';
+import { runBounded } from './startup-health.mjs';
+
+const PACKAGE = 'total-recall-brain';
+
+function readVersion(dir) {
+  try { return JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')).version || null; } catch { return null; }
+}
+
+/**
+ * The release this process runs, read once at import. A source update can fast-forward this
+ * checkout during the run, so reading the file again later would report the new release.
+ */
+export const RUNNING_VERSION = readVersion(PACKAGE_ROOT);
+
+/** Installed releases this run may have moved: the global install and source checkouts it updated. */
+export function installedReleases({ global, sources } = {}) {
+  const dirs = new Set();
+  const add = dir => { try { dirs.add(fs.realpathSync(dir)); } catch {} };
+  if (global?.root) {
+    const direct = path.join(global.root, PACKAGE);
+    const dir = fs.existsSync(direct) ? direct : findLinkedSourceCheckout(global.root, PACKAGE);
+    if (dir) add(dir);
+  }
+  for (const row of sources?.results || []) {
+    if (row?.package === PACKAGE && row.status === 'updated' && row.root) add(row.root);
+  }
+  return [...dirs]
+    .map(dir => ({ dir, version: readVersion(dir) }))
+    .filter(release => release.version && fs.existsSync(path.join(release.dir, 'bin', 'total-recall.mjs')));
+}
+
+/** The JSON report `update --defaults --json` prints, even after other output on stdout. */
+export function parseDefaultsReport(text) {
+  const trimmed = String(text || '').trim();
+  try { return JSON.parse(trimmed); } catch {}
+  const start = trimmed.lastIndexOf('\n{\n');
+  if (start >= 0) { try { return JSON.parse(trimmed.slice(start + 1)); } catch {} }
+  return null;
+}
+
+/**
+ * When an installed release is newer than the running code, run its `update --defaults` and report
+ * what it did. Never throws: the outcome is a row in the maintenance report.
+ * @returns {Promise<{status:'current'|'refreshed'|'failed', running?:string|null, installed?:string, version?:string, from?:string|null, results?:object[], error?:string}>}
+ */
+export async function handOffDefaultsToRelease({ global, sources, cwd = process.cwd(), running = RUNNING_VERSION,
+  execPath = process.execPath, run = runBounded, timeoutMs = 10 * 60 * 1000 } = {}) {
+  let newest = null;
+  try {
+    for (const release of installedReleases({ global, sources })) {
+      if (!newest || comparePackageVersions(release.version, newest.version) === 1) newest = release;
+    }
+  } catch (error) {
+    return { status: 'failed', running, error: `Installed releases could not be read: ${error.message}` };
+  }
+  if (!newest || comparePackageVersions(newest.version, running) !== 1) {
+    return { status: 'current', running, ...(newest ? { installed: newest.version } : {}) };
+  }
+  const handoff = { version: newest.version, from: running };
+  let result;
+  try {
+    result = await run(execPath, [path.join(newest.dir, 'bin', 'total-recall.mjs'), 'update', '--defaults', '--json'],
+      { cwd, timeoutMs, maxBytes: 1024 * 1024 });
+  } catch (error) {
+    return { status: 'failed', ...handoff, error: `update --defaults could not run: ${error.message}` };
+  }
+  const report = parseDefaultsReport(result?.output);
+  if (result?.code === 0 && report && report.failed === 0) {
+    return { status: 'refreshed', ...handoff, results: report.results || [] };
+  }
+  const failures = (report?.results || []).filter(row => row.status === 'failed').map(row => `${row.root}: ${row.error}`);
+  const error = result?.reason ? `update --defaults stopped: ${result.reason}`
+    : failures.length ? failures.join('; ')
+      : !report ? `update --defaults printed no report (exit ${result?.code ?? 'unknown'}): ${String(result?.stderr || result?.output || '').trim().slice(-1000)}`
+        : `update --defaults exited ${result?.code}`;
+  return { status: 'failed', ...handoff, error, ...(report?.results ? { results: report.results } : {}) };
+}