sinapse-ai 1.20.0 → 1.21.0

package/docs/framework/source-tree.md

@@ -752,8 +752,7 @@ outputs/                               # Runtime outputs (gitignored)
 │   ├── engine/                        # Core WIS engines
 │   │   ├── confidence-scorer.js       # Pattern confidence scoring
 │   │   ├── output-formatter.js        # Output formatting
-│   │   ├── suggestion-engine.js       # Intelligent suggestions
-│   │   └── wave-analyzer.js           # Wave pattern analysis
+│   │   └── suggestion-engine.js       # Intelligent suggestions
 │   ├── learning/                      # Machine learning components
 │   │   ├── capture-hook.js            # Pattern capture hooks
 │   │   ├── index.js                   # Learning module entry

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sinapse-ai",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "SINAPSE AI: Framework de orquestracao de IA — 17 squads, 172 agentes especializados",
   "bin": {
     "sinapse": "bin/sinapse.js",
@@ -86,6 +86,7 @@
     "test:coverage": "jest --coverage",
     "test:health-check": "jest tests/health-check",
     "eval": "node scripts/eval-runner.js",
+    "eval:e2e": "node scripts/eval-e2e.js",
     "validate:evals": "node scripts/validate-evals.js",
     "validate:schemas": "node scripts/validate-schemas.js",
     "lint": "eslint . --cache --cache-location .eslintcache",
@@ -97,6 +98,7 @@
     "validate:article-vii": "node scripts/validate-article-vii.js",
     "validate:article-viii": "node scripts/validate-article-viii.js",
     "validate:article-xi": "node scripts/validate-article-xi.js",
+    "validate:article-iv": "node scripts/validate-article-iv.js",
     "reconcile:squads": "node scripts/reconcile-squad-manifests.js",
     "apply:persona-disclaimer": "node scripts/apply-persona-disclaimer.js",
     "validate:manifest": "node scripts/validate-manifest.js",

package/packages/installer/src/config/configure-environment.js

@@ -23,6 +23,7 @@ const {
   sanitizeInput,
 } = require('./validation/config-validator');
 const { getMergeStrategy, hasMergeStrategy } = require('../merger/index.js');
+const { atomicWriteFileSync } = require('../utils/atomic-write');
 
 /**
  * Configure environment files (.env and core-config.yaml)
@@ -110,7 +111,8 @@ async function configureEnvironment(options = {}) {
       const merger = getMergeStrategy(envPath);
       const mergeResult = await merger.merge(existingContent, envContent);
 
-      await fs.writeFile(envPath, mergeResult.content, { encoding: 'utf8' });
+      // Atomic (tmp+rename): .env carries user secrets — never leave it torn
+      atomicWriteFileSync(envPath, mergeResult.content, 'utf8');
       results.envCreated = true;
 
       console.log('✅ Merged .env file');
@@ -119,8 +121,8 @@ async function configureEnvironment(options = {}) {
         console.log(`   ⚠️  Suggestions: ${mergeResult.stats.conflicts} (see comments in file)`);
       }
     } else {
-      // Create new or overwrite
-      await fs.writeFile(envPath, envContent, { encoding: 'utf8' });
+      // Create new or overwrite — atomic (tmp+rename)
+      atomicWriteFileSync(envPath, envContent, 'utf8');
       results.envCreated = true;
       console.log('✅ Created .env file');
     }
@@ -133,7 +135,7 @@ async function configureEnvironment(options = {}) {
     // Step 4: Generate and write .env.example
     const envExamplePath = path.join(targetDir, '.env.example');
     const envExampleContent = generateEnvExample();
-    await fs.writeFile(envExamplePath, envExampleContent, { encoding: 'utf8' });
+    atomicWriteFileSync(envExamplePath, envExampleContent, 'utf8');
     results.envExampleCreated = true;
     console.log('✅ Created .env.example file');
 
@@ -187,7 +189,7 @@ async function configureEnvironment(options = {}) {
       throw new Error('Generated core-config.yaml has invalid structure');
     }
 
-    await fs.writeFile(coreConfigPath, coreConfigContent, { encoding: 'utf8' });
+    atomicWriteFileSync(coreConfigPath, coreConfigContent, 'utf8');
     results.coreConfigCreated = true;
     console.log('✅ Created .sinapse-ai/core-config.yaml');
 
@@ -359,7 +361,7 @@ async function updateGitignore(targetDir) {
 
     newContent += '\n';
 
-    await fs.writeFile(gitignorePath, newContent, { encoding: 'utf8' });
+    atomicWriteFileSync(gitignorePath, newContent, 'utf8');
   }
 }
 

package/packages/installer/src/installer/brownfield-upgrader.js

@@ -12,6 +12,7 @@ const yaml = require('js-yaml');
 const semver = require('semver');
 const { hashFile, hashesMatch } = require('./file-hasher');
 const { YamlMerger } = require('../merger/strategies/yaml-merger.js');
+const { atomicWriteFileSync } = require('../utils/atomic-write');
 
 /**
  * Upgrade report structure
@@ -278,8 +279,8 @@ async function applyUpgrade(report, sourceDir, targetDir, options = {}) {
           const merger = new YamlMerger();
           const mergeResult = await merger.merge(sourceContent, targetContent);
 
-          // Write merged content
-          fs.writeFileSync(targetPath, mergeResult.content, 'utf8');
+          // Write merged content — atomic (tmp+rename); backup taken above
+          atomicWriteFileSync(targetPath, mergeResult.content, 'utf8');
 
           // Log conflict warnings
           const conflicts = mergeResult.changes.filter(c => c.type === 'conflict');
@@ -379,7 +380,8 @@ function updateInstalledManifest(targetDir, sourceManifest, sourcePackage) {
 `;
 
   fs.ensureDirSync(path.dirname(installedManifestPath));
-  fs.writeFileSync(installedManifestPath, header + yamlContent, 'utf8');
+  // Atomic (tmp+rename): the installed manifest drives future upgrades
+  atomicWriteFileSync(installedManifestPath, header + yamlContent, 'utf8');
 
   return installedManifestPath;
 }

package/packages/installer/src/installer/file-hasher.js

@@ -62,24 +62,29 @@ function removeBOM(content) {
  * @throws {Error} - If file cannot be read
  */
 function hashFile(filePath) {
-  if (!fs.existsSync(filePath)) {
-    throw new Error(`File not found: ${filePath}`);
-  }
-
-  const stats = fs.statSync(filePath);
-  if (stats.isDirectory()) {
-    throw new Error(`Cannot hash directory: ${filePath}`);
+  // SECURITY [TOCTOU]: single read — the hashed bytes are exactly what was
+  // read, with no exists/stat/read window for a concurrent writer to exploit.
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath);
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new Error(`File not found: ${filePath}`);
+    }
+    if (error.code === 'EISDIR') {
+      throw new Error(`Cannot hash directory: ${filePath}`);
+    }
+    throw error;
   }
 
   let content;
 
   if (isBinaryFile(filePath)) {
     // Binary files: hash raw bytes
-    content = fs.readFileSync(filePath);
+    content = raw;
   } else {
     // Text files: normalize line endings and remove BOM
-    const rawContent = fs.readFileSync(filePath, 'utf8');
-    const withoutBOM = removeBOM(rawContent);
+    const withoutBOM = removeBOM(raw.toString('utf8'));
     const normalized = normalizeLineEndings(withoutBOM);
     content = Buffer.from(normalized, 'utf8');
   }
