total-recall-brain 3.30.2 → 3.31.2

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-DGMNZi_1.js"></script>
+    <script type="module" crossorigin src="/assets/index-FOJG4jQh.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-C7_Xpk27.css">
   </head>
   <body>

package/frontend/package.json

@@ -16,7 +16,7 @@
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "react-force-graph-3d": "^1.29.1",
-    "react-router-dom": "^7.15.0",
+    "react-router-dom": "^7.18.4",
     "recharts": "^3.9.2",
     "three": "^0.185.1",
     "three-spritetext": "^1.10.0"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.30.2",
+  "version": "3.31.2",
   "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

@@ -16,7 +16,6 @@ repo_scoped: true
 > **Only agent skill in this package.** Implementation helpers live in `modules/` (not skills).
 > Openwiki ships with the brain at `openwiki/`.
 
-
 Welcome to the master control skill for the **Total Recall Autonomous AI OS**. > [!NOTE]
 > **Total Recall Architecture:**
 > The Total Recall memory kernel runs as a standalone REST service. Agents interact with the memory vault, perform semantic searches, and compile rules directly using lightweight, filesystem-native REST API calls via standard shell `curl` commands.
@@ -71,7 +70,9 @@ Use the **MESH / CONTROL SERVER** section. Node details are entity fields on
 SSSS `mesh_node` documents — never hardcoded hostnames.
 
 ### 5d. When running tests, typechecks, or builds
-See **TESTS**. Heavy runs go to the Mac Mini or the droplet, never the laptop.
+See **TESTS**. The full suite and the quality gates run only on the Mac Mini —
+never on a laptop or the cloud droplet. A single spec file may run on any mesh node. Builds and installs are fine on any machine; build large apps
+on the Mac Mini.
 
 ### 6. When troubleshooting connections, port blocks, or sync errors
 *   **Trigger**: If the REST server is unreachable, ports are blocked, or the upstream sync tool encounters errors.
@@ -553,12 +554,6 @@ that dead-ends back at a manual dashboard step.
 
 ---
 
-<!-- BEGIN INJECTED MEMORY: do not edit by hand; rebuilt by total-recall surface -->
-<!-- @route: tfidf, generated_at: 2026-05-21T03:34:14.837Z -->
-
-<!-- END INJECTED MEMORY -->
-
-
 ---
 
 ## 🕸️ MESH / CONTROL SERVER (`mesh` subcommand)
@@ -602,9 +597,11 @@ npx vitest run <path>       # one spec file
 
 Current baseline (3.30.1): **349 spec files / 2024 tests, ~160 s** on the Mac Mini.
 
