total-recall-brain 3.20.0 → 3.21.0

package/bin/total-recall.mjs

@@ -60,6 +60,8 @@ const COMMANDS = {
   recall:   'recall.mjs',
   search:   'recall.mjs',
   research: 'research.mjs',
+  proposals: 'proposals.mjs',
+  proposal:  'proposals.mjs',
   task:     'task.mjs',
   share:    'share.mjs',
   'generate-pat': 'generate-pat.mjs',
@@ -102,6 +104,7 @@ function printHelp() {
     recall              Read-path hybrid search
     compile             Rebuild instruction surfaces
     dream               Memory consolidation cycle
+    proposals <cmd>     Review / apply optimizer proposals (list|apply|revert)
     task <cmd>          Enqueue daemon work (open envelope)
     daemon <cmd>        Background worker (start|stop|status)
     skill <cmd>         Skills registry, deploy, multi-repo sync

package/frontend/src/api/system.ts

@@ -16,6 +16,37 @@ export async function fetchUsageStats(): Promise<UsageData> {
   return res.json()
 }
 
+/** One provider's reported spend, or the reason we could not read it. */
+export interface ProviderUsageEntry {
+  label: string
+  /** `ok` carries numbers; every other state carries a `reason` instead. */
+  state: 'ok' | 'no_key' | 'needs_admin_key' | 'unsupported' | 'error'
+  reason?: string
+  secret_name?: string
+  total_cost?: number
+  currency?: string
+  balance?: number
+  /** True when the figure is lifetime-to-date rather than the requested window. */
+  lifetime?: boolean
+}
+
+export interface ProviderUsage {
+  fetched_at: string
+  window_days: number
+  from_cache?: boolean
+  providers: Record<string, ProviderUsageEntry>
+}
+
+/**
+ * Spend as the providers report it, rather than estimated from local token counts.
+ * Served from an hourly cache unless `refresh` is set.
+ */
+export async function fetchProviderUsage(refresh = false): Promise<ProviderUsage> {
+  const res = await apiFetch(`${API_BASE}/api/usage/providers${refresh ? '?refresh=1' : ''}`)
+  if (!res.ok) throw new Error(`Provider usage API error: ${res.status}`)
+  return res.json()
+}
+
 export async function fetchLogs(type: 'server' | 'daemon'): Promise<{ content: string }> {
   const res = await apiFetch(`${API_BASE}/api/logs/${type}`)
   if (!res.ok) throw new Error(`Logs API error: ${res.status}`)

package/frontend/src/pages/UsagePage.tsx

@@ -1,5 +1,6 @@
 import { useState, useEffect, useMemo } from 'react';
-import { fetchUsageStats, fetchConfigJson } from '../api';
+import { fetchUsageStats, fetchConfigJson, fetchProviderUsage } from '../api';
+import type { ProviderUsage } from '../api';
 import type { ConfigJson, UsageData } from '../types';
 import { AreaChart, Area, XAxis, YAxis, CartesianGrid, Tooltip, ResponsiveContainer, Legend } from 'recharts';
 
@@ -8,6 +9,9 @@ export default function UsagePage() {
   const [config, setConfig] = useState<ConfigJson | null>(null);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
+  const [providerUsage, setProviderUsage] = useState<ProviderUsage | null>(null);
+  const [providerLoading, setProviderLoading] = useState(false);
+  const [providerError, setProviderError] = useState<string | null>(null);
 
   const fetchUsageAndConfig = async () => {
     try {
@@ -24,6 +28,18 @@ export default function UsagePage() {
     }
   };
 
+  const loadProviderUsage = async (refresh = false) => {
+    setProviderLoading(true);
+    try {
+      setProviderUsage(await fetchProviderUsage(refresh));
+      setProviderError(null);
+    } catch (err: unknown) {
+      setProviderError((err as Error).message || 'Failed to read provider billing data.');
+    } finally {
+      setProviderLoading(false);
+    }
+  };
+
   useEffect(() => {
     // eslint-disable-next-line react-hooks/set-state-in-effect -- legitimate statistics sync on mount
     void fetchUsageAndConfig();
@@ -31,6 +47,13 @@ export default function UsagePage() {
     return () => clearInterval(interval);
   }, []);
 
+  useEffect(() => {
+    // Deliberately not on the 5s ledger interval — this hits live provider
+    // billing APIs. The server caches hourly; refreshing is a manual action.
+    // eslint-disable-next-line react-hooks/set-state-in-effect -- initial fetch on mount
+    void loadProviderUsage();
+  }, []);
+
 
 
   const dailyCap = config?.budget?.budget?.daily_cap_usd ?? 5.0;
@@ -611,6 +634,69 @@ export default function UsagePage() {
         </div>
       </div>
 
+      {/* ── Provider-Reported Spend ──
+          Everything above is estimated locally: observed tokens × a hardcoded
+          price table. This panel is what the providers themselves bill. */}
+      <div className="card" style={{ padding: 24, marginTop: 24, background: 'rgba(18, 18, 26, 0.6)', backdropFilter: 'blur(8px)', border: '1px solid var(--border)' }}>
+        <div style={{ display: 'flex', alignItems: 'baseline', justifyContent: 'space-between', borderBottom: '1px solid var(--border)', paddingBottom: 10, marginBottom: 16 }}>
+          <h3 style={{ fontSize: 14, fontWeight: 700, color: 'var(--text-tertiary)', textTransform: 'uppercase', letterSpacing: 0.5, margin: 0 }}>
+            Reported by Provider
+          </h3>
+          <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
+            {providerUsage?.fetched_at && (
+              <span style={{ fontSize: 11, color: 'var(--text-tertiary)' }}>
+                {new Date(providerUsage.fetched_at).toLocaleString()}
+                {providerUsage.from_cache ? ' (cached)' : ''}
+              </span>
+            )}
+            <button
+              type="button"
+              onClick={() => { void loadProviderUsage(true); }}
+              disabled={providerLoading}
+              style={{ fontSize: 11, padding: '4px 10px', borderRadius: 6, border: '1px solid var(--border)', background: 'transparent', color: 'var(--text-secondary)', cursor: providerLoading ? 'wait' : 'pointer' }}
+            >
+              {providerLoading ? 'Refreshing…' : 'Refresh'}
+            </button>
+          </div>
+        </div>
+
+        {providerError && (
+          <div style={{ fontSize: 12, color: 'var(--error)', marginBottom: 12 }}>{providerError}</div>
+        )}
+
+        <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(260px, 1fr))', gap: 16 }}>
+          {Object.entries(providerUsage?.providers || {}).map(([id, p]) => (
+            <div key={id} style={{
+              border: '1px solid var(--border)',
+              borderLeft: `3px solid ${p.state === 'ok' ? 'var(--success)' : p.state === 'error' ? 'var(--error)' : 'var(--warning)'}`,
+              borderRadius: 8,
+              padding: 16,
+            }}>
+              <div style={{ fontSize: 13, fontWeight: 700, color: '#fff', marginBottom: 8 }}>{p.label}</div>
+              {p.state === 'ok' ? (
+                <>
+                  <div style={{ fontSize: 22, fontWeight: 700, color: '#fff' }}>
+                    ${(p.total_cost ?? 0).toFixed(2)}
+                  </div>
+                  <div style={{ fontSize: 11, color: 'var(--text-tertiary)', marginTop: 4 }}>
+                    {/* Never label a lifetime figure as a windowed one. */}
+                    {p.lifetime ? 'lifetime to date' : `last ${providerUsage?.window_days ?? 30} days`}
+                    {typeof p.balance === 'number' ? ` · $${p.balance.toFixed(2)} remaining` : ''}
+                  </div>
+                </>
+              ) : (
+                <div style={{ fontSize: 11, color: 'var(--text-secondary)', lineHeight: 1.5 }}>
+                  {p.reason}
+                </div>
+              )}
+            </div>
+          ))}
+          {!providerUsage && !providerError && (
+            <div style={{ fontSize: 12, color: 'var(--text-tertiary)' }}>Loading provider billing data…</div>
+          )}
+        </div>
+      </div>
+
     </div>
   );
 }

package/package.json

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

package/src/cli/proposals.mjs

@@ -0,0 +1,216 @@
+import path from 'node:path';
+import { resolveBrainDir, parseLayerFlag } from './agent-dir.mjs';
+import {
+  listProposals,
+  getProposal,
+  applyProposal,
+  setProposalStatus,
+  revertProposal,
+  hasHandler,
+  AUTO_APPLICABLE_TOPICS,
+} from '../core/proposal-applier.mjs';
+import { findStaleNodes } from '../core/optimizer.mjs';
+
+function printHelp() {
+  console.log(`
+  total-recall proposals — Review and apply optimizer proposals
+
+  Usage: total-recall proposals <subcommand> [options]
+
+  Subcommands:
+    list                   Show open proposals (default)
+    show <id>              Full detail for one proposal
+    apply <id>             Perform the proposed work
+    reject <id> [reason]   Refuse a proposal permanently
+    revert <id>            Undo an applied proposal from its snapshot
+    supersede --topic <t>  Bulk-close every open proposal of a retired topic
+    stale                  Nodes due for re-verification (read-only query)
+
+  Options:
+    --status <s>   Filter: draft | accepted | applied | rejected | superseded | all
+    --topic <t>    Filter by proposal topic
+    --dry-run      With apply: show the change without writing
+    --global       Use the global brain
+    --project      Use the project brain
+    --help, -h     Show this help
+
+${AUTO_APPLICABLE_TOPICS.size > 0
+    ? `  Applied automatically during the dream cycle: ${[...AUTO_APPLICABLE_TOPICS].join(', ')}.
+  Everything else waits here for review.`
+    : `  Nothing is applied automatically in this release — every proposal waits for
+  you to run \`apply\`. Applying is non-destructive (duplicates are superseded,
+  never deleted) and \`revert\` restores the exact prior bytes.`}
+
+  Examples:
+    npx total-recall proposals
+    npx total-recall proposals show prop_a1b2c3d4e5f6
+    npx total-recall proposals apply prop_a1b2c3d4e5f6 --dry-run
+    npx total-recall proposals reject prop_a1b2c3d4e5f6 "targets are not duplicates"
+    npx total-recall proposals revert prop_a1b2c3d4e5f6
+`);
+}
+
+const STATUS_ICON = {
+  draft: '○',
+  accepted: '◆',
+  applied: '✓',
+  rejected: '✗',
+  superseded: '~',
+};
+
+function flagValue(args, name) {
+  const i = args.indexOf(name);
+  return i !== -1 ? args[i + 1] : null;
+}
+
+export default async function proposals(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    return;
+  }
+
+  const { layer, remainingArgs } = parseLayerFlag(args);
+  const brainDir = resolveBrainDir(layer);
+  const vaultDir = path.join(brainDir, 'memory-vault');
+
+  const sub = remainingArgs[0] && !remainingArgs[0].startsWith('--') ? remainingArgs[0] : 'list';
+  const id = remainingArgs[1] && !remainingArgs[1].startsWith('--') ? remainingArgs[1] : null;
+
+  switch (sub) {
+    case 'list': {
+      const statusFlag = flagValue(remainingArgs, '--status');
+      // Default view is the actionable queue. Terminal proposals are history, not
+      // work — `--status all` shows them when you actually want them.
+      const status = statusFlag === 'all' ? undefined : (statusFlag || ['draft', 'accepted']);
+      const items = listProposals(vaultDir, {
+        status,
+        topic: flagValue(remainingArgs, '--topic') || undefined,
+      });
+
+      if (items.length === 0) {
+        console.log('\n  No proposals match.\n');
+        return;
+      }
+
+      console.log(`\n  ${items.length} proposal(s)\n`);
+      for (const p of items) {
+        const auto = AUTO_APPLICABLE_TOPICS.has(p.topic) && hasHandler(p.topic) ? ' [auto]' : '';
+        console.log(`  ${STATUS_ICON[p.status] || '?'} ${p.proposal_id}  ${p.topic}${auto}`);
+        console.log(`     ${p.summary || p.title}`);
+        if (p.review_reason) console.log(`     ↳ ${p.review_reason}`);
+        if (p.rejection_reason) console.log(`     ↳ ${p.rejection_reason}`);
+      }
+      console.log('\n  Apply one:  npx total-recall proposals apply <id>\n');
+      return;
+    }
+
+    case 'show': {
+      if (!id) { console.error('  ❌ Usage: proposals show <id>'); process.exitCode = 1; return; }
+      const p = getProposal(vaultDir, id);
+      if (!p) { console.error(`  ❌ Proposal not found: ${id}`); process.exitCode = 1; return; }
+      console.log(`\n  ${p.proposal_id}  [${p.status}]  ${p.topic}\n`);
+      console.log(`  Summary:   ${p.summary || p.title}`);
+      console.log(`  Target:    ${p.target_path || '(none)'}`);
+      console.log(`  Proposed:  ${p.proposed_at} by ${p.proposed_by}`);
+      if (p.reviewed_at) console.log(`  Reviewed:  ${p.reviewed_at} by ${p.reviewed_by}`);
+      if (p.applied_at) console.log(`  Applied:   ${p.applied_at} by ${p.applied_by}`);
+      if (p.review_reason) console.log(`  Note:      ${p.review_reason}`);
+      if (p.rejection_reason) console.log(`  Rejected:  ${p.rejection_reason}`);
+      console.log(`\n  ${p.rationale || p.description || ''}\n`);
+      return;
+    }
+
+    case 'apply': {
+      if (!id) { console.error('  ❌ Usage: proposals apply <id>'); process.exitCode = 1; return; }
+      const dryRun = remainingArgs.includes('--dry-run');
+      const result = await applyProposal(vaultDir, id, { dryRun, actor: 'cli' });
+      if (!result.ok) {
+        console.error(`  ❌ Not applied: ${result.reason}`);
+        process.exitCode = 1;
+        return;
+      }
+      if (dryRun) {
+        console.log(`\n  Dry run — would keep ${result.canonical}, supersede ${result.merged.join(', ')}\n`);
+        return;
+      }
+      console.log(`\n  ✓ Applied ${id}`);
+      console.log(`    Kept:     ${result.canonical}`);
+      console.log(`    Merged:   ${result.merged.join(', ')}`);
+      console.log(`\n  Undo:  npx total-recall proposals revert ${id}\n`);
+      return;
+    }
+
+    case 'reject': {
+      if (!id) { console.error('  ❌ Usage: proposals reject <id> [reason]'); process.exitCode = 1; return; }
+      const reason = remainingArgs.slice(2).filter(a => !a.startsWith('--')).join(' ') || 'Rejected by user.';
+      setProposalStatus(vaultDir, id, 'rejected', { rejection_reason: reason, reviewed_by: 'user' });
+      console.log(`\n  ✗ Rejected ${id}: ${reason}\n`);
+      return;
+    }
+
+    case 'supersede': {
+      // Bulk-resolve a whole topic. Needed when a generator is retired: its
+      // already-filed tickets are neither wrong nor refused, they just describe
+      // work that now flows somewhere else. Without this they sit in `list`
+      // forever, and the terminal-only pruner correctly refuses to touch them.
+      const topic = flagValue(remainingArgs, '--topic');
+      if (!topic) {
+        console.error('  ❌ Usage: proposals supersede --topic <topic> [--reason "..."]');
+        process.exitCode = 1;
+        return;
+      }
+      const reason = flagValue(remainingArgs, '--reason') || `Topic "${topic}" is no longer generated.`;
+      const open = listProposals(vaultDir, { status: ['draft', 'accepted'], topic });
+      if (open.length === 0) {
+        console.log(`\n  No open proposals under topic "${topic}".\n`);
+        return;
+      }
+      if (!remainingArgs.includes('--yes')) {
+        console.log(`\n  Would supersede ${open.length} open "${topic}" proposal(s).`);
+        console.log(`  Reason: ${reason}`);
+        console.log('\n  Re-run with --yes to apply.\n');
+        return;
+      }
+      for (const p of open) {
+        setProposalStatus(vaultDir, p.proposal_id, 'superseded', { superseded_reason: reason });
+      }
+      console.log(`\n  ~ Superseded ${open.length} "${topic}" proposal(s).\n`);
+      return;
+    }
+
+    case 'revert': {
+      if (!id) { console.error('  ❌ Usage: proposals revert <id>'); process.exitCode = 1; return; }
+      try {
+        const { reverted, deleted } = revertProposal(vaultDir, id);
+        console.log(`\n  ✓ Reverted ${id} — ${reverted} file(s) restored, ${deleted} removed.\n`);
+      } catch (err) {
+        console.error(`  ❌ ${err.message}`);
+        process.exitCode = 1;
+      }
+      return;
+    }
+
+    case 'stale': {
+      // Answers the question the old stale-knowledge-refresh generator used to
+      // answer by writing one file per node, every cycle, forever.
+      const stale = findStaleNodes(vaultDir);
+      if (stale.length === 0) {
+        console.log('\n  No stale high-importance nodes.\n');
+        return;
+      }
+      console.log(`\n  ${stale.length} node(s) due for re-verification\n`);
+      for (const n of stale.slice(0, 40)) {
+        const days = Math.floor((Date.now() - new Date(n.last_accessed).getTime()) / 86400000);
+        console.log(`  ${String(days).padStart(4)}d  [i${n.importance}]  ${n.slug}`);
+      }
+      if (stale.length > 40) console.log(`\n  … and ${stale.length - 40} more.`);
+      console.log('\n  The dream cycle queues these for research automatically.\n');
+      return;
+    }
+
+    default:
+      console.error(`  ❌ Unknown subcommand: ${sub}`);
+      printHelp();
+      process.exitCode = 1;
+  }
+}

package/src/cli/rebuild.mjs

@@ -53,9 +53,22 @@ export async function runRebuild(options = {}) {
   }
 
   // Perform full rebuild
+  // Discard the cheap, fully-derivable indexes — but NOT embeddings.db.
+  //
+  // `fs.rmSync(derivedDir)` used to take the whole directory, which threw away
+  // every vector. Embeddings are not free to re-derive: each one is a provider
+  // call. Worse, the rebuild that followed was fire-and-forget, so the process
+  // exited before replacing them and the index stayed empty — that is how this
+  // brain ended up with 520 nodes and 0 embeddings while reporting success.
+  //
+  // The index is content-hash incremental and prunes slugs no longer in the
+  // vault, so keeping it across a rebuild is correct as well as cheap.
   console.log('🗑️  Discarding existing derived indexes...');
   if (fs.existsSync(derivedDir)) {
-    fs.rmSync(derivedDir, { recursive: true, force: true });
+    for (const entry of fs.readdirSync(derivedDir)) {
+      if (entry.startsWith('embeddings.db')) continue; // also skips -wal / -shm
+      fs.rmSync(path.join(derivedDir, entry), { recursive: true, force: true });
+    }
   }
 
   console.log('🏗️  Recompiling surface from canonical vault...');
@@ -64,7 +77,19 @@ export async function runRebuild(options = {}) {
     console.log(`✅ Processed ${stats.nodesProcessed} canonical memory nodes.`);
     console.log(`✅ Injected memory into ${stats.skillsInjected} skill files.`);
     console.log(`✅ Rebuilt graph-index.jsonl, memory-layers.jsonl, and skill-routes.jsonl.`);
-    
+
+    // Report vector coverage explicitly. "Post-build verification passed: 0 drift"
+    // checks the jsonl indexes only — it passed happily on a brain with 520 nodes
+    // and 0 embeddings, i.e. keyword-only recall that returns plausible-looking
+    // results from the wrong places.
+    if (stats.semanticUnavailable) {
+      console.log(`⚠️  Vector search is OFF — embeddings unavailable${stats.semanticError ? `: ${stats.semanticError}` : ''}.`);
+      console.log(`   Recall will fall back to keyword matching.`);
+    } else {
+      console.log(`✅ Embeddings: ${stats.semanticIndexed} built, ${stats.semanticSkipped} unchanged${stats.semanticFailed ? `, ${stats.semanticFailed} FAILED` : ''}.`);
+    }
+
+
     // Verify
     const drift = detectIndexDrift(vaultDir, derivedDir);
     if (!drift.drifted) {

package/src/cli/recall.mjs

@@ -129,6 +129,7 @@ export default async function recall(args) {
     let allResults = [];
     let isDegraded = false;
     const searchErrors = [];
+    const degradedReasons = new Map();
 
     for (const target of searchTargets) {
       const vaultDir = path.join(target.brainDir, 'memory-vault');
@@ -163,7 +164,13 @@ export default async function recall(args) {
             priority
           });
         }
-        if (results.degradedTextSearch) isDegraded = true;
+        if (results.degradedTextSearch) {
+          isDegraded = true;
+          degradedReasons.set(results.degradedReason || 'unknown', {
+            label: target.label,
+            detail: results.degradedDetail || '',
+          });
+        }
         // Tag each result with its layer
         for (const r of results) {
           r._layer = target.label;
@@ -215,11 +222,35 @@ export default async function recall(args) {
       return;
     }
     if (isDegraded) {
-      console.log('\n  ⚠️  WARNING: Embedding API unreachable or unconfigured. Cos-similarity vector search is disabled.');
-      console.log('              Running basic text keyword search instead. Configure GOOGLE_API_KEY or OPENAI_API_KEY.');
+      // This block used to print ONE message for two unrelated failures:
+      // "Embedding API unreachable or unconfigured … Configure GOOGLE_API_KEY
+      // or OPENAI_API_KEY". When the real cause was an unbuilt index, that
+      // sent the reader to check credentials that were already working, while
+      // a brain with thousands of nodes quietly answered from keyword matching
+      // and returned results from the wrong project. Name the actual cause.
+      const empty = degradedReasons.get('empty_index');
+      const failed = degradedReasons.get('embedding_failed');
+
+      console.log('\n  ⚠️  Vector search is OFF — these results are keyword-only and may miss obvious matches.');
+      if (empty) {
+        console.log(`      Cause: the ${empty.label} brain has NO embeddings indexed. The API is fine; the index was never built.`);
+        console.log('      Fix:   npx total-recall compile        (embeds any unembedded nodes for this brain)');
+      }
+      if (failed) {
+        console.log(`      Cause: embedding generation failed for the ${failed.label} brain — ${failed.detail}`);
+        console.log('      Fix:   set OPENROUTER_API_KEY (preferred), or GOOGLE_API_KEY / OPENAI_API_KEY.');
+      }
+      if (!empty && !failed) {
+        console.log('      Cause: unknown — embeddings unavailable and no reason was reported.');
+      }
     }
     const layerSuffix = searchTargets.length > 1 ? ' (merged)' : ` (${searchTargets[0].label})`;
-    console.log(`\n  🔍 Semantic search results for "${query}"${layerSuffix}:\n`);
+    // Never call it "Semantic search results" when semantic search did not run.
+    // The old header said exactly that regardless, so degraded keyword output
+    // was indistinguishable from real vector results — same header, same
+    // percentage scores. If the label doesn't change, nobody can tell.
+    const modeLabel = isDegraded ? '🔤 KEYWORD-ONLY results' : '🔍 Semantic search results';
+    console.log(`\n  ${modeLabel} for "${query}"${layerSuffix}:\n`);
     for (let i = 0; i < allResults.length; i++) {
       const match = allResults[i];
       const rank = i + 1;

package/src/core/config.mjs

@@ -285,7 +285,13 @@ export function detectProjectBrain(startDir = process.cwd()) {
     if (fs.existsSync(path.join(candidate, 'SKILL.md'))) {
       return {
         agentDir: path.join(dir, '.agent'),
-        brainDir: globalBrainDir,
+        // The project brain lives at the detected candidate — NEVER alias it to
+        // globalBrainDir. This returned `globalBrainDir` while the sibling
+        // implementation in src/cli/agent-dir.mjs returned `candidate`, so the
+        // two disagreed about where the project brain is: anything routed
+        // through this function silently operated on the GLOBAL vault while
+        // reporting itself as the 'project' layer.
+        brainDir: candidate,
         projectRoot: dir,
       };
     }

package/src/core/daemon-loop.mjs

@@ -16,6 +16,7 @@ import fs from 'fs';
 import { createScheduler, updateTaskStatus, persistTaskToDisk } from './scheduler.mjs';
 import { scanAndIngest } from './session-watcher.mjs';
 import { syncAllRepos } from './repo-sync.mjs';
+import { refreshProviderUsage } from './usage-fetcher.mjs';
 import { logger } from './logger.mjs';
 import { updateQueueItem } from './research-queue.mjs';
 import { agentDir, brainDir } from './config.mjs';
@@ -365,6 +366,18 @@ async function main() {
         } catch (err) {
           logger.info({ subsystem: 'daemon-loop', message: `Periodic repo-sync failed: ${err.message}` });
         }
+
+        // Provider usage/billing refresh. Self-throttles to once an hour
+        // internally, so calling it every cycle is safe.
+        try {
+          const usage = await refreshProviderUsage(BRAIN_DIR);
+          if (!usage.from_cache) {
+            const ok = Object.values(usage.providers).filter(p => p.state === 'ok').length;
+            logger.info({ subsystem: 'daemon-loop', message: `Provider usage refreshed (${ok} provider(s) reporting)` });
+          }
+        } catch (err) {
+          logger.info({ subsystem: 'daemon-loop', message: `Provider usage refresh failed: ${err.message}` });
+        }
       }
 
       const scheduler = createScheduler({