total-recall-brain 3.21.3 → 3.22.0

package/frontend/dist/index.html

@@ -17,7 +17,7 @@
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
     <title>Total Recall — Portable Memory</title>
-    <script type="module" crossorigin src="/assets/index-BwUTxKNm.js"></script>
+    <script type="module" crossorigin src="/assets/index-DJjuZ3t3.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-C7_Xpk27.css">
   </head>
   <body>

package/frontend/src/api/embeddings.ts

@@ -0,0 +1,46 @@
+import { get, post } from './_base'
+
+/** One model on the Ollama host, annotated with why it can or cannot be used. */
+export interface EmbeddingCandidate {
+  name: string
+  size: number | null
+  family: string | null
+  capabilities: string[]
+  /** Whether the model declares the embedding capability at all. */
+  embedding: boolean
+  /** Vector width the model produces, or null when it is not an embedding model. */
+  dims: number | null
+  /** True only when it embeds AND its width matches the vault index. */
+  compatible: boolean
+}
+
+export interface LocalEmbeddingProvider {
+  available: boolean
+  endpoint: string | null
+  selected: string | null
+  preferred: string | null
+  dims: number
+  candidates: EmbeddingCandidate[]
+  reason: string | null
+}
+
+export interface EmbeddingProviderStatus {
+  dims: number
+  local: LocalEmbeddingProvider
+  fallbacks: { provider: string; configured: boolean }[]
+}
+
+export async function fetchEmbeddingProvider(): Promise<EmbeddingProviderStatus> {
+  return get<EmbeddingProviderStatus>('/api/embeddings/provider')
+}
+
+/** Pin a model, or pass null to return to automatic selection. */
+export async function setEmbeddingModel(
+  model: string | null,
+): Promise<{ ok: boolean; pinned: string | null; selected: string | null }> {
+  return post('/api/embeddings/model', { model })
+}
+
+export async function rediscoverEmbeddingProvider(): Promise<{ ok: boolean; local: LocalEmbeddingProvider }> {
+  return post('/api/embeddings/rediscover', {})
+}

package/frontend/src/components/EmbeddingProviderPanel.spec.tsx

