total-recall-brain 3.20.1 → 3.21.1

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.1",
+  "version": "3.21.1",
   "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/secret.mjs

@@ -48,6 +48,13 @@ import {
   enqueueRotationDueTasks,
   getBrowserRotateAssist,
 } from '../core/secrets-rotate.mjs';
+import {
+  loadRemoteTargets,
+  addRemoteTarget,
+  removeRemoteTarget,
+  deployEnvToRemote,
+  deployKeyToRemotes,
+} from '../core/secrets-remote-deploy.mjs';
 import { listProviders, getProvider } from '../core/provider-catalog.mjs';
 import { resolveBrainDir, parseLayerFlag } from './agent-dir.mjs';
 import fs from 'node:fs';
@@ -77,7 +84,18 @@ function printHelp() {
       --no-example        Skip .env.example
       --no-global         Only keys bound to this repo (skip unbound)
       --replace-all       Overwrite entire .env (default: merge TR block only)
+      --remote <name>     Also push the SSOT projection to a configured remote
+                           target over SSH (see 'secret remote') instead of
+                           (or in addition to) a local file
       --dry-run           Show keys that would be written
+    remote <cmd>          Manage remote (production) deploy targets — generic,
+                           per-repo config, no host/path ever hardcoded in TR
+      add <name>           --host <h> --path </remote/dir> [--user root]
+                            [--port 22] [--filename .env] [--restart-cmd "..."]
+      list                 Show configured targets (no secret values)
+      remove <name>        Delete a target
+      deploy <name>        Push the SSOT projection to that target now
+                            [--dry-run] [--keys k1,k2]
     import-env            One-time migrate: scan local .env → store (not the steady-state path)
       --all / --file / --overwrite / --dry-run
     catalog               Full catalog: keys, providers, usage, rotation, cost, tracking
@@ -116,6 +134,8 @@ function printHelp() {
   rotate options:
     --export-env          After rotate, write .env to bound repos (and cwd if unbound)
     --export-all          After rotate, export-env to all project-registry paths
+    --remote <name>       After rotate, also push to a configured remote target
+                           (production, etc.) over SSH — see 'secret remote'
 
   set / rotate options:
     --provider <name>     Optional provider tag (e.g. openai, anthropic)
@@ -186,6 +206,12 @@ function parseArgs(args) {
     exempt: false,
     tracking_exempt: null,
     shared_ok: null,
+    subcommand: null,
+    remote: null,
+    remoteHost: null,
+    remoteUser: 'root',
+    remotePort: 22,
+    restartCmd: null,
   };
   if (!args.length || args[0] === '--help' || args[0] === '-h') {
     out.help = true;
@@ -193,6 +219,12 @@ function parseArgs(args) {
   }
   out.command = args[0];
   let i = 1;
+  if (out.command === 'remote') {
+    if (args[i] && !args[i].startsWith('--')) out.subcommand = args[i++];
+    if (['add', 'remove', 'rm', 'deploy'].includes(out.subcommand) && args[i] && !args[i].startsWith('--')) {
+      out.key = args[i++]; // reused as the remote target name
+    }
+  }
   if (
     ['set', 'get', 'rotate', 'delete', 'meta', 'rotate-browser', 'rm', 'generate', 'account-sync'].includes(
       out.command,
@@ -208,6 +240,21 @@ function parseArgs(args) {
   while (i < args.length) {
     const a = args[i];
     switch (a) {
+      case '--remote':
+        out.remote = args[++i];
+        break;
+      case '--host':
+        out.remoteHost = args[++i];
+        break;
+      case '--user':
+        out.remoteUser = args[++i] || 'root';
+        break;
+      case '--port':
+        out.remotePort = parseInt(args[++i], 10) || 22;
+        break;
+      case '--restart-cmd':
+        out.restartCmd = args[++i];
+        break;
       case '--provider':
         out.provider = args[++i];
         break;
@@ -724,11 +771,121 @@ export default async function secretCli(argv) {
       return;
     }
 
+    if (opts.command === 'remote') {
+      if (!opts.subcommand) {
+        console.error(
+          'Usage: total-recall secret remote <add|list|remove|deploy> [...]\n' +
+            '  add <name> --host <h> --path </remote/dir> [--user root] [--port 22] [--filename .env] [--restart-cmd "..."]\n' +
+            '  list\n' +
+            '  remove <name>\n' +
+            '  deploy <name> [--dry-run] [--keys k1,k2]',
+        );
+        process.exit(1);
+      }
+
+      if (opts.subcommand === 'add') {
+        if (!opts.key || !opts.remoteHost || !opts.path) {
+          console.error(
+            'Usage: total-recall secret remote add <name> --host <host> --path </remote/dir> [--user root] [--port 22] [--filename .env] [--restart-cmd "..."]',
+          );
+          process.exit(1);
+        }
+        const { path: targetsPath } = addRemoteTarget(brainDir, {
+          name: opts.key,
+          host: opts.remoteHost,
+          user: opts.remoteUser,
+          port: opts.remotePort,
+          remotePath: opts.path,
+          filename: opts.filename || '.env',
+          restartCommand: opts.restartCmd || null,
+          keys: opts.keys.length ? opts.keys : undefined,
+        });
+        console.log(`\n  ✅ Remote target added: ${opts.key}`);
+        console.log(`     ${opts.remoteUser}@${opts.remoteHost}:${opts.path}/${opts.filename || '.env'}`);
+        if (opts.restartCmd) console.log(`     restart: ${opts.restartCmd}`);
+        console.log(`     config: ${targetsPath}\n`);
+        return;
+      }
+
+      if (opts.subcommand === 'list') {
+        const targets = loadRemoteTargets(brainDir);
+        if (!targets.length) {
+          console.log(`\n  No remote targets configured for this repo.\n`);
+          return;
+        }
+        console.log(`\n  Remote deploy targets\n`);
+        for (const t of targets) {
+          console.log(
+            `  • ${t.name.padEnd(20)} ${t.user}@${t.host}:${t.port}  ${t.remotePath}/${t.filename}`,
+          );
+          if (t.restartCommand) console.log(`      restart: ${t.restartCommand}`);
+          if (t.keys?.length) console.log(`      keys: ${t.keys.join(', ')}`);
+        }
+        console.log('');
+        return;
+      }
+
+      if (opts.subcommand === 'remove' || opts.subcommand === 'rm') {
+        if (!opts.key) {
+          console.error('Usage: total-recall secret remote remove <name>');
+          process.exit(1);
+        }
+        const r = removeRemoteTarget(brainDir, opts.key);
+        console.log(r.removed ? `  ✅ Removed remote target: ${opts.key}` : `  Remote target not found: ${opts.key}`);
+        return;
+      }
+
+      if (opts.subcommand === 'deploy') {
+        if (!opts.key) {
+          console.error('Usage: total-recall secret remote deploy <name> [--dry-run] [--keys k1,k2]');
+          process.exit(1);
+        }
+        const r = await deployEnvToRemote(brainDir, opts.key, {
+          dryRun: opts.dryRun,
+          keys: opts.keys.length ? opts.keys : undefined,
+        });
+        if (r.dryRun) {
+          console.log(`\n  📤 dry-run remote deploy → ${r.target} (${r.host})`);
+          console.log(`     would write ${r.count} keys → ${r.remoteFile}\n`);
+          return;
+        }
+        console.log(`\n  ✅ Deployed ${r.count} secret(s) → ${r.target} (${r.host}:${r.remoteFile})`);
+        if (r.restarted) console.log(`     restart: ok`);
+        else if (r.restartOutput) console.log(`     restart: FAILED — ${r.restartOutput.slice(0, 300)}`);
+        console.log(`     (values written with mode 0600 remotely; not printed)\n`);
+        return;
+      }
+
+      console.error(`Unknown remote subcommand: ${opts.subcommand}`);
+      process.exit(1);
+    }
+
     if (opts.command === 'rotate') {
       if (!opts.key || !opts.value) {
-        console.error('Usage: total-recall secret rotate <key> <new-value> [--export-env|--export-all]');
+        console.error('Usage: total-recall secret rotate <key> <new-value> [--export-env|--export-all|--remote <name>]');
         process.exit(1);
       }
+      if (opts.remote) {
+        await rotateSecret(brainDir, opts.key, opts.value, { provider: opts.provider, scope: opts.scope });
+        console.log(`  ✅ Rotated: ${opts.key}`);
+        const r = await deployEnvToRemote(brainDir, opts.remote, {});
+        console.log(`  ✅ Deployed to remote target: ${r.target} (${r.host}:${r.remoteFile}, ${r.count} keys)`);
+        if (r.restarted) console.log(`     restart: ok`);
+        else if (r.restartOutput) console.log(`     restart: FAILED — ${r.restartOutput.slice(0, 300)}`);
+        if (opts.exportEnv || opts.exportAll) {
+          const localR = await rotateSecretAndExport(brainDir, opts.key, opts.value, {
+            provider: opts.provider,
+            actor: 'cli',
+            exportEnv: true,
+            exportAllProjects: opts.exportAll,
+            exportCwd: true,
+            includeGlobal: true,
+          });
+          const ok = (localR.exports || []).filter((e) => e.ok !== false);
+          console.log(`     local export-env: ${ok.length} target(s)`);
+        }
+        return;
+      }
       if (opts.exportEnv || opts.exportAll) {
         const r = await rotateSecretAndExport(brainDir, opts.key, opts.value, {
           provider: opts.provider,
@@ -859,6 +1016,23 @@ export default async function secretCli(argv) {
         keys: opts.keys.length ? opts.keys : undefined,
       };
 
+      if (opts.remote) {
+        const r = await deployEnvToRemote(brainDir, opts.remote, {
+          dryRun: opts.dryRun,
+          keys: opts.keys.length ? opts.keys : undefined,
+        });
+        if (r.dryRun) {
+          console.log(`\n  📤 dry-run remote export → ${r.target} (${r.host})`);
+          console.log(`     would write ${r.count} keys → ${r.remoteFile}\n`);
+        } else {
+          console.log(`\n  ✅ Exported ${r.count} secret(s) → ${r.target} (${r.host}:${r.remoteFile})`);
+          if (r.restarted) console.log(`     restart: ok`);
+          else if (r.restartOutput) console.log(`     restart: FAILED — ${r.restartOutput.slice(0, 300)}`);
+          console.log(`     (values written with mode 0600 remotely; not printed)\n`);
+        }
+        if (!opts.path && !opts.allProjects) return; // --remote alone doesn't also touch local disk
+      }
+
       if (opts.allProjects) {
         const results = await exportEnvToRegistry(brainDir, exportOpts);
         console.log(`\n  📤 export-env → ${results.length} project(s) from ${resolveSecretsPath(brainDir)}\n`);