-> **Never run the full suite, a full typecheck, or a production build on the
-> laptop.** These go to the Mac Mini or the droplet — local runs cause slowdowns
-> and OOM kills. Sync and run remotely:
+> **The full suite and the quality gates run only on the Mac Mini** — never on a
+> laptop or the cloud droplet; they cause slowdowns and OOM kills. A single spec
+> file may run on any mesh node. Builds
+> and installs are fine anywhere; build large apps on the Mac Mini. Sync and run
+> remotely:
 >
 > ```bash
 > REMOTE=build-host; REMOTE_DIR=code/total-recall   # your own host and path

package/src/cli/config.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import yaml from 'yaml';
 import { resolveBrainDir, parseLayerFlag } from './agent-dir.mjs';
+import { writeFileSecure } from '../core/secure-file.mjs';
 
 // Pre-defined mapping of known settings
 const KEY_MAP = {
@@ -224,7 +225,7 @@ export default async function configCommand(args) {
       if (!fs.existsSync(configDir)) {
         fs.mkdirSync(configDir, { recursive: true });
       }
-      fs.writeFileSync(targetPath, yaml.stringify(targetObj), { encoding: 'utf8', mode: 0o600 });
+      writeFileSecure(targetPath, yaml.stringify(targetObj), { encoding: 'utf8', mode: 0o600 });
 
       console.log(`\n  ✅ Success! Config key "${key}" ${layerLabel} set to: ${JSON.stringify(parsedValue)}`);
       console.log(`  📍 Saved in: ${targetPath}\n`);

package/src/cli/deploy-ui.mjs

@@ -19,6 +19,7 @@ import os from 'node:os';
 import path from 'node:path';
 import bcrypt from 'bcrypt';
 import yaml from 'yaml';
+import { writeFileSecure } from '../core/secure-file.mjs';
 import { BCRYPT_COST } from '../server/auth.mjs';
 
 
@@ -175,7 +176,7 @@ export function startDeployUI(port = 3001) {
               if (opts.cloudRegion) current['cfg-cloud-region'] = opts.cloudRegion;
               if (opts.installGlobal !== undefined) current['installGlobal'] = opts.installGlobal;
               if (opts.projectPaths) current['projectPaths'] = opts.projectPaths;
-              fs.writeFileSync(configFile, JSON.stringify(current, null, 2), { encoding: 'utf8', mode: 0o600 });
+              writeFileSecure(configFile, JSON.stringify(current, null, 2), { encoding: 'utf8', mode: 0o600 });
 
             } catch (e) {
               console.error('Failed to auto-persist install options on disk:', e);
@@ -572,7 +573,7 @@ export function startDeployUI(port = 3001) {
             }
 
             const updated = { ...current, ...data };
-            fs.writeFileSync(configFile, JSON.stringify(updated, null, 2), { encoding: 'utf8', mode: 0o600 });
+            writeFileSecure(configFile, JSON.stringify(updated, null, 2), { encoding: 'utf8', mode: 0o600 });
             syncInstallOptionsFromDisk();
 
             res.writeHead(200, { 'Content-Type': 'application/json' });
@@ -1114,7 +1115,7 @@ export function startDeployUI(port = 3001) {
             }
             current['cfg-github-token'] = token;
             current['backupRepo'] = backupUrl;
-            fs.writeFileSync(configFile, JSON.stringify(current, null, 2), { encoding: 'utf8', mode: 0o600 });
+            writeFileSecure(configFile, JSON.stringify(current, null, 2), { encoding: 'utf8', mode: 0o600 });
 
             log('✅ Encryption keys and tokens written.');
 
@@ -1735,7 +1736,7 @@ console.log("REMOTE_PASS_OK");
       if (_installOptions.dashboardPassword) {
         current['cfg-dashboard-password'] = _installOptions.dashboardPassword;
       }
-      fs.writeFileSync(configFile, JSON.stringify(current, null, 2), { encoding: 'utf8', mode: 0o600 });
+      writeFileSecure(configFile, JSON.stringify(current, null, 2), { encoding: 'utf8', mode: 0o600 });
     } catch (e) {
       console.error('Failed to auto-persist remote install options on disk:', e);
     }

package/src/cli/deploy.mjs

@@ -43,6 +43,7 @@ import yaml from 'yaml';
 import bcrypt from 'bcrypt';
 import crypto from 'node:crypto';
 import { BCRYPT_COST } from '../server/auth.mjs';
+import { writeFileSecure } from '../core/secure-file.mjs';
 
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -407,7 +408,7 @@ function hardenSecurityConfig(dryRun, dashboardPassword = null) {
     log('  🔑 Dashboard credentials left unconfigured. You will set your admin password on first dashboard access.');
   }
 
-  fs.writeFileSync(securityPath, yaml.stringify(config), { encoding: 'utf8', mode: 0o600 });
+  writeFileSecure(securityPath, yaml.stringify(config), { encoding: 'utf8', mode: 0o600 });
   logOk('Security config hardened: HTTPS required, Express bound to localhost, no public health, no legacy local PAT');
 }
 
@@ -1095,7 +1096,7 @@ export default async function deploy(args) {
           if (wizardOpts.dashboardPassword) {
             current['cfg-dashboard-password'] = wizardOpts.dashboardPassword;
           }
-          fs.writeFileSync(configFile, JSON.stringify(current, null, 2), { encoding: 'utf8', mode: 0o600 });
+          writeFileSecure(configFile, JSON.stringify(current, null, 2), { encoding: 'utf8', mode: 0o600 });
         } catch (e) {
           console.error('Failed to auto-persist cloud install options on disk:', e);
         }

package/src/cli/edit.mjs

@@ -0,0 +1,206 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { resolveBrainDir, parseLayerFlag, getBothBrains } from './agent-dir.mjs';
+import { writeNodeValidatedAsync } from '../core/validated-write.mjs';
+import { isSafeVaultName } from '../core/vault.mjs';
+
+const PRIORITIES = ['absolute', 'high', 'normal', 'low'];
+const MODALITIES = ['must', 'must_not', 'should', 'should_not', 'descriptive', 'preference'];
+const STATUSES = ['active', 'archived', 'deprecated'];
+
+function printHelp() {
+  console.log(`
+  total-recall edit — Change an existing memory node in place (same slug)
+
+  Usage: total-recall edit <slug> ["<new content>"] [options]
+
+    Options:
+    --title <text>            Replace the title
+    --importance, -i <1-5>    Replace the importance
+    --priority, -p <level>    absolute | high | normal | low
+    --modality, -m <type>     must | must_not | should | should_not | descriptive | preference
+    --tags, -t <list>         Replace the tags (comma-separated)
+    --status <status>         active | archived | deprecated
+    --global                  Edit the node in the global brain
+    --project                 Edit the node in the project brain
+    --no-compile              Skip auto-recompilation after the edit
+    --help, -h                Show this help
+
+  Pass "-" as the content to read the new body from stdin. Omit the content to
+  keep the body and change only the options given.
+
+  If neither --global nor --project is specified, the node is looked up in the
+  project brain first (if one exists), then in the global brain.
+
+  Examples:
+    npx total-recall edit anti-patterns-7a7fb6a5 "Never run tests on the MacBook."
+    npx total-recall edit my-rule --priority absolute --modality must --global
+    cat new-body.md | npx total-recall edit my-fact -
+`);
+}
+
+/** Path of `<slug>.md` inside any category directory of `vaultDir`, or null. */
+export function findNodeFile(slug, vaultDir) {
+  if (!isSafeVaultName(slug) || !fs.existsSync(vaultDir)) return null;
+  for (const entry of fs.readdirSync(vaultDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+    const filePath = path.join(vaultDir, entry.name, `${slug}.md`);
+    if (fs.existsSync(filePath)) return filePath;
+  }
+  return null;
+}
+
+/**
+ * Parse edit arguments into { slug, body, changes, noCompile }.
+ * Throws with a user-facing message on invalid input.
+ */
+export function parseEditArgs(args) {
+  const result = { slug: null, body: undefined, changes: {}, noCompile: false };
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const next = () => {
+      const value = args[++i];
+      if (value === undefined) throw new Error(`${arg} requires a value.`);
+      return value;
+    };
+    if (arg === '--no-compile') result.noCompile = true;
+    else if (arg === '--title') result.changes.title = next();
+    else if (arg === '--importance' || arg === '-i') {
+      const value = Number(next());
+      if (!Number.isInteger(value) || value < 1 || value > 5) {
+        throw new Error('--importance must be an integer from 1 to 5.');
+      }
+      result.changes.importance = value;
+    } else if (arg === '--priority' || arg === '-p') {
+      const value = next().toLowerCase();
+      if (!PRIORITIES.includes(value)) throw new Error(`--priority must be one of: ${PRIORITIES.join(', ')}.`);
+      result.changes.priority = value;
+    } else if (arg === '--modality' || arg === '-m') {
+      const value = next().toLowerCase();
+      if (!MODALITIES.includes(value)) throw new Error(`--modality must be one of: ${MODALITIES.join(', ')}.`);
+      result.changes.modality = value;
+    } else if (arg === '--tags' || arg === '-t') {
+      result.changes.tags = next().split(',').map((t) => t.trim()).filter(Boolean);
+    } else if (arg === '--status') {
+      const value = next().toLowerCase();
+      if (!STATUSES.includes(value)) throw new Error(`--status must be one of: ${STATUSES.join(', ')}.`);
+      result.changes.status = value;
+    } else if (/^--?[a-z]/i.test(arg)) {
+      throw new Error(`Unknown option: ${arg}`);
+    } else positional.push(arg);
+  }
+  if (positional.length > 2) throw new Error('Quote the new content as a single argument.');
+  [result.slug, result.body] = positional;
+  return result;
+}
+
+/**
+ * Apply an edit to a parsed node. Returns the updated node and the list of
+ * changed field names. `immutable` follows `priority`, as in `remember`.
+ */
+export function applyEdit(node, { body, changes }, now = new Date().toISOString()) {
+  const updated = { ...node };
+  const changed = [];
+  if (body !== undefined && body.trim() !== (node.body || '').trim()) {
+    updated.body = body.trim();
+    changed.push('body');
+  }
+  for (const [key, value] of Object.entries(changes)) {
+    if (JSON.stringify(node[key]) === JSON.stringify(value)) continue;
+    updated[key] = value;
+    changed.push(key);
+  }
+  if (changed.includes('title') && node.description === node.title) {
+    updated.description = updated.title;
+  }
+  if (changed.includes('priority')) {
+    if (updated.priority === 'absolute') updated.immutable = true;
+    else delete updated.immutable;
+  }
+  if (changed.length) updated.updated = now;
+  return { node: updated, changed };
+}
+
+function locate(slug, explicitLayer) {
+  const layers = explicitLayer === 'auto' ? ['project', 'global'] : [explicitLayer];
+  const brains = getBothBrains();
+  for (const layer of layers) {
+    if (layer === 'project' && !brains.project) continue;
+    const vaultDir = path.join(resolveBrainDir(layer), 'memory-vault');
+    const filePath = findNodeFile(slug, vaultDir);
+    if (filePath) return { layer, vaultDir, filePath };
+  }
+  return null;
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+export default async function edit(args) {
+  const { layer: explicitLayer, remainingArgs } = parseLayerFlag(args);
+  if (!remainingArgs.length || remainingArgs.includes('--help') || remainingArgs.includes('-h')) {
+    printHelp();
+    return;
+  }
+
+  let parsed;
+  try {
+    parsed = parseEditArgs(remainingArgs);
+  } catch (err) {
+    console.error(`  ❌ ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (parsed.body === '-') parsed.body = await readStdin();
+  if (parsed.body !== undefined && !parsed.body.trim()) {
+    console.error('  ❌ The new content is empty. Use `total-recall forget` to delete a node.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const found = locate(parsed.slug, explicitLayer);
+  if (!found) {
+    const where = explicitLayer === 'auto' ? 'project or global' : explicitLayer;
+    console.error(`  ❌ Node "${parsed.slug}" not found in the ${where} vault.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const { data, content } = matter(fs.readFileSync(found.filePath, 'utf8'));
+  const { node, changed } = applyEdit({ ...data, body: content.trim() }, parsed);
+  const layerLabel = `[${found.layer}]`;
+  const relPath = path.relative(path.dirname(found.vaultDir), found.filePath);
+
+  if (!changed.length) {
+    console.log(`  ℹ️  Nothing to change in ${layerLabel} ${relPath}.`);
+    return;
+  }
+
+  const result = await writeNodeValidatedAsync(node, found.vaultDir);
+  if (!result.success) {
+    const errors = result.validation?.errors || [result.error || 'unknown validation failure'];
+    console.error(`  ❌ Validation failed: ${errors.join('; ')}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`  ✅ Updated ${layerLabel} ${relPath} (${changed.join(', ')})`);
+
+  if (parsed.noCompile) return;
+  console.log('  ⏳ Recompiling active memory surfaces and indexes in the background...');
+  try {
+    const { spawn } = await import('node:child_process');
+    const child = spawn(process.argv[0], [process.argv[1], 'compile', `--${found.layer}`], {
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.unref();
+    console.log('  ✅ Background compilation started.');
+  } catch (err) {
+    console.warn(`  ⚠️  Node updated, but background recompilation spawn failed: ${err.message}`);
+  }
+}

package/src/cli/help.mjs

@@ -146,7 +146,7 @@ function printGeneralHelp() {
     npx total-recall help architecture
 
   \x1b[1mCore Memory Operations:\x1b[0m
-    \x1b[33mremember\x1b[0m, \x1b[33mrecall\x1b[0m, \x1b[33mforget\x1b[0m, \x1b[33mbrain\x1b[0m, \x1b[33mmap\x1b[0m
+    \x1b[33mremember\x1b[0m, \x1b[33mrecall\x1b[0m, \x1b[33mforget\x1b[0m, \x1b[33medit\x1b[0m, \x1b[33mbrain\x1b[0m, \x1b[33mmap\x1b[0m
 
   \x1b[1mCompilation & System Rules:\x1b[0m
     \x1b[33mcompile\x1b[0m, \x1b[33mrebuild\x1b[0m, \x1b[33mconnect\x1b[0m, \x1b[33mskill\x1b[0m, \x1b[33mimport-rules\x1b[0m

package/src/cli/init.mjs

@@ -31,6 +31,7 @@ import os from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { exec, spawn, spawnSync } from 'node:child_process';
 import { projectSkillsForScope, detectActiveSkillTargets } from './skill-projection.mjs';
+import { writeFileSecure } from '../core/secure-file.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.join(__dirname, '..', '..');
@@ -408,10 +409,10 @@ export default async function init(args) {
       }
 
       if (!config.dashboard.password_hash) {
-        fs.writeFileSync(securityPath, yaml.stringify(config), { encoding: "utf8", mode: 0o600 });
+        writeFileSecure(securityPath, yaml.stringify(config), { encoding: "utf8", mode: 0o600 });
         passwordMessage = "\n  🔑 Dashboard Access: Unconfigured\n     (You will be prompted to set your password upon first browser access)";
       } else {
-        fs.writeFileSync(securityPath, yaml.stringify(config), { encoding: 'utf8', mode: 0o600 });
+        writeFileSecure(securityPath, yaml.stringify(config), { encoding: 'utf8', mode: 0o600 });
         passwordMessage = '\n  🔑 Dashboard credentials preserved (custom password hash already configured)';
       }
     } catch (err) {
@@ -586,7 +587,7 @@ export default async function init(args) {
       current['cfg-health-url'] = 'http://localhost:3000/health';
     }
 
-    fs.writeFileSync(configFile, JSON.stringify(current, null, 2), { encoding: 'utf8', mode: 0o600 });
+    writeFileSecure(configFile, JSON.stringify(current, null, 2), { encoding: 'utf8', mode: 0o600 });
     logOk('UI deploy configuration persisted to wizard-config.json!');
   }
 
@@ -670,7 +671,7 @@ export default async function init(args) {
     fs.mkdirSync(cfgDir, { recursive: true });
     const brainCfg = { url: opts.brain };
     if (opts.token) brainCfg.token = opts.token;
-    fs.writeFileSync(path.join(cfgDir, 'brain.json'), JSON.stringify(brainCfg, null, 2), { mode: 0o600 });
+    writeFileSecure(path.join(cfgDir, 'brain.json'), JSON.stringify(brainCfg, null, 2), { mode: 0o600 });
     logOk(`Registered brain at ${opts.brain}. Run \`npx total-recall sync\` to pull instructions.`);
   } else {
     // Zero-config bootstrap: auto-generate localhost brain.json and valid Developer PAT out-of-the-box
@@ -696,7 +697,7 @@ export default async function init(args) {
         const keyData = issueKey('Default Local Developer Key', { scopes: ['*'] });
         brainCfg.url = brainCfg.url || 'http://localhost:3000';
         brainCfg.token = brainCfg.token || keyData.token;
-        fs.writeFileSync(brainJsonPath, JSON.stringify(brainCfg, null, 2), { mode: 0o600 });
+        writeFileSecure(brainJsonPath, JSON.stringify(brainCfg, null, 2), { mode: 0o600 });
         logOk(`Bootstrap configuration successfully generated and pre-authorized at ${brainCfg.url}`);
       } catch (err) {
         logWarn(`Could not auto-generate bootstrap developer key: ${err.message}`);
@@ -786,7 +787,7 @@ export default async function init(args) {
           current['cfg-dash-url'] = `${tunnelUrl}/`;
           current['cfg-health-url'] = `${tunnelUrl}/health`;
           
-          fs.writeFileSync(configFile, JSON.stringify(current, null, 2), { encoding: 'utf8', mode: 0o600 });
+          writeFileSecure(configFile, JSON.stringify(current, null, 2), { encoding: 'utf8', mode: 0o600 });
           logOk('Registered Quick Tunnel URL in wizard-config.json!');
           dashboardUrl = `${tunnelUrl}/`;
         } else {

package/src/cli/reset-password.mjs

@@ -5,6 +5,7 @@ import bcrypt from 'bcrypt';
 import yaml from 'yaml';
 import { BCRYPT_COST } from '../server/auth.mjs';
 import { brainDir } from '../core/config.mjs';
+import { writeFileSecure } from '../core/secure-file.mjs';
 
 /**
  * Read a password without echoing it, and without it ever becoming an argv
@@ -128,7 +129,7 @@ export default async function resetPassword(args) {
   const isDefault = password === 'totalrecall';
   config.dashboard.force_password_reset = isDefault;
 
-  fs.writeFileSync(securityPath, yaml.stringify(config), { encoding: 'utf8', mode: 0o600 });
+  writeFileSecure(securityPath, yaml.stringify(config), { encoding: 'utf8', mode: 0o600 });
 
   // Never echo the password back. The operator just typed it; repeating it to
   // stdout puts it into scrollback, into any log capturing this command, and

package/src/cli/uninstall.mjs

@@ -30,6 +30,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawnSync, execFileSync } from 'node:child_process';
 import backup from './backup.mjs';
+import { writeFileSecure } from '../core/secure-file.mjs';
 
 // ╔══════════════════════════════════════════════════════════════════════════╗
 // ║  FORBIDDEN FLAGS — These patterns must NEVER be accepted as arguments  ║
@@ -531,7 +532,7 @@ export default async function uninstall(args = []) {
       
       if (Object.keys(secretsObj).length > 0) {
         fs.mkdirSync(agentDir, { recursive: true });
-        fs.writeFileSync(
+        writeFileSecure(
           path.join(agentDir, 'secrets.enc'),
           JSON.stringify(secretsObj, null, 2),
           { encoding: 'utf8', mode: 0o600 }

package/src/core/project-brain.mjs

@@ -19,6 +19,7 @@ import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import YAML from 'yaml';
+import { writeFileSecure } from './secure-file.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '../..');
@@ -162,7 +163,7 @@ export function writeBrainIdentity(brainDir, { name, role = 'project', tags = []
     updated_at: new Date().toISOString(),
     created_at: current.created_at || new Date().toISOString(),
   };
-  fs.writeFileSync(brainJsonPath, JSON.stringify(next, null, 2), { encoding: 'utf8', mode: 0o600 });
+  writeFileSecure(brainJsonPath, JSON.stringify(next, null, 2), { encoding: 'utf8', mode: 0o600 });
   return next;
 }
 

package/src/core/secrets-store.mjs

@@ -13,6 +13,7 @@ import os from 'os';
 import YAML from 'yaml';
 import { encryptSecrets, decryptSecrets, encryptSecretsSync, decryptSecretsSync } from './crypto.mjs';
 import { DEFAULT_KEYCHAIN_SERVICE, readKeychainPassword } from './secrets-keychain.mjs';
+import { writeFileSecure, appendFileSecure } from './secure-file.mjs';
 
 const META_KEY = '__tr_secrets_meta';
 
@@ -170,7 +171,7 @@ export function saveSecretsSync(brainDir, obj) {
   const password = secretsPassword();
   if (!password) throw new Error('TR_SECRETS_PASSWORD or TR_MASTER_PASSWORD is required to write secrets');
   const buf = encryptSecretsSync(obj, password);
-  fs.writeFileSync(filePath, buf, { mode: 0o600 });
+  writeFileSecure(filePath, buf, { mode: 0o600 });
 }
 
 /**
@@ -221,7 +222,7 @@ export async function saveSecrets(brainDir, secrets) {
 
   if (!password) throw new Error('TR_SECRETS_PASSWORD or TR_MASTER_PASSWORD is required to write secrets');
   const buf = await encryptSecrets(secrets, password);
-  fs.writeFileSync(filePath, buf, { mode: 0o600 });
+  writeFileSecure(filePath, buf, { mode: 0o600 });
 }
 
 /**
@@ -314,7 +315,7 @@ function appendAudit(brainDir, event) {
     ...event,
     // never include values
   });
-  fs.appendFileSync(auditPath, line + '\n', { mode: 0o600 });
+  appendFileSecure(auditPath, line + '\n', { mode: 0o600 });
 }
 
 /**
@@ -983,7 +984,7 @@ export function recordUsage(brainDir, event) {
     source: event.source || 'cli',
     key_ref: event.key_ref || null, // secret *name* only, never value
   };
-  fs.appendFileSync(usagePath, JSON.stringify(row) + '\n', { mode: 0o600 });
+  appendFileSecure(usagePath, JSON.stringify(row) + '\n', { mode: 0o600 });
   return row;
 }
 

package/src/core/secure-file.mjs

@@ -0,0 +1,71 @@
+/**
+ * Secure file writes for credential-bearing files.
+ *
+ * `fs.writeFileSync`/`fs.appendFileSync` only apply their `mode` option when the
+ * file is CREATED. Rewriting a file that already exists silently preserves the
+ * old permissions, so a security.yml or secrets.enc that was ever created under
+ * a loose umask (or restored from a backup, or copied by a sync) stays
+ * world-readable forever no matter how many times it is rewritten with
+ * `{ mode: 0o600 }`.
+ *
+ * Observed live: config/security.yml at mode 644 while holding the dashboard
+ * bcrypt password_hash.
+ *
+ * Every writer of a file containing hashes, tokens, or key material must go
+ * through here so the mode is re-asserted on every write, not just the first.
+ */
+
+import fs from 'fs';
+
+export const SECRET_FILE_MODE = 0o600;
+
+/**
+ * Re-assert permissions on an existing file.
+ *
+ * @param {string} filePath
+ * @param {number} [mode]
+ * @returns {boolean} true when the mode was applied
+ */
+export function chmodSecure(filePath, mode = SECRET_FILE_MODE) {
+  try {
+    fs.chmodSync(filePath, mode);
+    return true;
+  } catch {
+    // Best effort: chmod can fail on non-POSIX filesystems.
+    return false;
+  }
+}
+
+function requireSecureMode(filePath, mode) {
+  if (!chmodSecure(filePath, mode)) {
+    throw new Error(`Could not secure file permissions: ${filePath}`);
+  }
+}
+
+/**
+ * writeFileSync that actually enforces `mode` on rewrite.
+ *
+ * @param {string} filePath
+ * @param {string|Buffer} data
+ * @param {object} [options] same as fs.writeFileSync; `mode` defaults to 0o600
+ */
+export function writeFileSecure(filePath, data, options = {}) {
+  const { mode = SECRET_FILE_MODE, ...rest } = options;
+  if (fs.existsSync(filePath)) requireSecureMode(filePath, SECRET_FILE_MODE);
+  fs.writeFileSync(filePath, data, { ...rest, mode });
+  requireSecureMode(filePath, mode);
+}
+
+/**
+ * appendFileSync that actually enforces `mode` on an existing file.
+ *
+ * @param {string} filePath
+ * @param {string|Buffer} data
+ * @param {object} [options] same as fs.appendFileSync; `mode` defaults to 0o600
+ */
+export function appendFileSecure(filePath, data, options = {}) {
+  const { mode = SECRET_FILE_MODE, ...rest } = options;
+  if (fs.existsSync(filePath)) requireSecureMode(filePath, SECRET_FILE_MODE);
+  fs.appendFileSync(filePath, data, { ...rest, mode });
+  requireSecureMode(filePath, mode);
+}

package/src/core/webauthn-store.mjs

@@ -9,6 +9,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { writeFileSecure } from './secure-file.mjs';
 import {
   generateRegistrationOptions,
   verifyRegistrationResponse,
@@ -49,7 +50,7 @@ function loadStore(brainDir) {
 function saveStore(brainDir, store) {
   const filePath = resolveWebAuthnPath(brainDir);
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, JSON.stringify(store, null, 2) + '\n', {
+  writeFileSecure(filePath, JSON.stringify(store, null, 2) + '\n', {
     encoding: 'utf8',
     mode: 0o600,
   });

package/src/server/auth.mjs

@@ -11,6 +11,7 @@ import { findValidKeyByToken, keyHasAnyScope, recordKeyUsage } from './keys.mjs'
 import { logger } from '../core/logger.mjs';
 
 import { agentDir, brainDir, sessionSecret, nodeEnv } from '../core/config.mjs';
+import { writeFileSecure } from '../core/secure-file.mjs';
 
 const BRAIN_DIR = brainDir;
 const CONFIG_FILE = path.join(BRAIN_DIR, 'config', 'security.yml');
@@ -26,7 +27,7 @@ try {
   JWT_SECRET = crypto.randomBytes(32).toString('hex');
   try {
     fs.mkdirSync(path.dirname(JWT_SECRET_PATH), { recursive: true });
-    fs.writeFileSync(JWT_SECRET_PATH, JWT_SECRET, { mode: 0o600 });
+    writeFileSecure(JWT_SECRET_PATH, JWT_SECRET, { mode: 0o600 });
   } catch { /* non-fatal — will regenerate on next restart */ }
 }
 
@@ -450,7 +451,7 @@ export async function changePasswordHandler(req, res) {
   config.dashboard.password_hash = hash;
   config.dashboard.force_password_reset = false;
 
-  fs.writeFileSync(CONFIG_FILE, yaml.stringify(config));
+  writeFileSecure(CONFIG_FILE, yaml.stringify(config), { encoding: 'utf8', mode: 0o600 });
 
   // Dynamically update the backup secrets.enc file to preserve the password hash
   try {