@@ -0,0 +1,127 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+
+import { EmbeddingProviderPanel } from './EmbeddingProviderPanel'
+import * as api from '../api/embeddings'
+import type { EmbeddingProviderStatus } from '../api/embeddings'
+
+vi.mock('../api/embeddings')
+
+// Annotated against the real contract: without it TS narrows `endpoint` to
+// string and `reason` to null from the literal, so the "nothing reachable"
+// case below cannot be expressed.
+const LOCAL_OK: EmbeddingProviderStatus = {
+  dims: 768,
+  local: {
+    available: true,
+    endpoint: 'http://100.64.0.2:11434',
+    selected: 'nomic-embed-text:latest',
+    preferred: null,
+    dims: 768,
+    candidates: [
+      {
+        name: 'nomic-embed-text:latest',
+        size: 274_000_000,
+        family: 'nomic-bert',
+        capabilities: ['embedding'],
+        embedding: true,
+        dims: 768,
+        compatible: true,
+      },
+      {
+        name: 'gemma4:latest',
+        size: 9_608_000_000,
+        family: 'gemma4',
+        capabilities: ['completion'],
+        embedding: false,
+        dims: 2560,
+        compatible: false,
+      },
+    ],
+    reason: null,
+  },
+  fallbacks: [
+    { provider: 'openrouter', configured: true },
+    { provider: 'google', configured: false },
+    { provider: 'openai', configured: false },
+  ],
+}
+
+beforeEach(() => {
+  vi.mocked(api.fetchEmbeddingProvider).mockResolvedValue(structuredClone(LOCAL_OK))
+  vi.mocked(api.setEmbeddingModel).mockResolvedValue({ ok: true, pinned: null, selected: null })
+  vi.mocked(api.rediscoverEmbeddingProvider).mockResolvedValue({ ok: true, local: LOCAL_OK.local })
+})
+
+describe('EmbeddingProviderPanel', () => {
+  it('shows the resolved endpoint and selected model', async () => {
+    render(<EmbeddingProviderPanel />)
+    expect(await screen.findByTestId('embed-endpoint')).toHaveTextContent('http://100.64.0.2:11434')
+    expect(screen.getByTestId('embed-selected')).toHaveTextContent('nomic-embed-text:latest')
+    expect(screen.getByTestId('embed-selected')).toHaveTextContent('auto')
+  })
+
+  it('lists incompatible models with the reason instead of hiding them', async () => {
+    render(<EmbeddingProviderPanel />)
+    // An operator who pulled a chat model needs to see why it is unusable.
+    expect(await screen.findByText('gemma4:latest')).toBeInTheDocument()
+    expect(screen.getByText(/cannot embed/i)).toBeInTheDocument()
+  })
+
+  it('offers no "Use" button for a model that cannot embed', async () => {
+    render(<EmbeddingProviderPanel />)
+    await screen.findByText('gemma4:latest')
+    // Only compatible, non-selected models are pinnable; here that set is empty.
+    expect(screen.queryByRole('button', { name: /^use$/i })).not.toBeInTheDocument()
+  })
+
+  it('pins a model when the operator picks one', async () => {
+    const withOther = structuredClone(LOCAL_OK)
+    withOther.local.candidates.push({
+      name: 'other-embed:latest',
+      size: 100_000_000,
+      family: 'other',
+      capabilities: ['embedding'],
+      embedding: true,
+      dims: 768,
+      compatible: true,
+    })
+    vi.mocked(api.fetchEmbeddingProvider).mockResolvedValue(withOther)
+
+    render(<EmbeddingProviderPanel />)
+    const useBtn = await screen.findByRole('button', { name: /^use$/i })
+    await userEvent.click(useBtn)
+
+    await waitFor(() => expect(api.setEmbeddingModel).toHaveBeenCalledWith('other-embed:latest'))
+  })
+
+  it('reports the hosted fallback state when nothing local answers', async () => {
+    const down = structuredClone(LOCAL_OK)
+    down.local = {
+      ...down.local,
+      available: false,
+      endpoint: null,
+      selected: null,
+      candidates: [],
+      reason: 'No Ollama endpoint answered on this host or any online mesh peer.',
+    }
+    vi.mocked(api.fetchEmbeddingProvider).mockResolvedValue(down)
+
+    render(<EmbeddingProviderPanel />)
+    expect(await screen.findByTestId('embed-availability')).toHaveTextContent('hosted fallback')
+    expect(screen.getByRole('status')).toHaveTextContent(/No Ollama endpoint answered/)
+  })
+
+  it('surfaces a load failure rather than rendering an empty panel', async () => {
+    vi.mocked(api.fetchEmbeddingProvider).mockRejectedValue(new Error('Authentication required'))
+    render(<EmbeddingProviderPanel />)
+    expect(await screen.findByRole('alert')).toHaveTextContent('Authentication required')
+  })
+
+  it('re-discovers on demand', async () => {
+    render(<EmbeddingProviderPanel />)
+    await userEvent.click(await screen.findByRole('button', { name: /re-discover/i }))
+    await waitFor(() => expect(api.rediscoverEmbeddingProvider).toHaveBeenCalled())
+  })
+})

package/frontend/src/components/EmbeddingProviderPanel.tsx

