total-recall-brain 3.40.0 → 3.40.2

package/scaffold/.agent/skills/total-recall/plugins/security/src/machines.mjs

@@ -0,0 +1,164 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { auditWindows } from './windows.mjs';
+import { auditAndroid } from './android.mjs';
+import { normalizePlatform } from './devices.mjs';
+
+export function runCheck(command, args) {
+  const result = spawnSync(command, args, { encoding: 'utf8', timeout: 8000, maxBuffer: 262144, stdio: ['ignore', 'pipe', 'pipe'] });
+  // Diagnostics deliberately exclude stderr: system tools can include sensitive configuration.
+  return { ok: !result.error && result.status === 0, output: !result.error && result.status === 0 ? result.stdout : '', reason: result.error?.code || (result.status === 0 ? null : 'unavailable-or-insufficient-privilege') };
+}
+
+export function parseListeners(output, platform, protocol = 'tcp') {
+  const endpoints = new Map();
+  for (const line of output.split('\n')) {
+    const endpoint = platform === 'darwin' ? (line.startsWith('n') ? line.slice(1).replace(/ \(LISTEN\)$/, '') : '') : line.trim().split(/\s+/)[3];
+    if (!endpoint) continue;
+    const match = endpoint.match(/^(.*):(\d+)$/);
+    if (!match) continue;
+    const address = match[1].replace(/^\[|\]$/g, '');
+    const port = Number(match[2]);
+    if (port < 1 || port > 65535) continue;
+    const scope = address === '*' || address === '0.0.0.0' || address === '::' ? 'all-interfaces' : address === '::1' || /^127\./.test(address) ? 'loopback' : 'interface';
+    endpoints.set(`${address}:${port}`, { address, port, scope, protocol });
+  }
+  return [...endpoints.values()];
+}
+
+function sshPermissions(home) {
+  const directory = path.join(home, '.ssh');
+  if (!fs.existsSync(directory)) return { state: 'not-configured', files: [] };
+  const root = fs.lstatSync(directory);
+  if (root.isSymbolicLink() || !root.isDirectory()) return { state: 'unavailable', reason: 'SSH directory must be a regular directory', files: [] };
+  const files = [{ path: directory, expected: 0o700, mode: root.mode & 0o777, directory: true }];
+  for (const entry of fs.readdirSync(directory)) {
+    const file = path.join(directory, entry);
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink()) continue;
+    // Never read private key material; only inspect metadata for recognized SSH files.
+    if (stat.isFile() && (/^id_[\w-]+$/.test(entry) || ['config', 'authorized_keys'].includes(entry))) {
+      files.push({ path: file, mode: stat.mode & 0o777, expected: 0o600, directory: false });
+    }
+  }
+  return { state: 'observed', files };
+}
+
+export async function auditMachine({ platform = process.platform, hostname = os.hostname(), home = os.homedir(), execute = runCheck } = {}) {
+  if (platform === 'win32') return auditWindows({ execute, hostname });
+  if (platform === 'android') return auditAndroid({ execute, hostname });
+  const checks = [];
+  const add = (id, result, classify, remediation) => {
+    const state = result.ok ? classify(result.output) : 'unavailable';
+    checks.push({ id, state, severity: state === 'fail' ? 'HIGH' : state === 'review' ? 'MEDIUM' : null, remediation: state === 'pass' ? null : remediation, ...(result.ok ? {} : { reason: result.reason || 'check-unavailable' }) });
+  };
+  if (!['darwin', 'linux'].includes(platform)) return { schema: 'security-machine/v1', hostname, platform, timestamp: new Date().toISOString(), status: 'incomplete', checks: [], listeners: [], coverage: { complete: false, reason: 'unsupported-platform' } };
+  if (platform === 'darwin') {
+    add('firewall', execute('/usr/libexec/ApplicationFirewall/socketfilterfw', ['--getglobalstate']), text => /enabled/i.test(text) ? 'pass' : /disabled/i.test(text) ? 'fail' : 'unavailable', 'Enable the application firewall in System Settings → Network → Firewall; review application exceptions and verify again.');
+    add('disk-encryption', execute('/usr/bin/fdesetup', ['status']), text => /FileVault is On/.test(text) ? 'pass' : /FileVault is Off/.test(text) ? 'fail' : 'unavailable', 'Enable FileVault in Privacy & Security after verifying recovery-key custody and a current backup.');
+    add('gatekeeper', execute('/usr/sbin/spctl', ['--status']), text => /assessments enabled/.test(text) ? 'pass' : /assessments disabled/.test(text) ? 'fail' : 'unavailable', 'Enable application assessment; investigate why it was disabled before accepting unsigned software.');
+    add('system-integrity', execute('/usr/bin/csrutil', ['status']), text => /status: enabled/.test(text) ? 'pass' : /status: disabled/.test(text) ? 'fail' : 'unavailable', 'Restore System Integrity Protection through macOS Recovery with physical access and a verified backup.');
+    add('automatic-updates', execute('/usr/sbin/softwareupdate', ['--schedule']), text => /turned on/.test(text) ? 'pass' : /turned off/.test(text) ? 'review' : 'unavailable', 'Enable automatic security updates and verify the installed OS is supported.');
+  } else {
+    add('firewall', execute('ufw', ['status']), text => /Status: active/.test(text) ? 'pass' : /Status: inactive/.test(text) ? 'fail' : 'unavailable', 'Inspect the active firewall backend with administrator access. Preserve verified SSH/mesh access, review allow rules and default inbound policy, then verify from a second connection. UFW unavailable does not establish absence of nftables/firewalld protection.');
+    const root = execute('findmnt', ['-n', '-o', 'SOURCE', '/']);
+    const source = root.output?.trim();
+    const disk = root.ok && source?.startsWith('/dev/') ? execute('lsblk', ['-s', '-n', '-o', 'TYPE', source]) : { ok: false, reason: 'root-storage-encryption-not-observable' };
+    add('disk-encryption', disk, text => /(^|\n)crypt(\n|$)/.test(text.trim()) ? 'pass' : 'review', 'Verify root-volume encryption and provider storage policy; this check cannot prove encryption of every volume or remote storage.');
+    add('automatic-updates', execute('systemctl', ['is-enabled', 'unattended-upgrades.service']), text => /^(enabled|static)\s*$/.test(text) ? 'review' : 'unavailable', 'Inspect your distribution security-update timers and last successful run. A configured service alone does not prove patches are installed.');
+  }
+  const ssh = execute('/usr/sbin/sshd', ['-T']);
+  const settings = Object.fromEntries(ssh.ok ? ssh.output.split('\n').map(line => line.trim().split(/\s+/, 2)).filter(parts => parts.length === 2) : []);
+  for (const [setting, expected] of [['permitrootlogin', 'no'], ['passwordauthentication', 'no'], ['permitemptypasswords', 'no'], ['pubkeyauthentication', 'yes']]) {
+    add(`ssh-${setting}`, { ok: ssh.ok && Object.hasOwn(settings, setting), output: settings[setting] || '', reason: ssh.reason || 'effective-setting-unavailable' }, value => value === expected ? 'pass' : 'fail', `Review effective SSH ${setting}=${expected}, including Match blocks. Validate sshd -t and a second key-authenticated session before any reload; retain rollback access.`);
+  }
+  const listening = platform === 'darwin' ? execute('/usr/sbin/lsof', ['-nP', '-iTCP', '-sTCP:LISTEN', '-Fn']) : execute('ss', ['-H', '-lnt']);
+  const listeners = listening.ok ? parseListeners(listening.output, platform) : [];
+  add('listening-ports', listening, () => listeners.some(item => item.scope !== 'loopback') ? 'review' : 'pass', 'Review every non-loopback listener. Bind private services to loopback or the mesh interface and verify firewall rules plus an authorized external vantage. Bind scope alone does not prove Internet exposure.');
+  const udp = platform === 'darwin' ? execute('/usr/sbin/lsof', ['-nP', '-iUDP', '-Fn']) : execute('ss', ['-H', '-lnu']);
+  const udpListeners = udp.ok ? parseListeners(udp.output, platform, 'udp') : [];
+  add('udp-bindings', udp, () => udpListeners.some(item => item.scope !== 'loopback') ? 'review' : 'pass', 'Review UDP bindings and firewall rules, including discovery and DNS services. A local binding alone does not establish remote reachability.');
+  listeners.push(...udpListeners);
+  let permissions;
+  try { permissions = sshPermissions(home); } catch { permissions = { state: 'unavailable', files: [], reason: 'SSH metadata inspection failed' }; }
+  checks.push({ id: 'ssh-file-permissions', state: permissions.state === 'observed' ? permissions.files.some(file => (file.mode & ~file.expected) !== 0) ? 'fail' : 'pass' : permissions.state === 'not-configured' ? 'not-applicable' : 'unavailable', severity: permissions.files.some(file => (file.mode & ~file.expected) !== 0) ? 'HIGH' : null, remediation: 'Use security machine --apply-permissions to restrict recognized local SSH files; symbolic links are never modified.' });
+  const complete = checks.every(check => check.state !== 'unavailable');
+  return { schema: 'security-machine/v1', hostname, platform, timestamp: new Date().toISOString(), status: checks.some(check => check.state === 'fail') ? 'at-risk' : !complete ? 'incomplete' : checks.some(check => check.state === 'review') ? 'review-required' : 'passed', coverage: { complete, observed: checks.filter(check => !['unavailable', 'not-applicable'].includes(check.state)).length, total: checks.length, limitations: ['Scope is the current OS runtime; a Linux container does not certify its Chromebook, Windows or other host', 'TCP/UDP bindings visible to current user only', 'No external reachability or patch-currency certification', 'SSH Match blocks require connection-specific review'] }, checks, listeners, permissions };
+}
+
+export function hardenSshPermissions({ home = os.homedir() } = {}) {
+  const inspection = sshPermissions(home);
+  if (inspection.state !== 'observed') throw new Error('SSH directory cannot be safely hardened');
+  const actions = [];
+  for (const file of inspection.files) {
+    if ((file.mode & ~file.expected) === 0) continue;
+    let fd;
+    try {
+      // Lock to the inspected inode; refuse symlink/ownership changes instead of following them.
+      const parent = fs.lstatSync(path.join(home, '.ssh'));
+      if (parent.isSymbolicLink() || !parent.isDirectory()) throw new Error('SSH directory changed');
+      fd = fs.openSync(file.path, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+      const before = fs.fstatSync(fd);
+      const current = fs.lstatSync(file.path);
+      if (before.ino !== current.ino || before.dev !== current.dev || before.uid !== process.getuid()) throw new Error('Ownership or identity changed');
+      fs.fchmodSync(fd, file.expected);
+      if ((fs.fstatSync(fd).mode & 0o777) !== file.expected) throw new Error('Verification failed');
+      actions.push({ path: file.path, before: file.mode.toString(8), after: file.expected.toString(8), status: 'verified' });
+    } catch { actions.push({ path: file.path, status: 'failed', reason: 'Unsafe path, ownership, or permission verification failure' }); }
+    finally { if (fd !== undefined) fs.closeSync(fd); }
+  }
+  return { status: actions.some(action => action.status === 'failed') ? 'failed' : 'verified', changed: actions.filter(action => action.status === 'verified').length, actions };
+}
+
+export async function loadOwner(id, name) {
+  const host = process.env.TR_PACKAGE_ROOT;
+  const runtime = host ? await import(pathToFileURL(path.join(host, 'src/core/plugin-runtime.mjs')).href) : await import('total-recall-brain/src/core/plugin-runtime.mjs');
+  return runtime.loadPluginModule(id, name);
+}
+
+export async function auditFleet({ mesh, target, auditLocal = auditMachine } = {}) {
+  mesh ||= await loadOwner('mesh', 'mesh');
+  if (!mesh.isMeshAvailable()) throw new Error('Mesh runtime is unavailable; fleet coverage cannot be established');
+  const nodes = mesh.getMeshPeers({ includeSelf: true });
+  const selected = target ? nodes.filter(node => node.hostname === target || node.ip === target) : nodes;
+  if (!selected.length) throw new Error('No matching discovered mesh machines');
+  const reports = [];
+  // Sequential bounded execution avoids exhausting every peer at once.
+  for (const node of selected) {
+    if (!node.online) { reports.push({ hostname: node.hostname, state: 'unavailable', reason: 'mesh-peer-offline' }); continue; }
+    let devicePlatform;
+    try { devicePlatform = normalizePlatform(String(node.os || '').toLowerCase()); } catch { /* native machine path */ }
+    if (!node.self && ['ios', 'ipados', 'android', 'chromeos', 'chromeos-flex'].includes(devicePlatform)) {
+      reports.push({ hostname: node.hostname, state: 'unavailable', reason: 'No authenticated native posture collector is connected for this device', assessment: { platform: devicePlatform, command: 'security device', evidence: 'manual-review-required' } }); continue;
+    }
+    try {
+      let report;
+      let transportIdentity = node.hostname;
+      if (node.self) report = await auditLocal();
+      else {
+        const response = await mesh.execMeshCommand(node.hostname, 'total-recall security machine --json', { timeoutMs: 120000 });
+        // A collector exit 1 is an actual risk/incomplete report, not a transport success.
+        if (![0, 1].includes(response.exitCode)) throw new Error('remote-collector-failed');
+        transportIdentity = response.hostname;
+        report = JSON.parse(response.stdout);
+      }
+      const age = Date.now() - Date.parse(report.timestamp);
+      // Mesh authenticates the target; OS hostname may differ from its registered mesh name.
+      if (transportIdentity !== node.hostname || report.schema !== 'security-machine/v1' || typeof report.hostname !== 'string' || !report.hostname || !Array.isArray(report.checks) || !['passed', 'at-risk', 'incomplete', 'review-required'].includes(report.status) || typeof report.coverage?.complete !== 'boolean' || !Number.isFinite(age) || age < -5000 || age > 180000) throw new Error('remote-report-identity-schema-or-freshness-invalid');
+      const states = new Set(['pass', 'fail', 'review', 'unavailable', 'not-applicable']);
+      if (report.checks.some(check => typeof check.id !== 'string' || !states.has(check.state))) throw new Error('invalid-check-state');
+      if (report.checks.length) {
+        const complete = report.checks.every(check => check.state !== 'unavailable');
+        const observed = report.checks.filter(check => !['unavailable', 'not-applicable'].includes(check.state)).length;
+        const expectedStatus = report.checks.some(check => check.state === 'fail') ? 'at-risk' : !complete ? 'incomplete' : report.checks.some(check => check.state === 'review') ? 'review-required' : 'passed';
+        if (report.coverage.complete !== complete || report.coverage.total !== report.checks.length || report.coverage.observed !== observed || report.status !== expectedStatus) throw new Error('inconsistent-report-claims');
+      } else if (report.status !== 'incomplete' || report.coverage.complete) throw new Error('empty-report-cannot-pass');
+      reports.push({ hostname: node.hostname, state: 'observed', report });
+    } catch { reports.push({ hostname: node.hostname, state: 'unavailable', reason: 'Remote collector unavailable, invalid, or insufficiently authorized' }); }
+  }
+  const complete = reports.every(item => item.state === 'observed' && item.report.coverage.complete);
+  return { schema: 'security-fleet/v1', timestamp: new Date().toISOString(), status: reports.some(item => item.report?.status === 'at-risk') ? 'at-risk' : !complete ? 'incomplete' : reports.some(item => item.report.status !== 'passed') ? 'review-required' : 'passed', coverage: { complete, discovered: nodes.length, selected: selected.length, observed: reports.filter(item => item.state === 'observed').length }, machines: reports };
+}

package/scaffold/.agent/skills/total-recall/plugins/security/src/scanner.mjs

@@ -0,0 +1,41 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Findings contain locations and rule identifiers only, never matched source or values.
+export function scanSource(targetPath) {
+  const root = fs.realpathSync(path.resolve(targetPath));
+  const findings = [];
+  const skipped = new Set(['node_modules', '.git', 'dist', 'coverage', 'memory-vault', '.cache', '.venv', '__pycache__']);
+  let count = 0;
+  function visit(file) {
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink()) {
+      findings.push({ file: path.relative(root, file), line: 0, rule: 'uninspected-symlink', severity: 'HIGH', detail: 'Linked source was not inspected; coverage incomplete' });
+      return;
+    }
+    if (stat.isDirectory()) {
+      for (const name of fs.readdirSync(file)) if (!skipped.has(name)) visit(path.join(file, name));
+      return;
+    }
+    if (!stat.isFile() || !/\.(?:[cm]?js|tsx?|py|sh|bash|ps1|json|env|ya?ml)$|(?:^|\/)\.env(?:\.|$)/.test(file)) return;
+    if (++count > 20000 || stat.size > 2097152) throw new Error('Scan coverage limit exceeded; narrow the target');
+    const testFile = /(?:^|\/)(?:test|tests|fixtures)(?:\/|$)|\.(?:test|spec)\./.test(file);
+    fs.readFileSync(file, 'utf8').split('\n').forEach((line, index) => {
+      const rules = [];
+      if (/^\s*(?:\/\/|\*|\/\*)/.test(line)) return;
+      if (!testFile && /(?:process\.env|\benv)\s*\[\s*(?:key|name|secretRef|TOKEN_KEY|API_KEY_ENV)\s*\]/.test(line)) rules.push(['dynamic-credential-source-review', 'HIGH']);
+      if (!testFile && /(?:fallback_(?:geo|rev|place|route)|tr-tickets-default-secret)/.test(line)) rules.push(['synthetic-provider-or-signing-default', 'HIGH']);
+      if (/\beval\s*\(|new\s+Function\s*\(/.test(line)) rules.push(['code-evaluation', 'CRITICAL']);
+      if (/(?:api[_-]?key|secret|password|token)\s*[:=]\s*['"][\w+/=-]{16,}['"]/i.test(line)) rules.push(['embedded-credential', 'HIGH']);
+      if (/-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/.test(line)) rules.push(['private-key-material', 'CRITICAL']);
+      if (!testFile && /process\.env(?:\.[A-Z_]*(?:API_KEY|SECRET|TOKEN|PASSWORD)\b|\[['"][A-Z_]*(?:API_KEY|SECRET|TOKEN|PASSWORD)['"]\])/.test(line)) rules.push(['ambient-credential-bypass-review', 'HIGH']);
+      if (!testFile && /os\.(?:getenv\(\s*|environ(?:\.get\(\s*|\[\s*))['"][A-Z_]*(?:API_KEY|SECRET|TOKEN|PASSWORD)['"]/.test(line)) rules.push(['python-ambient-credential-review', 'HIGH']);
+      if (!testFile && /\.(?:sh|bash|ps1)$/.test(file) && /\$(?:env:|\{)?[A-Z_]*(?:API_KEY|SECRET|TOKEN|PASSWORD)\b/.test(line)) rules.push(['shell-ambient-credential-review', 'HIGH']);
+      if (!testFile && /(?:from\s*|import\s*\()\s*['"][^'"]*total-recall[^'"]*\/(?:secrets-store|secrets-gateway|crypto)\.mjs/.test(line)) rules.push(['core-secret-ownership', 'HIGH']);
+      if (!testFile && /(?:secret|passphrase|password).*(?:\|\||\?\?).*['"][^'"]+['"]/i.test(line)) rules.push(['credential-default-review', 'HIGH']);
+      for (const [rule, severity] of rules) findings.push({ file: path.relative(root, file) || path.basename(file), line: index + 1, rule, severity, detail: 'Review owning source; matched content withheld' });
+    });
+  }
+  visit(root);
+  return findings;
+}

package/scaffold/.agent/skills/total-recall/plugins/security/src/windows.mjs

@@ -0,0 +1,42 @@
+// Fixed native queries select posture only, never BitLocker recovery material.
+const queries = {
+  firewall: "Get-NetFirewallProfile -PolicyStore ActiveStore | Select-Object Name,@{Name='Enabled';Expression={$_.Enabled.ToString()}},DefaultInboundAction",
+  antivirus: 'Get-MpComputerStatus | Select-Object AntivirusEnabled,RealTimeProtectionEnabled,AMRunningMode,AntivirusSignatureAge',
+  encryption: 'Get-BitLockerVolume -MountPoint $env:SystemDrive | Select-Object VolumeStatus,ProtectionStatus,EncryptionPercentage',
+  'secure-boot': 'Confirm-SecureBootUEFI',
+  tcp: 'Get-NetTCPConnection -State Listen | Select-Object LocalAddress,LocalPort',
+  udp: 'Get-NetUDPEndpoint | Select-Object LocalAddress,LocalPort',
+};
+export function auditWindows({ execute, hostname }) {
+  const checks = [], listeners = [];
+  for (const [id, query] of Object.entries(queries)) {
+    const result = execute('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', `$ErrorActionPreference='Stop'; @(${query}) | ConvertTo-Json -Compress -Depth 3`]);
+    let values, state = 'unavailable';
+    try { if (result.ok) { values = JSON.parse(result.output); if (!Array.isArray(values)) values = [values]; } } catch { /* malformed output is unavailable */ }
+    if (values?.length) {
+      if (id === 'firewall' && ['Domain', 'Private', 'Public'].every(name => values.filter(v => v?.Name === name).length === 1) && values.length === 3 && values.every(v => [true, false, 'True', 'False'].includes(v.Enabled))) state = values.every(v => v.Enabled === true || v.Enabled === 'True') ? 'review' : 'fail';
+      if (id === 'antivirus' && values.length === 1 && typeof values[0]?.AntivirusEnabled === 'boolean' && typeof values[0]?.RealTimeProtectionEnabled === 'boolean') state = values[0].AntivirusEnabled && values[0].RealTimeProtectionEnabled && values[0].AMRunningMode === 'Normal' && Number.isInteger(values[0].AntivirusSignatureAge) && values[0].AntivirusSignatureAge <= 1 && values[0].AntivirusSignatureAge >= 0 ? 'pass' : 'review';
+      if (id === 'encryption' && values.length === 1) {
+        const v = values[0];
+        if (v && [0, 1, 'On', 'Off'].includes(v.ProtectionStatus) && Number.isFinite(v.EncryptionPercentage) && v.EncryptionPercentage >= 0 && v.EncryptionPercentage <= 100) state = [1, 'On'].includes(v.ProtectionStatus) && v.EncryptionPercentage === 100 ? 'pass' : 'fail';
+      }
+      if (id === 'secure-boot' && values.length === 1 && typeof values[0] === 'boolean') state = values[0] ? 'pass' : 'fail';
+    }
+    if ((id === 'tcp' || id === 'udp') && values && values.every(v => v && typeof v.LocalAddress === 'string' && /^[0-9a-fA-F:.%]+$/.test(v.LocalAddress) && Number.isInteger(v.LocalPort) && v.LocalPort > 0 && v.LocalPort <= 65535)) {
+      const endpoints = values.map(v => ({ address: v.LocalAddress, port: v.LocalPort, protocol: id, scope: ['0.0.0.0', '::'].includes(v.LocalAddress) ? 'all-interfaces' : v.LocalAddress === '::1' || /^127\./.test(v.LocalAddress) ? 'loopback' : 'interface' }));
+      listeners.push(...endpoints); state = endpoints.some(v => v.scope !== 'loopback') ? 'review' : 'pass';
+    }
+    const guidance = {
+      firewall: 'Review all three active firewall profiles and inbound allow rules. Enabled profiles alone do not certify blocked exposure. Preserve a verified management path before changes.',
+      antivirus: 'Review Windows Security active providers, real-time protection and signature updates. Passive or unavailable built-in protection requires checking the actual installed provider.',
+      encryption: 'Review system-volume Device encryption / BitLocker protection and recovery custody. This query does not inspect other disks or collect recovery keys.',
+      'secure-boot': 'Review UEFI Secure Boot and hardware requirements. Unsupported firmware or insufficient privilege is unverified, not disabled. Keep recovery access before firmware changes.',
+      tcp: 'Review non-loopback TCP listeners and firewall rules; local binds do not prove remote reachability.',
+      udp: 'Review UDP bindings and firewall rules; verify reachability from an authorized external vantage.',
+    };
+    checks.push({ id, state, evidence: state === 'unavailable' ? 'none' : 'native-command', severity: state === 'fail' ? 'HIGH' : null, remediation: state === 'pass' ? null : guidance[id], ...(state === 'unavailable' ? { reason: 'native-query-unavailable-or-invalid; edition, permission or tooling may restrict access' } : {}) });
+  }
+  checks.push({ id: 'patch-currency', state: 'unavailable', evidence: 'none', remediation: 'Review Windows Update and support entitlement for the installed release. Service presence cannot certify patch currency.' });
+  const complete = checks.every(v => v.state !== 'unavailable');
+  return { schema: 'security-machine/v1', hostname, platform: 'win32', timestamp: new Date().toISOString(), status: checks.some(v => v.state === 'fail') ? 'at-risk' : !complete ? 'incomplete' : 'review-required', coverage: { complete, observed: checks.filter(v => v.state !== 'unavailable').length, total: checks.length, limitations: ['Current machine only; no administrative changes', 'Patch currency and alternate antivirus providers require review', 'System volume only; no recovery keys collected', 'Listener visibility does not certify Internet exposure'] }, checks, listeners };
+}

package/scaffold/.agent/skills/total-recall/plugins/security/ui/DESIGN.md

@@ -0,0 +1,18 @@
+# DESIGN.md — Tin Foil
+
+```yaml
+tokens:
+  brand-name: "Tin Foil"
+  wordmark: "[TIN//FOIL]"
+  color-primary: "#f59e0b"
+  color-background: "#0a0a0c"
+  color-accent: "#e2e8f0"
+  badge: "Hardening"
+  font-mono: "'JetBrains Mono', 'Fira Code', monospace"
+  border-radius: "8px"
+```
+
+## Brand & Typographic Wordmark
+- **Name**: Tin Foil
+- **Wordmark Logo**: `[TIN//FOIL]` (custom typographic badge, no generic icons)
+- **Palette**: Primary `#f59e0b`, Surface `#0a0a0c`, Accent `#e2e8f0`.

package/scaffold/.agent/skills/total-recall/plugins/security/ui/card.js

@@ -0,0 +1,95 @@
+export class SecuritySecurityCard extends HTMLElement {
+  connectedCallback() {
+    if (this.shadowRoot) return;
+    const root = this.attachShadow({ mode: 'open' });
+    root.innerHTML = `<style>
+      :host{display:block;color:#edf3fa;background:#16222e;font:14px system-ui;border-radius:12px;padding:18px}header{display:flex;align-items:center;gap:12px}svg{width:32px;height:38px;color:#73d6bf}h2{margin:0;font-size:20px}p{color:#bbcad6;line-height:1.5}nav{display:flex;gap:8px;flex-wrap:wrap}button,input,select{min-height:44px;border:1px solid #71928e;border-radius:6px;padding:8px 12px;background:#213644;color:inherit}button{cursor:pointer}button:disabled{opacity:.5}input{min-width:0;flex:1}#state{margin:14px 0;color:#73d6bf}table{width:100%;border-collapse:collapse}td,th{padding:10px 6px;text-align:left;border-bottom:1px solid #3a4e5c;vertical-align:top}td:last-child{line-height:1.5}pre{white-space:pre-wrap;overflow-wrap:anywhere;max-height:360px;overflow:auto}.scroll{overflow:auto}
+      </style><header><svg viewBox="0 0 32 38" fill="none" aria-hidden="true"><path d="M16 2 29 8v11c0 8-7 14-13 17C10 33 3 27 3 19V8Z" stroke="currentColor" stroke-width="2"/><path d="m9 19 5 5 10-12" stroke="currentColor" stroke-width="2"/></svg><h2>Security Assessments</h2></header>
+      <p>Inspect this machine or your mesh. Review firewall, SSH, disk protection, and listening services with concrete remediation.</p>
+      <nav><button data-action="machine">This machine</button><button data-action="fleet">Mesh fleet</button><button data-action="plugins">Plugin audit</button><button data-action="harden">Hardening plan</button></nav>
+      <nav style="margin-top:10px"><input id="target" aria-label="Machine name" placeholder="Optional mesh machine name"><button id="selected">Audit selected</button></nav>
+      <nav style="margin-top:10px"><input id="website" type="url" aria-label="Authorized HTTPS website" placeholder="https://your-site.example"><button id="probe">Check website</button></nav>
+      <nav style="margin-top:10px"><input id="source" aria-label="Source directory" placeholder="Source directory"><button id="scan">Scan source</button><button id="permissions">Repair local SSH permissions</button></nav>
+      <nav style="margin-top:10px"><select id="platform" aria-label="Device platform"><option value="ios">iPhone</option><option value="ipados">iPad</option><option value="android">Android</option><option value="chromeos">Chromebook</option><option value="chromeos-flex">ChromeOS Flex</option><option value="windows">Windows</option></select><input id="device" aria-label="Device label" placeholder="Device label (no passwords)"><button id="review-device">Review device</button></nav>
+      <section id="device-review" hidden><p>Manual device review — answers are your observations, not an automatic scan. Unknown checks remain unverified. Never enter passwords or recovery keys.</p><div id="device-checks"></div><button id="evaluate-device">Evaluate review</button></section>
+      <nav style="margin-top:10px"><input id="android-serial" aria-label="Already authorized Android serial" placeholder="Already authorized Android serial"><button id="android-check">Read Android properties</button></nav>
+      <div id="state" role="status">Not audited</div><div class="scroll"><table hidden><thead><tr><th>Check / machine</th><th>State</th><th>Remediation / coverage</th></tr></thead><tbody></tbody></table></div><pre id="details"></pre>`;
+    root.querySelectorAll('[data-action]').forEach(button => button.addEventListener('click', () => this.execute(button.dataset.action)));
+    root.querySelector('#selected').addEventListener('click', () => {
+      const target = root.querySelector('#target').value.trim();
+      if (!target) { root.querySelector('#state').textContent = 'Enter a discovered machine name'; return; }
+      this.execute('fleet', ['--target', target]);
+    });
+    root.querySelector('#probe').addEventListener('click', () => {
+      const website = root.querySelector('#website').value.trim();
+      try {
+        const url = new URL(website);
+        if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash) throw new Error();
+      } catch { root.querySelector('#state').textContent = 'Enter an authorized HTTPS URL without credentials or query'; return; }
+      this.execute('probe', ['--url', website]);
+    });
+    root.querySelector('#scan').addEventListener('click', () => {
+      const source = root.querySelector('#source').value.trim();
+      if (!source) { root.querySelector('#state').textContent = 'Enter a source directory'; return; }
+      this.execute('scan', [source]);
+    });
+    root.querySelector('#permissions').addEventListener('click', () => this.execute('machine', ['--apply-permissions']));
+    const resetReview = () => { root.querySelector('#device-review').hidden = true; root.querySelector('#device-checks').replaceChildren(); };
+    root.querySelector('#platform').addEventListener('change', resetReview);
+    root.querySelector('#device').addEventListener('input', resetReview);
+    const identity = () => ['--platform', root.querySelector('#platform').value, '--device', root.querySelector('#device').value.trim()];
+    root.querySelector('#review-device').addEventListener('click', () => this.execute('device', identity()));
+    root.querySelector('#evaluate-device').addEventListener('click', () => {
+      const observations = {};
+      root.querySelectorAll('#device-checks select').forEach(select => { if (select.dataset.observedAt) observations[select.dataset.check] = { status: select.value, observedAt: select.dataset.observedAt }; });
+      this.execute('device', [...identity(), '--answers-json', JSON.stringify(observations)]);
+    });
+    root.querySelector('#android-check').addEventListener('click', () => this.execute('android', ['--serial', root.querySelector('#android-serial').value.trim()]));
+  }
+  async execute(action, args = []) {
+    const root = this.shadowRoot;
+    const state = root.querySelector('#state');
+    const details = root.querySelector('#details');
+    root.querySelectorAll('button,input,select').forEach(button => { button.disabled = true; });
+    state.textContent = 'Checking…';
+    details.textContent = '';
+    root.querySelector('tbody').replaceChildren();
+    root.querySelector('table').hidden = true;
+    try {
+      if (!this.host?.run) throw new Error('Security runtime is unavailable');
+      let response;
+      try { response = await this.host.run(action, [...args, '--json']); }
+      catch (error) {
+        try { response = JSON.parse(error.message); } catch { throw error; }
+      }
+      const report = typeof response === 'string' ? JSON.parse(response) : typeof response?.output === 'string' ? JSON.parse(response.output) : response;
+      if (!report || typeof report !== 'object') throw new Error('No audit report returned');
+      if (report.status === 'failed') throw new Error(report.error);
+      if (report.schema === 'security-device/v1' && !args.includes('--answers-json')) {
+        const form = root.querySelector('#device-checks'); form.replaceChildren();
+        for (const check of report.checks) {
+          const label = document.createElement('label'); label.style.display = 'block';
+          const title = document.createElement('p'); title.textContent = `${check.title}: ${check.remediation}`;
+          const select = document.createElement('select'); select.dataset.check = check.id; select.setAttribute('aria-label', check.title);
+          for (const [value, text] of [['unknown', 'Not checked'], ['secure', 'Reviewed — protection confirmed'], ['needs-attention', 'Needs attention']]) { const option = document.createElement('option'); option.value = value; option.textContent = text; select.append(option); }
+          select.addEventListener('change', () => { select.dataset.observedAt = new Date().toISOString(); });
+          label.append(title, select); form.append(label);
+        }
+        root.querySelector('#device-review').hidden = false;
+      }
+      state.textContent = `${report.status || (report.total_findings ? 'Findings require review' : 'Audit returned')} · ${report.timestamp || 'No observation timestamp supplied'}`;
+      const rows = report.checks?.map(check => [check.id, check.state, check.remediation || check.reason || 'Observed']) || report.machines?.map(machine => [machine.hostname, machine.report?.status || machine.state, machine.reason || `${machine.report.coverage.observed}/${machine.report.coverage.total} checks observed`]) || [];
+      if (rows.length) {
+        root.querySelector('table').hidden = false;
+        for (const row of rows) {
+          const tr = document.createElement('tr');
+          row.forEach(value => { const td = document.createElement('td'); td.textContent = value; tr.append(td); });
+          root.querySelector('tbody').append(tr);
+        }
+      }
+      details.textContent = JSON.stringify(report, null, 2);
+    } catch (error) { state.textContent = 'Audit unavailable'; details.textContent = error.message; }
+    finally { root.querySelectorAll('button,input,select').forEach(button => { button.disabled = false; }); }
+  }
+}
+if (!customElements.get('tr-security-card')) customElements.define('tr-security-card', SecuritySecurityCard);

package/scaffold/.agent/skills/total-recall/plugins/security/ui/panel.js

@@ -0,0 +1,98 @@
+export class SecuritySecurityCard extends HTMLElement {
+  connectedCallback() {
+    if (this.shadowRoot) return;
+    const root = this.attachShadow({ mode: 'open' });
+    root.innerHTML = `<style>
+      :host{display:block;color:#edf3fa;background:#16222e;font:14px system-ui;border-radius:12px;padding:18px}header{display:flex;align-items:center;gap:12px}svg{width:32px;height:38px;color:#73d6bf}h2{margin:0;font-size:20px}p{color:#bbcad6;line-height:1.5}nav{display:flex;gap:8px;flex-wrap:wrap}button,input,select{min-height:44px;border:1px solid #71928e;border-radius:6px;padding:8px 12px;background:#213644;color:inherit}button{cursor:pointer}button:disabled{opacity:.5}input{min-width:0;flex:1}#state{margin:14px 0;color:#73d6bf}table{width:100%;border-collapse:collapse}td,th{padding:10px 6px;text-align:left;border-bottom:1px solid #3a4e5c;vertical-align:top}td:last-child{line-height:1.5}pre{white-space:pre-wrap;overflow-wrap:anywhere;max-height:360px;overflow:auto}.scroll{overflow:auto}
+      </style><header><svg viewBox="0 0 32 38" fill="none" aria-hidden="true"><path d="M16 2 29 8v11c0 8-7 14-13 17C10 33 3 27 3 19V8Z" stroke="currentColor" stroke-width="2"/><path d="m9 19 5 5 10-12" stroke="currentColor" stroke-width="2"/></svg><h2>Security Assessments</h2></header>
+      <p>Inspect this machine or your mesh. Review firewall, SSH, disk protection, and listening services with concrete remediation.</p>
+      <nav><button data-action="machine">This machine</button><button data-action="fleet">Mesh fleet</button><button data-action="plugins">Plugin audit</button><button data-action="harden">Hardening plan</button></nav>
+      <nav style="margin-top:10px"><input id="target" aria-label="Machine name" placeholder="Optional mesh machine name"><button id="selected">Audit selected</button></nav>
+      <nav style="margin-top:10px"><input id="website" type="url" aria-label="Authorized HTTPS website" placeholder="https://your-site.example"><button id="probe">Check website</button></nav>
+      <nav style="margin-top:10px"><input id="source" aria-label="Source directory" placeholder="Source directory"><button id="scan">Scan source</button><button id="permissions">Repair local SSH permissions</button></nav>
+      <nav style="margin-top:10px"><select id="platform" aria-label="Device platform"><option value="ios">iPhone</option><option value="ipados">iPad</option><option value="android">Android</option><option value="chromeos">Chromebook</option><option value="chromeos-flex">ChromeOS Flex</option><option value="windows">Windows</option></select><input id="device" aria-label="Device label" placeholder="Device label (no passwords)"><button id="review-device">Review device</button></nav>
+      <section id="device-review" hidden><p>Manual device review — answers are your observations, not an automatic scan. Unknown checks remain unverified. Never enter passwords or recovery keys.</p><div id="device-checks"></div><button id="evaluate-device">Evaluate review</button></section>
+      <nav style="margin-top:10px"><input id="android-serial" aria-label="Already authorized Android serial" placeholder="Already authorized Android serial"><button id="android-check">Read Android properties</button></nav>
+      <div id="state" role="status">Not audited</div><div class="scroll"><table hidden><thead><tr><th>Check / machine</th><th>State</th><th>Remediation / coverage</th></tr></thead><tbody></tbody></table></div><pre id="details"></pre>`;
+    root.querySelectorAll('[data-action]').forEach(button => button.addEventListener('click', () => this.execute(button.dataset.action)));
+    root.querySelector('#selected').addEventListener('click', () => {
+      const target = root.querySelector('#target').value.trim();
+      if (!target) { root.querySelector('#state').textContent = 'Enter a discovered machine name'; return; }
+      this.execute('fleet', ['--target', target]);
+    });
+    root.querySelector('#probe').addEventListener('click', () => {
+      const website = root.querySelector('#website').value.trim();
+      try {
+        const url = new URL(website);
+        if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash) throw new Error();
+      } catch { root.querySelector('#state').textContent = 'Enter an authorized HTTPS URL without credentials or query'; return; }
+      this.execute('probe', ['--url', website]);
+    });
+    root.querySelector('#scan').addEventListener('click', () => {
+      const source = root.querySelector('#source').value.trim();
+      if (!source) { root.querySelector('#state').textContent = 'Enter a source directory'; return; }
+      this.execute('scan', [source]);
+    });
+    root.querySelector('#permissions').addEventListener('click', () => this.execute('machine', ['--apply-permissions']));
+    const resetReview = () => { root.querySelector('#device-review').hidden = true; root.querySelector('#device-checks').replaceChildren(); };
+    root.querySelector('#platform').addEventListener('change', resetReview);
+    root.querySelector('#device').addEventListener('input', resetReview);
+    const identity = () => ['--platform', root.querySelector('#platform').value, '--device', root.querySelector('#device').value.trim()];
+    root.querySelector('#review-device').addEventListener('click', () => this.execute('device', identity()));
+    root.querySelector('#evaluate-device').addEventListener('click', () => {
+      const observations = {};
+      root.querySelectorAll('#device-checks select').forEach(select => { if (select.dataset.observedAt) observations[select.dataset.check] = { status: select.value, observedAt: select.dataset.observedAt }; });
+      this.execute('device', [...identity(), '--answers-json', JSON.stringify(observations)]);
+    });
+    root.querySelector('#android-check').addEventListener('click', () => this.execute('android', ['--serial', root.querySelector('#android-serial').value.trim()]));
+  }
+  async execute(action, args = []) {
+    const root = this.shadowRoot;
+    const state = root.querySelector('#state');
+    const details = root.querySelector('#details');
+    root.querySelectorAll('button,input,select').forEach(button => { button.disabled = true; });
+    state.textContent = 'Checking…';
+    details.textContent = '';
+    root.querySelector('tbody').replaceChildren();
+    root.querySelector('table').hidden = true;
+    try {
+      if (!this.host?.run) throw new Error('Security runtime is unavailable');
+      let response;
+      try { response = await this.host.run(action, [...args, '--json']); }
+      catch (error) {
+        try { response = JSON.parse(error.message); } catch { throw error; }
+      }
+      const report = typeof response === 'string' ? JSON.parse(response) : typeof response?.output === 'string' ? JSON.parse(response.output) : response;
+      if (!report || typeof report !== 'object') throw new Error('No audit report returned');
+      if (report.status === 'failed') throw new Error(report.error);
+      if (report.schema === 'security-device/v1' && !args.includes('--answers-json')) {
+        const form = root.querySelector('#device-checks'); form.replaceChildren();
+        for (const check of report.checks) {
+          const label = document.createElement('label'); label.style.display = 'block';
+          const title = document.createElement('p'); title.textContent = `${check.title}: ${check.remediation}`;
+          const select = document.createElement('select'); select.dataset.check = check.id; select.setAttribute('aria-label', check.title);
+          for (const [value, text] of [['unknown', 'Not checked'], ['secure', 'Reviewed — protection confirmed'], ['needs-attention', 'Needs attention']]) { const option = document.createElement('option'); option.value = value; option.textContent = text; select.append(option); }
+          select.addEventListener('change', () => { select.dataset.observedAt = new Date().toISOString(); });
+          label.append(title, select); form.append(label);
+        }
+        root.querySelector('#device-review').hidden = false;
+      }
+      state.textContent = `${report.status || (report.total_findings ? 'Findings require review' : 'Audit returned')} · ${report.timestamp || 'No observation timestamp supplied'}`;
+      const rows = report.checks?.map(check => [check.id, check.state, check.remediation || check.reason || 'Observed']) || report.machines?.map(machine => [machine.hostname, machine.report?.status || machine.state, machine.reason || `${machine.report.coverage.observed}/${machine.report.coverage.total} checks observed`]) || [];
+      if (rows.length) {
+        root.querySelector('table').hidden = false;
+        for (const row of rows) {
+          const tr = document.createElement('tr');
+          row.forEach(value => { const td = document.createElement('td'); td.textContent = value; tr.append(td); });
+          root.querySelector('tbody').append(tr);
+        }
+      }
+      details.textContent = JSON.stringify(report, null, 2);
+    } catch (error) { state.textContent = 'Audit unavailable'; details.textContent = error.message; }
+    finally { root.querySelectorAll('button,input,select').forEach(button => { button.disabled = false; }); }
+  }
+}
+if (!customElements.get('tr-security-card')) customElements.define('tr-security-card', SecuritySecurityCard);
+
+class SecurityPanel extends SecuritySecurityCard {}
+if (!customElements.get('security-panel')) customElements.define('security-panel', SecurityPanel);

package/scaffold/.agent/skills/total-recall/references/auth.md

@@ -2,7 +2,7 @@
 
 Auth is the credential owner and is shipped in Total Recall scaffold. Its source repository owns storage, encryption, provider catalog/account probes, rotation, rekey, exports, sync, CLI, API and UI. The generic runtime loader requests manifest-declared exports; core must never retain a second secret implementation. Missing or invalid auth fails. Secret operations must never fall through to a core handler or silently switch stores.
 
-Discover `total-recall auth --help` and `total-recall auth secret --help`. The compatibility command name `total-recall secret` routes to auth only; it is not another store. Use `auth secret set KEY --stdin` for values, never argv, chat, logs or vault content. `auth secret list` and `catalog` expose metadata. Avoid `get` in a tool transcript; consumers resolve through the auth runtime in-process. Auth API lives under `/api/plugins/auth/secrets`; any retained legacy HTTP route is implemented by auth, never core.
+Discover `total-recall auth --help` and `total-recall auth secret --help`. The auth namespace is the only credential command path. Use `auth secret set KEY --stdin` for values, never argv, chat, logs or vault content. `auth secret list` and `catalog` expose metadata. Avoid `get` in a tool transcript; consumers resolve through the auth runtime in-process. Auth API lives under `/api/plugins/auth/secrets`; any retained legacy HTTP route is implemented by auth, never core.
 
 Select the store explicitly with the supported brain/store configuration. Existing carrier paths and encrypted data are preserved; no migration may overwrite credentials. No implicit merging of project/global stores or environment credential fallback. Auth alone manages its unlock carriers. Failed unlock/decryption must propagate; never report the store empty after failure. Rekey changes the master carrier, not provider keys: read the current rekey CLI and runbook, update every selected carrier, verify fresh-shell reads and retired-password rejection without exposing either password.
 

package/src/cli/backup.mjs

@@ -17,6 +17,7 @@
  */
 
 import { spawnSync } from 'node:child_process';
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -64,8 +65,22 @@ function parseArgs(args) {
   return opts;
 }
 
+/**
+ * The backup repo's git directory lives OUTSIDE the project tree, under
+ * ~/.agent/brain-backups. A `.git` inside `<project>/.agent/skills/total-recall`
+ * makes the project repo see an embedded repository: `git add -A` records it as a
+ * gitlink (mode 160000) with no .gitmodules, which cannot be cloned back.
+ */
+export function brainGitDir(skillDir) {
+  const abs = path.resolve(skillDir);
+  const owner = path.basename(path.resolve(abs, '..', '..', '..')) || 'brain';
+  const tag = crypto.createHash('sha1').update(abs).digest('hex').slice(0, 8);
+  return path.join(os.homedir(), '.agent', 'brain-backups', `${owner}-${tag}.git`);
+}
+
 function git(cwd, ...gitArgs) {
-  const result = spawnSync('git', gitArgs, { cwd, stdio: 'pipe' });
+  const env = { ...process.env, GIT_DIR: brainGitDir(cwd), GIT_WORK_TREE: path.resolve(cwd) };
+  const result = spawnSync('git', gitArgs, { cwd, env, stdio: 'pipe' });
   return {
     ok: result.status === 0,
     stdout: result.stdout?.toString().trim() || '',
@@ -73,6 +88,56 @@ function git(cwd, ...gitArgs) {
   };
 }
 
+/**
+ * Move a legacy in-tree `<brain>/.git` to the external git dir, and keep the
+ * enclosing project repo from absorbing the brain directory. Idempotent.
+ */
+export function adoptExternalGitDir(skillDir) {
+  const inTree = path.join(skillDir, '.git');
+  const external = brainGitDir(skillDir);
+  let moved = false;
+  if (fs.existsSync(inTree) && fs.statSync(inTree).isDirectory() && !fs.existsSync(external)) {
+    fs.mkdirSync(path.dirname(external), { recursive: true });
+    try {
+      fs.renameSync(inTree, external);
+    } catch {
+      fs.cpSync(inTree, external, { recursive: true });
+      fs.rmSync(inTree, { recursive: true, force: true });
+    }
+    spawnSync('git', ['--git-dir', external, 'config', 'core.worktree', path.resolve(skillDir)], { stdio: 'pipe' });
+    moved = true;
+  }
+  if (fs.existsSync(external) && !fs.existsSync(inTree)) excludeFromParentRepo(skillDir);
+  return moved;
+}
+
+/** Add the brain dir to the enclosing repo's local exclude unless that repo tracks it on purpose. */
+function excludeFromParentRepo(skillDir) {
+  try {
+    const top = spawnSync('git', ['-C', skillDir, 'rev-parse', '--show-toplevel'], { stdio: 'pipe' });
+    if (top.status !== 0) return;
+    const root = top.stdout.toString().trim();
+    const rel = path.relative(fs.realpathSync(root), fs.realpathSync(skillDir)).split(path.sep).join('/');
+    if (!rel || rel.startsWith('..')) return;
+    const tracked = spawnSync('git', ['-C', root, 'ls-files', '-s', '--', rel], { stdio: 'pipe' }).stdout.toString().trim();
+    if (/^160000 /.test(tracked) && !tracked.includes('\n')) {
+      // A stale gitlink (embedded repo with no .gitmodules) cannot be cloned back: unstage it.
+      spawnSync('git', ['-C', root, 'rm', '--cached', '-f', '-q', '--', rel], { stdio: 'pipe' });
+    } else if (tracked) {
+      return; // the project repo versions its brain files itself
+    }
+    const excludePath = path.join(root, '.git', 'info', 'exclude');
+    try {
+      const entry = `/${rel}/`;
+      const current = fs.existsSync(excludePath) ? fs.readFileSync(excludePath, 'utf8') : '';
+      if (!current.split('\n').includes(entry)) {
+        fs.mkdirSync(path.dirname(excludePath), { recursive: true });
+        fs.appendFileSync(excludePath, `${current && !current.endsWith('\n') ? '\n' : ''}${entry}\n`);
+      }
+    } catch { /* parent exclude is best effort */ }
+  } catch { /* best effort: never fail a backup over the parent's exclude file */ }
+}
+
 function defaultOutput(encrypt) {
   const stamp = new Date().toISOString().replace(/[:.]/g, '-');
   const suffix = encrypt ? '.tar.gz.gpg' : '.tar.gz';
@@ -169,8 +234,10 @@ async function pushGitBackup(remote, layer = 'auto') {
   // rule are corrected on their next backup.
   ensureBrainGitignore(SKILL_DIR);
 
-  // Initialise the skill folder as a git repo if needed
-  const gitDir = path.join(SKILL_DIR, '.git');
+  // Initialise the skill folder as a git repo if needed. The git dir lives outside
+  // the project tree; a legacy in-tree .git is moved there first.
+  adoptExternalGitDir(SKILL_DIR);
+  const gitDir = brainGitDir(SKILL_DIR);
   if (!fs.existsSync(gitDir)) {
     console.error(`  🔧 Initialising git repo in ${SKILL_DIR}`);
     const init = git(SKILL_DIR, 'init', '-b', 'main');
@@ -178,6 +245,7 @@ async function pushGitBackup(remote, layer = 'auto') {
       git(SKILL_DIR, 'init');
       git(SKILL_DIR, 'checkout', '-b', 'main');
     }
+    excludeFromParentRepo(SKILL_DIR);
   }
 
   // Resolve the remote: if the argument is an existing remote name, use its URL.