total-recall-brain 3.47.1 → 3.47.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.47.1",
+  "version": "3.47.3",
   "description": "The Vibe Coding Brain & Autonomous Software Factory: memory, rules, secrets, and 33 visual plugins automatically managed across all your devices.",
   "type": "module",
   "bin": {

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/package-lock.json

@@ -1,17 +1,17 @@
 {
   "name": "tr-plugin-meta-harness",
-  "version": "0.4.0",
+  "version": "0.4.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "tr-plugin-meta-harness",
-      "version": "0.4.0",
+      "version": "0.4.3",
       "dependencies": {
         "@gregiteen/ssss-cli": "0.14.5"
       },
       "devDependencies": {
-        "total-recall-brain": "3.45.0"
+        "total-recall-brain": "3.47.1"
       }
     },
     "node_modules/@alcalzone/ansi-tokenize": {
@@ -5546,9 +5546,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.45.0",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.45.0.tgz",
-      "integrity": "sha512-HDYfROazZbsLHQsFPnlBcSpe1HL1QEi7JG8x/eNRUI06RxVQsZWl8LwBo2lTWjWRDrKmCy7BUmSXQDuWF3lrEw==",
+      "version": "3.47.1",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.47.1.tgz",
+      "integrity": "sha512-9yDByVZMNxNE10hjPf0vEmvBLGGUpD8sqAN7svuZpJEb2TSTPA1eSSwaZ5H4QScJQTT3DcV8MeQjuyLy8urnEw==",
       "dev": true,
       "license": "MIT",
       "workspaces": [

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tr-plugin-meta-harness",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Total Recall Metaharness plugin",
   "type": "module",
   "scripts": {

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "meta-harness",
   "name": "Metaharness",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Discover, configure, document, track, and run coding agent harnesses through Total Recall across mesh nodes.",
   "gate": {
     "tasks": ["Run work in another agent harness", "Choose which harness takes a task", "Check harness versions, sign-in and quota", "Read a harness's official documentation"],

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/dispatch.mjs

@@ -79,7 +79,7 @@ export async function dispatchWithReceipt(request, { dispatchFn, node = request.
     // exhausted until its reset and picks another included harness instead of choosing it again.
     if (result.failureKind === 'quota') {
       try { await record({ harness: request.agent, role, task: String(request.contextTask || request.prompt || '').slice(0, 200), success: false,
-        failureKind: 'quota', error: result.error, resetsAt: result.resetsAt || null }); } catch { /* bookkeeping must not hide the refusal */ }
+        failureKind: 'quota', billingMode, error: result.error, resetsAt: result.resetsAt || null }); } catch { /* bookkeeping must not hide the refusal */ }
     }
     return { ...result, launchPrevented, durationMs };
   }

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/included-usage.mjs

@@ -7,7 +7,7 @@ import { createInterface } from 'node:readline';
 import { pathToFileURL } from 'node:url';
 import { configDir } from './paths.mjs';
 import { agentEnvironment, CODEX_PLAN_ARGS, findBinary, OPENROUTER_AGENTS, readClaudeMaxOrganization } from './worker.mjs';
-import { activeQuotaWalls, readReceipts } from './learner.mjs';
+import { activeQuotaWalls, includedBillingReceipts, readReceipts } from './learner.mjs';
 
 export const INCLUDED_AGENTS = ['claude', 'codex'];
 const VERSION = 1;
@@ -235,7 +235,7 @@ export async function includedAdmission(agent, cwd, policy, { readKey = authKey,
   if (agent === 'claude' && !policy.claudePlan && !claudeProofCurrent(policy)) {
     return { ok: false, failureKind: 'billing-policy', error: 'Verify the native Claude Max login with Usage credits off, or bind a verified included grant.' };
   }
-  const wall = activeQuotaWalls((await receipts()).filter(run => run.billingMode === 'included'))[agent];
+  const wall = activeQuotaWalls(includedBillingReceipts(await receipts()))[agent];
   if (wall) return { ok: false, failureKind: 'quota', error: 'This harness is waiting for included usage.', resetsAt: wall.resetReported ? wall.until : null };
   if (agent === 'codex') return codex(cwd);
   if (policy.claudePlan) return { ok: true, claudePlan: policy.claudePlan.organization };

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/learner.mjs

@@ -60,6 +60,13 @@ export async function recordRunReceipt(receipt = {}) {
   return entry;
 }
 
+/**
+ * Receipts that count under the included usage policy: included runs, plus quota refusals recorded before
+ * refusals carried a billingMode. Those legacy walls expire at their reset, so nothing stale lingers.
+ */
+export const includedBillingReceipts = (entries = []) =>
+  entries.filter(run => run.billingMode === 'included' || (!run.billingMode && run.failureKind === 'quota'));
+
 /** A harness is walled from its last quota failure until the reported reset, or until a later success proves it clear. */
 export function activeQuotaWalls(entries = [], now = Date.now(), unknownResetMs = 60 * 60 * 1000) {
   const latest = new Map();

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/model-selection.mjs

@@ -20,7 +20,11 @@ export function queryAiModels(harness, model, { bin = process.env.TOTAL_RECALL_B
   const line = output.trim().split('\n').filter(Boolean).at(-1);
   try {
     const answer = JSON.parse(line);
-    return answer && typeof answer.ok === 'boolean' ? answer : null;
+    if (!answer || typeof answer.ok !== 'boolean') return null;
+    // An error reply (an older ai-models without `validate` answers invalid_arguments) is the command
+    // failing, not a verdict on the model; reading it as one would refuse every model.
+    if (answer.error != null || answer.code != null) return null;
+    return answer;
   } catch { return null; }
 }
 
@@ -32,7 +36,7 @@ export function createModelValidator({ aiModels = queryAiModels, catalog = getMo
     if (refusal) return { ok: false, harness, model, source: 'policy', reason: refusal };
     if (ownerAnswers) {
       const answer = aiModels(harness, model);
-      if (answer) return { ok: answer.ok, harness, model, source: 'ai-models', ...(answer.ok ? {} : { reason: answer.reason || answer.error || `AI Models does not list ${model} for ${harness}` }) };
+      if (answer) return { ok: answer.ok, harness, model, source: 'ai-models', ...(answer.ok ? {} : { reason: answer.reason || `AI Models does not list ${model} for ${harness}` }) };
       ownerAnswers = false;
     }
     // Another node's catalog is not this one's: its destination validates against its own.

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/pool.mjs

@@ -1,7 +1,7 @@
 /** The harnesses that can actually take work right now, and why the others cannot. */
 import { ADAPTER_CATALOG } from '../capability/index.mjs';
 import { inspectAgents, getActiveAdapters } from './worker.mjs';
-import { readReceipts, activeQuotaWalls, activeCredentialBlocks } from './learner.mjs';
+import { readReceipts, activeQuotaWalls, activeCredentialBlocks, includedBillingReceipts } from './learner.mjs';
 import { measuredWalls } from './telemetry.mjs';
 import { claudeProofCurrent, INCLUDED_AGENTS, readIncludedPolicy } from './included-usage.mjs';
 import os from 'node:os';
@@ -29,7 +29,7 @@ export async function resolvePool({ availableHarnesses, inspect = inspectAgents,
   if (!policy.enabled && Array.isArray(availableHarnesses) && availableHarnesses.length) return { ready: availableHarnesses.map(id => describe(id)), excluded: [], walls: {} };
   const claudePlan = policy.enabled ? policy.claudePlan?.organization : undefined;
   const [{ agents = [] }, entries] = await Promise.all([inspect({ env: process.env, claudePlan }), receipts()]);
-  const billingEntries = policy.enabled ? entries.filter(run => run.billingMode === 'included') : entries;
+  const billingEntries = policy.enabled ? includedBillingReceipts(entries) : entries;
   const walls = { ...activeQuotaWalls(billingEntries), ...(!policy.enabled ? measuredWalls() : {}) };
   const blocks = activeCredentialBlocks(billingEntries);
   const ready = [], excluded = [];

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/router.mjs

@@ -18,10 +18,10 @@ import { classifyTaskComplexity, selectOptimalHarness, computeEmpiricalScorecard
 import { inspectAgents } from './worker.mjs';
 import { inspectNode } from './executor.mjs';
 import { getModelCatalog, joinHarnessModels } from './model-catalog.mjs';
-import { readReceipts, activeQuotaWalls, activeCredentialBlocks } from './learner.mjs';
+import { readReceipts, activeQuotaWalls, activeCredentialBlocks, includedBillingReceipts, recordRunReceipt } from './learner.mjs';
 import { resolvePool, exclusionReason, isLocalExecutionNode } from './pool.mjs';
 import { readCodexRateLimits, measuredWalls } from './telemetry.mjs';
-import { claudeProofCurrent, INCLUDED_AGENTS, readIncludedPolicy } from './included-usage.mjs';
+import { claudeProofCurrent, INCLUDED_AGENTS, readIncludedPolicy, readCodexAllowance } from './included-usage.mjs';
 import { derivedDir } from './paths.mjs';
 import { createModelValidator, filterPoolByModel } from './model-selection.mjs';
 
@@ -169,7 +169,7 @@ export async function inspectQuotas(options = {}) {
   const inspected = remote ? await (options.inspectNodeFn || inspectNode)(options.node) :
     await (options.inspect || inspectAgents)({ env: process.env, cwd: options.cwd, claudePlan });
   const codexLimits = remote ? null : readCodexRateLimits();
-  const receipts = remote ? [] : (await readReceipts()).filter(run => !policy.enabled || run.billingMode === 'included');
+  const receipts = remote ? [] : (policy.enabled ? includedBillingReceipts : runs => runs)(await (options.receipts || readReceipts)());
   const walls = remote ? {} : { ...activeQuotaWalls(receipts), ...(!policy.enabled ? measuredWalls(codexLimits) : {}) };
   const metered = METERED_HARNESSES;
 
@@ -286,7 +286,26 @@ export async function routeTask(taskDescription, options = {}) {
     ...(remote || lean.fleet ? {} : { fleet: complexity.tier === 'local' ? cachedFleet : () => ({ ok: false, error: 'Not read: this route places no local work', nodes: [] }) }),
   });
   const quotas = quotaReport.quotas;
-  const routing = selectOptimalHarness(taskDescription, pool.ready.map(h => h.id), quotas, { ...options, tierOverride: complexity.tier, empiricalScorecard: computeEmpiricalScorecard(receipts) });
+  const rank = ready => selectOptimalHarness(taskDescription, ready.map(h => h.id), quotas, { ...options, tierOverride: complexity.tier, empiricalScorecard: computeEmpiricalScorecard(receipts) });
+  let excluded = pool.excluded;
+  let routing = rank(pool.ready);
+  // Quota walls come from launches this machine saw refused. With none recorded here, a route kept
+  // choosing a Codex that was out of quota, and the selected-harness write gate then blocked every
+  // other harness. Before choosing Codex, ask it for its allowance (no turn), and record a quota
+  // answer as the wall a refused launch records (A-124), so later routes skip it without asking.
+  if (policy.enabled && !remote && routing.selected === 'codex') {
+    const allowance = await (options.codexAllowance || readCodexAllowance)(options.cwd || process.cwd());
+    if (allowance?.ok === false && allowance.failureKind === 'quota') {
+      const resetsAt = allowance.resetsAt || null;
+      try {
+        await (options.recordReceipt || recordRunReceipt)({ harness: 'codex', role: 'Route', task: String(taskDescription).slice(0, 200),
+          success: false, failureKind: 'quota', billingMode: 'included', error: allowance.error, resetsAt });
+      } catch { /* the route still skips Codex; only the next route asks again */ }
+      excluded = [...excluded, { harness: 'codex', reason: resetsAt ? `out of quota until ${resetsAt}` : 'out of quota', failureKind: 'quota', resetsAt }];
+      quotas.codex = { ...quotas.codex, status: 'exhausted', wallMessage: allowance.error, ...(resetsAt ? { resetsAt } : {}) };
+      routing = rank(pool.ready.filter(h => h.id !== 'codex'));
+    }
+  }
   const selectedQuota = quotas[routing.selected] || {};
   const warnings = [];
   if (policy.enabled && options.jev) warnings.push('Included usage policy uses the local task classifier.');
@@ -298,8 +317,8 @@ export async function routeTask(taskDescription, options = {}) {
   if (selectedModel?.source === 'unverified') warnings.push(selectedModel.note);
   return {
     ok: Boolean(routing.selected), task: taskDescription, classifier, complexity,
-    selected: routing.selected, tier: complexity.tier, model: options.model ?? null, ...(modelSelection ? { modelSelection } : {}), candidates: routing.candidates, excluded: pool.excluded,
-    ...(policy.enabled && !routing.selected ? { deferred: pool.excluded.find(row => row.failureKind === 'quota') || null } : {}),
+    selected: routing.selected, tier: complexity.tier, model: options.model ?? null, ...(modelSelection ? { modelSelection } : {}), candidates: routing.candidates, excluded,
+    ...(policy.enabled && !routing.selected ? { deferred: excluded.find(row => row.failureKind === 'quota') || null } : {}),
     placement: complexity.tier === 'local' ? placeLocalWork(quotaReport.fleet) : null,
     scoring: 'Adapter quality and cost scores are configured priors, adjusted by pass rates measured on this machine.',
     quotaSnapshot: { selectedHarnessStatus: selectedQuota.status || null, selectedHarnessUsage: selectedQuota.usagePercent ?? null, freeMemGB: quotas.system.freeMemGB ?? null },

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/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 } : {}) };
+}