@@ -0,0 +1,177 @@
+import { useCallback, useEffect, useState } from 'react'
+
+import {
+  fetchEmbeddingProvider,
+  setEmbeddingModel,
+  rediscoverEmbeddingProvider,
+  type EmbeddingProviderStatus,
+  type EmbeddingCandidate,
+} from '../api/embeddings'
+
+function formatSize(bytes: number | null): string {
+  if (!bytes) return '—'
+  if (bytes >= 1e9) return `${(bytes / 1e9).toFixed(1)} GB`
+  return `${Math.round(bytes / 1e6)} MB`
+}
+
+/**
+ * Explain why a model cannot be used, rather than hiding it. An operator who
+ * pulled the wrong model needs to see it listed with the reason attached.
+ */
+function incompatibilityReason(c: EmbeddingCandidate, dims: number): string {
+  if (!c.embedding) return 'chat model — cannot embed'
+  if (c.dims !== dims) return `${c.dims ?? '?'} dims — index needs ${dims}`
+  return ''
+}
+
+export function EmbeddingProviderPanel() {
+  const [status, setStatus] = useState<EmbeddingProviderStatus | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [busy, setBusy] = useState(false)
+
+  const load = useCallback(async () => {
+    try {
+      setStatus(await fetchEmbeddingProvider())
+      setError(null)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err))
+    }
+  }, [])
+
+  useEffect(() => {
+    void load()
+  }, [load])
+
+  const onPin = useCallback(
+    async (model: string | null) => {
+      setBusy(true)
+      try {
+        await setEmbeddingModel(model)
+        await load()
+        setError(null)
+      } catch (err) {
+        setError(err instanceof Error ? err.message : String(err))
+      } finally {
+        setBusy(false)
+      }
+    },
+    [load],
+  )
+
+  const onRediscover = useCallback(async () => {
+    setBusy(true)
+    try {
+      await rediscoverEmbeddingProvider()
+      await load()
+      setError(null)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err))
+    } finally {
+      setBusy(false)
+    }
+  }, [load])
+
+  if (error && !status) {
+    return (
+      <div className="panel">
+        <h3 style={{ marginTop: 0 }}>Embedding Provider</h3>
+        <p role="alert">{error}</p>
+      </div>
+    )
+  }
+
+  if (!status) {
+    return (
+      <div className="panel">
+        <h3 style={{ marginTop: 0 }}>Embedding Provider</h3>
+        <p>Loading…</p>
+      </div>
+    )
+  }
+
+  const { local, fallbacks, dims } = status
+
+  return (
+    <div className="panel">
+      <div style={{ display: 'flex', alignItems: 'center', gap: 12, flexWrap: 'wrap' }}>
+        <h3 style={{ margin: 0 }}>Embedding Provider</h3>
+        <span
+          data-testid="embed-availability"
+          style={{ color: local.available ? 'var(--ok, #2ea043)' : 'var(--warn, #d29922)' }}
+        >
+          {local.available ? '● local' : '○ hosted fallback'}
+        </span>
+        <button type="button" onClick={onRediscover} disabled={busy}>
+          Re-discover
+        </button>
+      </div>
+
+      <dl style={{ display: 'grid', gridTemplateColumns: 'auto 1fr', gap: '4px 12px', margin: '12px 0' }}>
+        <dt>Endpoint</dt>
+        <dd data-testid="embed-endpoint" style={{ margin: 0 }}>
+          {local.endpoint ?? 'none reachable'}
+        </dd>
+        <dt>Model</dt>
+        <dd data-testid="embed-selected" style={{ margin: 0 }}>
+          {local.selected ?? '—'}
+          {local.preferred ? ' (pinned)' : local.selected ? ' (auto)' : ''}
+        </dd>
+        <dt>Vector width</dt>
+        <dd style={{ margin: 0 }}>{dims}</dd>
+      </dl>
+
+      {local.reason && <p role="status">{local.reason}</p>}
+      {error && <p role="alert">{error}</p>}
+
+      {local.candidates.length > 0 && (
+        <table style={{ width: '100%', borderCollapse: 'collapse' }}>
+          <thead>
+            <tr>
+              <th style={{ textAlign: 'left' }}>Model</th>
+              <th style={{ textAlign: 'left' }}>Size</th>
+              <th style={{ textAlign: 'left' }}>Status</th>
+              <th />
+            </tr>
+          </thead>
+          <tbody>
+            {local.candidates.map((c) => {
+              const reason = incompatibilityReason(c, dims)
+              const isSelected = c.name === local.selected
+              return (
+                <tr key={c.name}>
+                  <td>{c.name}</td>
+                  <td>{formatSize(c.size)}</td>
+                  <td style={{ opacity: c.compatible ? 1 : 0.6 }}>
+                    {c.compatible ? `${c.dims} dims` : reason}
+                  </td>
+                  <td style={{ textAlign: 'right' }}>
+                    {c.compatible && !isSelected && (
+                      <button type="button" onClick={() => onPin(c.name)} disabled={busy}>
+                        Use
+                      </button>
+                    )}
+                    {isSelected && local.preferred && (
+                      <button type="button" onClick={() => onPin(null)} disabled={busy}>
+                        Unpin
+                      </button>
+                    )}
+                  </td>
+                </tr>
+              )
+            })}
+          </tbody>
+        </table>
+      )}
+
+      <div style={{ marginTop: 12, fontSize: '0.9em', opacity: 0.8 }}>
+        Fallback chain:{' '}
+        {fallbacks.map((f, i) => (
+          <span key={f.provider}>
+            {i > 0 && ' → '}
+            <span style={{ textDecoration: f.configured ? 'none' : 'line-through' }}>{f.provider}</span>
+          </span>
+        ))}
+      </div>
+    </div>
+  )
+}