@@ -96,25 +101,28 @@ function hashFile(filePath) {
  * @throws {Error} - If file cannot be read
  */
 async function hashFileAsync(filePath) {
-  const exists = await fs.pathExists(filePath);
-  if (!exists) {
-    throw new Error(`File not found: ${filePath}`);
-  }
-
-  const stats = await fs.stat(filePath);
-  if (stats.isDirectory()) {
-    throw new Error(`Cannot hash directory: ${filePath}`);
+  // SECURITY [TOCTOU]: single read (see hashFile) — no exists/stat/read window.
+  let raw;
+  try {
+    raw = await fs.readFile(filePath);
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new Error(`File not found: ${filePath}`);
+    }
+    if (error.code === 'EISDIR') {
+      throw new Error(`Cannot hash directory: ${filePath}`);
+    }
+    throw error;
   }
 
   let content;
 
   if (isBinaryFile(filePath)) {
     // Binary files: hash raw bytes
-    content = await fs.readFile(filePath);
+    content = raw;
   } else {
     // Text files: normalize line endings and remove BOM
-    const rawContent = await fs.readFile(filePath, 'utf8');
-    const withoutBOM = removeBOM(rawContent);
+    const withoutBOM = removeBOM(raw.toString('utf8'));
     const normalized = normalizeLineEndings(withoutBOM);
     content = Buffer.from(normalized, 'utf8');
   }

package/packages/installer/src/installer/manifest-signature.js

@@ -285,82 +285,94 @@ function signatureExists(manifestPath) {
  * @param {Object} [options.publicKey] - Override public key (testing only)
  * @returns {Object} { content: Buffer, verified: boolean, error: string|null }
  */
-function loadAndVerifyManifest(manifestPath, options = {}) {
-  const requireSignature = options.requireSignature !== false;
-  const signaturePath = manifestPath + '.minisig';
-
-  // Check manifest exists
-  if (!fs.existsSync(manifestPath)) {
+/**
+ * Open + fstat + read on a SINGLE file descriptor.
+ *
+ * SECURITY [TOCTOU]: size check (DoS guard) and read happen on the same open
+ * fd, so a concurrent writer cannot swap the file between the check and the
+ * use — the buffer verified downstream is exactly the bytes that were sized.
+ *
+ * @param {string} filePath - File to read
+ * @param {number} maxSize - Maximum allowed size in bytes
+ * @param {string} label - Human label used in error messages (e.g. "Manifest file")
+ * @returns {{content: Buffer|null, error: string|null, missing: boolean}}
+ */
+function readFileCapped(filePath, maxSize, label) {
+  let fd;
+  try {
+    fd = fs.openSync(filePath, 'r');
+  } catch (error) {
     return {
       content: null,
-      verified: false,
-      error: 'Manifest file not found',
+      error: `Cannot read ${label.toLowerCase()}: ${error.message}`,
+      missing: error.code === 'ENOENT',
     };
   }
-
-  // SECURITY [DOS-1]: Check manifest file size BEFORE reading into memory
-  // This prevents DoS attacks via oversized manifest files
-  let manifestStat;
   try {
-    manifestStat = fs.statSync(manifestPath);
+    const stat = fs.fstatSync(fd);
+    if (stat.size > maxSize) {
+      return {
+        content: null,
+        error: `${label} exceeds maximum size (${maxSize} bytes)`,
+        missing: false,
+      };
+    }
+    const content = Buffer.alloc(stat.size);
+    fs.readSync(fd, content, 0, stat.size, 0);
+    return { content, error: null, missing: false };
   } catch (error) {
     return {
       content: null,
-      verified: false,
-      error: `Cannot stat manifest file: ${error.message}`,
+      error: `Cannot read ${label.toLowerCase()}: ${error.message}`,
+      missing: false,
     };
+  } finally {
+    fs.closeSync(fd);
   }
+}
 
-  if (manifestStat.size > SignatureLimits.MAX_MANIFEST_SIZE) {
+function loadAndVerifyManifest(manifestPath, options = {}) {
+  const requireSignature = options.requireSignature !== false;
+  const signaturePath = manifestPath + '.minisig';
+
+  // SECURITY [DOS-1] + [TOCTOU]: size is validated on the same fd that is
+  // read, so the verified buffer cannot be swapped after the check.
+  const manifest = readFileCapped(manifestPath, SignatureLimits.MAX_MANIFEST_SIZE, 'Manifest file');
+  if (manifest.content === null) {
     return {
       content: null,
       verified: false,
-      error: `Manifest file exceeds maximum size (${SignatureLimits.MAX_MANIFEST_SIZE} bytes)`,
+      error: manifest.missing ? 'Manifest file not found' : manifest.error,
     };
   }
 
-  // Check signature exists
-  if (!fs.existsSync(signaturePath)) {
-    if (requireSignature) {
+  // SECURITY [DOS-2] + [TOCTOU]: same single-fd pattern for the signature
+  const signature = readFileCapped(signaturePath, SignatureLimits.MAX_SIGNATURE_SIZE, 'Signature file');
+  if (signature.content === null) {
+    if (signature.missing) {
+      if (requireSignature) {
+        return {
+          content: null,
+          verified: false,
+          error: 'Manifest signature file not found (.minisig)',
+        };
+      }
+      // Allow unsigned in dev mode (requireSignature=false)
       return {
-        content: null,
+        content: manifest.content,
         verified: false,
-        error: 'Manifest signature file not found (.minisig)',
+        error: null,
       };
     }
-    // Allow unsigned in dev mode (requireSignature=false)
-    // Size already validated above
-    return {
-      content: fs.readFileSync(manifestPath),
-      verified: false,
-      error: null,
-    };
-  }
-
-  // SECURITY [DOS-2]: Check signature file size BEFORE reading
-  // Signature files should be small (~200 bytes typical)
-  let signatureStat;
-  try {
-    signatureStat = fs.statSync(signaturePath);
-  } catch (error) {
-    return {
-      content: null,
-      verified: false,
-      error: `Cannot stat signature file: ${error.message}`,
-    };
-  }
-
-  if (signatureStat.size > SignatureLimits.MAX_SIGNATURE_SIZE) {
     return {
       content: null,
       verified: false,
-      error: `Signature file exceeds maximum size (${SignatureLimits.MAX_SIGNATURE_SIZE} bytes)`,
+      error: signature.error,
     };
   }
 
-  // Load files - sizes validated above
-  const manifestContent = fs.readFileSync(manifestPath);
-  const signatureContent = fs.readFileSync(signaturePath, 'utf8');
+  const manifestContent = manifest.content;
+  const signatureContent = signature.content.toString('utf8');
 
   // Verify signature BEFORE any parsing
   const verifyResult = verifyManifestSignature(manifestContent, signatureContent, options);

package/packages/installer/src/installer/post-install-validator.js

@@ -456,21 +456,30 @@ class PostInstallValidator {
     // Development mode: signature not required (NOT for production)
     this.log('WARNING: Signature verification disabled - development mode only');
     try {
-      // SECURITY [DOS-3]: Check file size BEFORE reading into memory
-      const manifestStat = fs.statSync(manifestPath);
-      if (manifestStat.size > SecurityLimits.MAX_MANIFEST_SIZE) {
-        this.issues.push({
-          type: IssueType.INVALID_MANIFEST,
-          severity: Severity.CRITICAL,
-          message: 'Manifest file exceeds maximum size',
-          details: `Size: ${manifestStat.size} bytes, Max: ${SecurityLimits.MAX_MANIFEST_SIZE} bytes`,
-          remediation: 'Use a valid manifest file from the official source',
-          relativePath: null,
-        });
-        return null;
-      }
+      // SECURITY [DOS-3] + [TOCTOU]: fstat + read on the same open fd, so the
+      // size check and the parsed bytes refer to the same file version.
+      const fd = fs.openSync(manifestPath, 'r');
+      let content;
+      try {
+        const manifestStat = fs.fstatSync(fd);
+        if (manifestStat.size > SecurityLimits.MAX_MANIFEST_SIZE) {
+          this.issues.push({
+            type: IssueType.INVALID_MANIFEST,
+            severity: Severity.CRITICAL,
+            message: 'Manifest file exceeds maximum size',
+            details: `Size: ${manifestStat.size} bytes, Max: ${SecurityLimits.MAX_MANIFEST_SIZE} bytes`,
+            remediation: 'Use a valid manifest file from the official source',
+            relativePath: null,
+          });
+          return null;
+        }
 
-      const content = fs.readFileSync(manifestPath, 'utf8');
+        const buf = Buffer.alloc(manifestStat.size);
+        fs.readSync(fd, buf, 0, manifestStat.size, 0);
+        content = buf.toString('utf8');
+      } finally {
+        fs.closeSync(fd);
+      }
       return this.parseManifestContent(content);
     } catch (error) {
       this.issues.push({
@@ -1394,9 +1403,7 @@ class PostInstallValidator {
  */
 function formatReport(report, options = {}) {
   const useColors = options.colors !== false;
-  // Note: detailed option is parsed from CLI but detailed view is handled by caller
-  // eslint-disable-next-line no-unused-vars
-  const detailed = options.detailed === true;
+  // Note: options.detailed is parsed from CLI but the detailed view is handled by the caller
 
   const c = {
     reset: useColors ? '\x1b[0m' : '',

package/packages/installer/src/merger/parsers/markdown-section-parser.js

@@ -140,8 +140,9 @@ function parseMarkdownSections(content) {
       result.preamble.push(line);
     } else if (currentSection) {
       currentSection.lines.push(line);
-    } else if (!sinapseSection) {
-      // Content after an SINAPSE section but before next section
+    } else {
+      // Content after an SINAPSE section but before next section (sinapseSection
+      // is always null here — the in-section branch above `continue`s).
       // This shouldn't happen in well-formed files, but handle it
       result.preamble.push(line);
     }

package/packages/installer/src/updater/index.js

@@ -780,11 +780,17 @@ class SINAPSEUpdater {
   /**
    * Log if verbose
    *
+   * Messages may interpolate error text or npm registry responses; control
+   * characters (ANSI escapes, CR) are stripped so external data cannot forge
+   * log lines in the user's terminal (CWE-117).
+   *
    * @param {string} message - Message
    */
   log(message) {
     if (this.options.verbose) {
-      console.log(`[SINAPSEUpdater] ${message}`);
+      // eslint-disable-next-line no-control-regex
+      const sanitized = String(message).replace(/[\x00-\x08\x0B-\x1F\x7F]/g, '');
+      console.log(`[SINAPSEUpdater] ${sanitized}`);
     }
   }
 }

package/packages/installer/src/utils/atomic-write.js

@@ -0,0 +1,35 @@
+/**
+ * Atomic write bridge — Onda B2 (AF-20260703)
+ *
+ * Thin pointer to the canonical tmp+rename util in
+ * `.sinapse-ai/core/synapse/utils/atomic-write.js` (ships in the same npm
+ * package as this workspace). Fail-open: if the canonical util can't be
+ * resolved, fall back to a plain write (the pre-hardening behavior) rather
+ * than breaking the installer.
+ *
+ * @module src/utils/atomic-write
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+let _atomicWriteSync = null;
+try {
+  // packages/installer/src/utils → repo/package root is 4 levels up
+  _atomicWriteSync = require(path.join(
+    __dirname, '..', '..', '..', '..',
+    '.sinapse-ai', 'core', 'synapse', 'utils', 'atomic-write',
+  )).atomicWriteSync;
+} catch { /* fallback below */ }
+
+function atomicWriteFileSync(filePath, data, encoding = 'utf8') {
+  if (_atomicWriteSync) {
+    _atomicWriteSync(filePath, data, encoding);
+  } else {
+    fs.writeFileSync(filePath, data, encoding);
+  }
+}
+
+module.exports = { atomicWriteFileSync };

package/packages/installer/src/wizard/index.js

@@ -13,6 +13,7 @@ const path = require('path');
 const fse = require('fs-extra');
 const { execSync } = require('child_process');
 const { colors } = require('../utils/sinapse-colors');
+const { atomicWriteFileSync } = require('../utils/atomic-write');
 const {
   getLanguageQuestion,
   getLLMQuestion,
@@ -78,7 +79,8 @@ async function writeClaudeSettings(language, projectDir = process.cwd()) {
     const claudeLanguage = LANGUAGE_MAP[language] || language;
     settings.language = claudeLanguage;
 
-    await fse.writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+    // Atomic (tmp+rename): user settings.json must never be torn
+    atomicWriteFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
     return true;
   } catch {
     // Non-blocking: language is a preference, not critical
@@ -366,7 +368,7 @@ async function installGlobalAgents() {
     try {
       const content = buildAgentTemplate(agent.id, agent.squad, homedir);
       const filePath = path.join(agentsDir, `${agent.id}.md`);
-      await fse.writeFile(filePath, content, 'utf8');
+      atomicWriteFileSync(filePath, content, 'utf8');
       count++;
     } catch (err) {
       errors.push(`${agent.id}: ${err.message}`);
@@ -650,7 +652,7 @@ async function runWizard(options = {}) {
                       '# User-Defined Preferred Patterns and Preferences',
                       '# User-Defined Preferred Patterns and Preferences' + activePresetSection,
                     );
-                    await fse.writeFile(techPrefsFile, techPrefsContent, 'utf8');
+                    atomicWriteFileSync(techPrefsFile, techPrefsContent, 'utf8');
                   }
                 }
               }

package/packages/sinapse-install/src/capabilities/chrome-brain.js

@@ -19,6 +19,7 @@ const path = require('path');
 const os = require('os');
 const { execSync } = require('child_process');
 const { detectOS, OS_TYPE } = require('../os-detector');
+const { atomicWriteFileSync } = require('../utils/atomic-write');
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -339,7 +340,8 @@ function readJsonSafe(filePath) {
 function writeJson(filePath, data) {
   const dir = path.dirname(filePath);
   fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+  // Atomic (tmp+rename): these are user config files (settings.json, .mcp.json)
+  atomicWriteFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
 }
 
 /**
@@ -755,7 +757,7 @@ function installChromeBrain(options = {}) {
         if (dryRun) {
           LOG.info(`[DRY-RUN] Would create ${filePath}`);
         } else {
-          fs.writeFileSync(filePath, content, 'utf8');
+          atomicWriteFileSync(filePath, content, 'utf8');
           // Make executable on Unix
           if (osInfo.type !== OS_TYPE.WINDOWS) {
             fs.chmodSync(filePath, 0o755);
@@ -848,7 +850,7 @@ function installChromeBrain(options = {}) {
           LOG.info(`[DRY-RUN] Would create ${file.label}`);
         } else {
           fs.mkdirSync(path.dirname(file.path), { recursive: true });
-          fs.writeFileSync(file.path, file.content, 'utf8');
+          atomicWriteFileSync(file.path, file.content, 'utf8');
           LOG.ok(file.label);
         }
       } catch (err) {

package/packages/sinapse-install/src/installer.js

@@ -23,6 +23,7 @@ const { intro, outro, select, confirm, note, isCancel, cancel } = require('@clac
 const { execa } = require('execa');
 
 const { detectOS, getOSDisplayName } = require('./os-detector');
+const { atomicWriteFileSync } = require('./utils/atomic-write');
 const { checkAllDependencies, displayResults } = require('./dep-checker');
 
 /**
@@ -148,7 +149,8 @@ async function createUserConfigDirect(profile, logger, dryRun) {
 
   const yaml = require('js-yaml');
   const yamlContent = yaml.dump(config, { lineWidth: -1 });
-  await fs.writeFile(userConfigPath, yamlContent, 'utf8');
+  // Atomic (tmp+rename): user config must never be torn
+  atomicWriteFileSync(userConfigPath, yamlContent, 'utf8');
 
   logger.success(`User config created at ${userConfigPath}`);
 }

package/packages/sinapse-install/src/utils/atomic-write.js

@@ -0,0 +1,67 @@
+/**
+ * Atomic write (tmp + rename) — self-contained copy for @sinapse/sinapse-install.
+ *
+ * This package publishes on its own, so it cannot require the canonical util
+ * in `.sinapse-ai/core/synapse/utils/atomic-write.js` (main sinapse-ai
+ * package). Keep the two in sync if the pattern evolves.
+ *
+ * Onda B2 (AF-20260703): a crash or concurrent reader must never see a torn
+ * config file.
+ *
+ * @module src/utils/atomic-write
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const IS_WINDOWS = process.platform === 'win32';
+const TRANSIENT_LOCK_CODES = new Set(['EPERM', 'EBUSY', 'EACCES', 'ENOTEMPTY']);
+
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function retrySync(fn, retries = 3, delayMs = 120) {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return fn();
+    } catch (err) {
+      if (!TRANSIENT_LOCK_CODES.has(err.code) || attempt >= retries) {
+        throw err;
+      }
+      sleepSync(delayMs * (attempt + 1));
+    }
+  }
+}
+
+function atomicWriteFileSync(filePath, data, encoding = 'utf8') {
+  const tmpPath = `${filePath}.tmp.${process.pid}`;
+  try {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(tmpPath, data, encoding);
+    if (IS_WINDOWS) {
+      retrySync(() => {
+        try {
+          fs.unlinkSync(filePath);
+        } catch (err) {
+          if (err.code !== 'ENOENT') {
+            throw err;
+          }
+        }
+      });
+    }
+    retrySync(() => fs.renameSync(tmpPath, filePath));
+  } catch (error) {
+    try {
+      fs.unlinkSync(tmpPath);
+    } catch { /* ignore cleanup errors */ }
+    throw error;
+  }
+}
+
+module.exports = { atomicWriteFileSync };

package/scripts/apply-persona-disclaimer.js

@@ -16,6 +16,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { atomicWriteSync } = require('../.sinapse-ai/core/synapse/utils/atomic-write');
 
 const ROOT = path.resolve(__dirname, '..');
 
@@ -85,7 +86,7 @@ function ensureNotice(filePath, realName) {
     next = notice + '\n\n' + content;
   }
 
-  fs.writeFileSync(filePath, next);
+  atomicWriteSync(filePath, next);
   return { status: 'inserted', filePath };
 }