package/frontend/src/pages/MeshPage.tsx

@@ -24,6 +24,7 @@ import type {
 } from '../api/mesh';
 import type { HeadscaleNode, PreAuthKey as HeadscalePreAuthKey, HeadscaleUser } from '../api/headscale';
 import { MeshTopology } from '../components/MeshTopology';
+import { EmbeddingProviderPanel } from '../components/EmbeddingProviderPanel';
 import { LatencySparkline } from '../components/LatencySparkline';
 import './MeshPage.css';
 
@@ -359,6 +360,10 @@ export function MeshPage() {
 
       {activeTab === 'mesh' && (
         <div style={{ display: 'flex', flexDirection: 'column', gap: 24 }}>
+          {/* Which mesh node actually serves embeddings, and which model it uses. */}
+          <div className="card">
+            <EmbeddingProviderPanel />
+          </div>
           <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 16 }}>
             <div className="card">
               <h3 style={{ marginTop: 0, marginBottom: 12 }}>Topology</h3>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.21.3",
+  "version": "3.22.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/SKILL.md

@@ -331,6 +331,45 @@ npx total-recall secret list                          # metadata only, no values
 npx total-recall secret export-env --path <repo>       # SSOT → local .env.local
 ```
 
+### Executed rotation — `rotate-auto` / `rotate-browser` (added 3.22.0)
+
+Rotation used to only ever **print instructions**. It now executes. Every key
+resolves to one of four rotation classes, so nothing is silently unrotatable:
+
+| Class | How it rotates | Human needed? |
+|---|---|---|
+| `self_generated` | TR mints the value itself (`JWT_SECRET`, `DB_PASSWORD`, `*_WEBHOOK_SECRET`) | **No** |
+| `provider_browser` | TR drives the provider console in its own browser profile | Login/2FA once |
+| `provider_api` | Provider key-management API | No |
+| `manual` | Human-only artifact (SSH keys, recovery codes, OAuth app secrets) | Yes, with reason |
+
+```bash
+npx total-recall secret rotation-status               # coverage for every key
+npx total-recall secret rotation-status --json
+npx total-recall secret rotate-auto <key>             # pick the right method automatically
+npx total-recall secret rotate-browser <key>          # force the console path
+npx total-recall secret rotate-browser <key> --print-only   # legacy: just print steps
+npx total-recall secret browser-logout                # wipe TR's browser profile
+```
+
+**Browser profile.** Console rotation uses a persistent Chromium profile at
+`<brain>/browser-profile` (created `0700`). You log in once per provider; the
+daemon can then rotate unattended. That directory holds live Stripe/GitHub
+sessions — treat it as **equally sensitive to `secrets.enc`**: never sync it,
+never back it up off-machine, and `browser-logout` when you're done.
+
+**Safety invariants** (enforced by `rotation-capability.spec.mjs`):
+
+- The new value is read from the browser's own clipboard **inside TR's process** —
+  it never transits an argv string, an env var, or a chat transcript.
+- Only recipes marked `verified: true` auto-click. Unverified providers run
+  **supervised** — TR opens the console, tells you what to click, and detects the
+  result. It never blind-clicks guessed selectors on a billing dashboard.
+- A captured value is shape-checked against the provider pattern and, where an
+  API probe exists, **verified to authenticate before it replaces the old one**.
+  A failed check stores nothing.
+- The old credential is never revoked until the new one is stored and exported.
+
 ### Remote (production) deploy — `secret remote` (added 3.21.1)
 
 `export-env` only ever wrote a **local** file — there was no path from the

package/scaffold/.agent/skills/total-recall/research-queue.jsonl

@@ -1 +0,0 @@
-{"id":"0efa65c2-0231-4267-a304-e0285e50011e","topic":"Total Recall repository improvement research: SSSS validated write pipeline, filesystem-native memory engines, local-first semantic indexing, Express 5 API hardening, 2026 agent memory architecture patterns","status":"pending","priority":"high","notes":"Queued from repo-wide analysis request on 2026-06-01. Focus on current best practices and meta-patterns for filesystem-native memory OS, validated operation envelopes, append-only logs, cache invalidation, research queue architecture, and secure local-first AI tools.","node_slug":null,"research_phase":"acquisition","created_at":"2026-06-01T06:07:40.102Z","updated_at":"2026-06-01T06:07:40.126Z","completed_at":null,"summary":{"id":"0efa65c2-0231-4267-a304-e0285e50011e","topic":"Total Recall repository improvement research: SSSS validated write pipeline, filesystem-native memory engines, local-first semantic indexing, Express 5 API hardening, 2026 agent memory architecture patterns","status":"pending","phase":"acquisition","last_updated":"2026-06-01T06:07:40.126Z","conclusions":[],"ongoing_directions":["Research project is enqueued / in progress in phase: acquisition"],"sources_count":0}}

package/src/cli/secret.mjs

@@ -29,6 +29,7 @@ import {
   updateSecretMeta,
   listRotationDue,
   getSharedValueHealth,
+  loadSecrets,
 } from '../core/secrets-store.mjs';
 import {
   scanEnvSources,
@@ -140,7 +141,13 @@ function printHelp() {
     --headscale-url <https-url>
     rotation-due          List keys overdue for rotation
       --enqueue           Create daemon tasks + browser-use prompts for each due key
-    rotate-browser <key>  Print supervised browser-use rotation instructions
+    rotate-browser <key>  Drive the provider console in TR's browser and rotate
+      --print-only        Only print instructions (legacy behaviour)
+      --headless          Allow headless for verified recipes
+    rotate-auto <key>     Rotate by whatever method the key's class supports
+    rotation-status       Rotation coverage for every key in the vault
+      --json              Machine-readable output
+    browser-logout        Delete TR's persistent browser profile (all sessions)
     usage                 Cost/events (add --key-ref for per-key)
 
   rotate options:
@@ -239,9 +246,18 @@ function parseArgs(args) {
     }
   }
   if (
-    ['set', 'get', 'rotate', 'delete', 'meta', 'rotate-browser', 'rm', 'generate', 'account-sync'].includes(
-      out.command,
-    ) &&
+    [
+      'set',
+      'get',
+      'rotate',
+      'delete',
+      'meta',
+      'rotate-browser',
+      'rotate-auto',
+      'rm',
+      'generate',
+      'account-sync',
+    ].includes(out.command) &&
     args[i] &&
     !args[i].startsWith('--')
   ) {
@@ -376,6 +392,15 @@ function parseArgs(args) {
       case '--enqueue':
         out.enqueue = true;
         break;
+      case '--print-only':
+        out.printOnly = true;
+        break;
+      case '--headless':
+        out.headless = true;
+        break;
+      case '--json':
+        out.json = true;
+        break;
       case '--bytes':
         out.bytes = parseInt(args[++i], 10) || 32;
         break;
@@ -945,17 +970,73 @@ export default async function secretCli(argv) {
       return;
     }
 
-    if (opts.command === 'rotate-browser') {
+    if (opts.command === 'rotate-browser' || opts.command === 'rotate-auto') {
       if (!opts.key) {
-        console.error('Usage: total-recall secret rotate-browser <key>');
+        console.error(`Usage: total-recall secret ${opts.command} <key>`);
+        process.exit(1);
+      }
+
+      if (opts.printOnly) {
+        const assist = await getBrowserRotateAssist(brainDir, opts.key);
+        console.log(`\n  🌐 Supervised browser rotation — ${assist.key}\n`);
+        if (assist.console_url) console.log(`  Console: ${assist.console_url}`);
+        if (assist.docs_url) console.log(`  Docs:    ${assist.docs_url}`);
+        console.log(`  Overdue: ${assist.overdue ? 'YES' : 'no'}`);
+        console.log('\n' + assist.prompt + '\n');
+        return;
+      }
+
+      const { rotateViaBrowser, rotateAuto } = await import('../core/secrets-rotate.mjs');
+      const run = opts.command === 'rotate-auto' ? rotateAuto : rotateViaBrowser;
+      console.log(`\n  🔐 Rotating ${opts.key}…\n`);
+      const r = await run(brainDir, opts.key, {
+        headless: !!opts.headless,
+        exportEnv: opts.exportEnv !== false,
+        onStatus: (m) => console.log(`     · ${m}`),
+      });
+
+      if (!r.ok) {
+        console.error(`\n  ❌ ${r.error}`);
+        if (r.console_url) console.error(`     Console: ${r.console_url}`);
         process.exit(1);
       }
-      const assist = await getBrowserRotateAssist(brainDir, opts.key);
-      console.log(`\n  🌐 Supervised browser rotation — ${assist.key}\n`);
-      if (assist.console_url) console.log(`  Console: ${assist.console_url}`);
-      if (assist.docs_url) console.log(`  Docs:    ${assist.docs_url}`);
-      console.log(`  Overdue: ${assist.overdue ? 'YES' : 'no'}`);
-      console.log('\n' + assist.prompt + '\n');
+      console.log(`\n  ✅ Rotated ${r.key}` + (r.method ? ` via ${r.method}` : ''));
+      if (r.verified === true) console.log('     verified against provider API');
+      if (r.supervised) console.log('     (supervised — recipe not yet auto-verified)');
+      if (r.exports?.length) console.log(`     exported to ${r.exports.length} project(s)`);
+      if (r.revoke_hint) console.log(`\n  ⚠️  ${r.revoke_hint}`);
+      return;
+    }
+
+    if (opts.command === 'rotation-status') {
+      const { planAll, summarizePlans } = await import('../core/rotation-capability.mjs');
+      const all = await loadSecrets(brainDir);
+      const keys = Object.keys(all || {}).filter((k) => k !== 'meta');
+      const plans = planAll(keys, all.meta || {});
+      const sum = summarizePlans(plans);
+
+      if (opts.json) {
+        console.log(JSON.stringify({ summary: sum, plans }, null, 2));
+        return;
+      }
+
+      console.log(`\n  🔄 Rotation coverage — ${sum.automatable}/${sum.total} automatable\n`);
+      for (const [cls, n] of Object.entries(sum.byClass)) {
+        console.log(`     ${cls.padEnd(18)} ${n}`);
+      }
+      const manual = plans.filter((p) => !p.automatable && p.class !== 'non_secret');
+      if (manual.length) {
+        console.log(`\n  Needs a human (${manual.length}):`);
+        for (const p of manual) console.log(`     ${p.key.padEnd(34)} ${p.reason}`);
+      }
+      console.log('');
+      return;
+    }
+
+    if (opts.command === 'browser-logout') {
+      const { clearProfile } = await import('../core/browser-session.mjs');
+      const r = clearProfile(brainDir);
+      console.log(r.removed ? `  ✅ Cleared browser profile: ${r.path}` : `  (no profile at ${r.path})`);
       return;
     }