contextos-agents 1.7.0 → 2.0.0-beta.2

package/bin/commands.js

@@ -103,15 +103,14 @@ function formatStatusText(status) {
 const COMMAND_REGISTRY = {
   init: {
     name: 'init',
-    description: 'Install and configure .agents/ in target project',
+    description: 'Compile and govern engineering context across AI coding agents.',
     usage: 'npx contextos-agents init [options]',
     requiresProject: false,
     options: [
       { flag: '--agent <target>', desc: 'Target agent (gemini, claude, cursor, auto)' },
       { flag: '--profile <name>', desc: 'Apply specific profile (mvp, startup, enterprise, etc.)' },
       { flag: '--auto', desc: 'Auto-detect tech stack and recommended profile' },
-      { flag: '--minimal', desc: 'Install only 5 core essential skills' },
-      { flag: '--with-mcp', desc: 'Install with MCP execution server enabled' },
+      { flag: '--minimal', desc: 'Install the 7-skill neutral bootstrap.' },
       { flag: '--force', desc: 'Overwrite existing installation' },
       { flag: '--dry-run', desc: 'Preview installation actions without writing' },
       { flag: '--skip-compile', desc: 'Skip auto-compiling skills after install' },
@@ -149,11 +148,35 @@ const COMMAND_REGISTRY = {
   },
   doctor: {
     name: 'doctor',
-    description: 'Run project diagnostic health check',
-    usage: 'contextos doctor [--json]',
+    description: 'Run project diagnostic health check (Doctor v2)',
+    usage: 'contextos doctor [--fix] [--strict] [--json]',
     requiresProject: false,
     options: [
-      { flag: '--json', desc: 'Output health report in JSON format' },
+      { flag: '--fix', desc: 'Automatically remediate safe diagnostic issues and clean caches' },
+      { flag: '--strict', desc: 'Exit with non-zero code on any warning' },
+      { flag: '--json', desc: 'Output health report in versioned JSON format' },
+    ],
+  },
+  recover: {
+    name: 'recover',
+    description: 'List, rollback, or resume stuck filesystem transactions',
+    usage: 'contextos recover [--list] [--rollback <txId>] [--resume <txId>]',
+    requiresProject: true,
+    options: [
+      { flag: '--list', desc: 'List pending or broken transactions requiring recovery' },
+      { flag: '--rollback <txId>', desc: 'Rollback a broken transaction' },
+      { flag: '--resume <txId>', desc: 'Resume and complete a stuck transaction' },
+    ],
+  },
+  compile: {
+    name: 'compile',
+    description: 'Compile skill manifests into deterministic registry v2 (registry.v2.json)',
+    usage: 'contextos compile [--check] [--sarif] [--json]',
+    requiresProject: true,
+    options: [
+      { flag: '--check', desc: 'Validate manifests without writing to disk' },
+      { flag: '--sarif', desc: 'Output diagnostics in SARIF 2.1.0 format' },
+      { flag: '--json', desc: 'Output result in JSON format' },
     ],
   },
   validate: {
@@ -183,22 +206,39 @@ const COMMAND_REGISTRY = {
   },
   profile: {
     name: 'profile',
-    description: 'Manage project profiles (list, show, apply, remove)',
-    usage: 'contextos profile <list|show|apply|remove> [name]',
+    description: 'Manage project profiles (list, show, explain, apply, remove)',
+    usage: 'contextos profile <list|show|explain|apply|remove> [name] [--scope <pkg>] [--no-export] [--json]',
     requiresProject: true,
-    options: [],
+    options: [
+      { flag: '--scope <path>', desc: 'Scope profile application or removal to specific package' },
+      { flag: '--no-export', desc: 'Skip re-exporting adapter skills after applying profile' },
+      { flag: '--json', desc: 'Output profile information in JSON format' },
+    ],
   },
   resolve: {
     name: 'resolve',
     description: 'Dynamically resolve minimal skills needed for a prompt or files',
-    usage: 'contextos resolve <prompt> [--files <a,b>] [--phase <p>] [--json]',
+    usage: 'contextos resolve <prompt> [--files <a,b>] [--phase <p>] [--explain] [--budget <n>] [--json]',
     requiresProject: true,
     options: [
       { flag: '--files <list>', desc: 'Comma-separated list of touched files' },
       { flag: '--phase <name>', desc: 'Lifecycle phase (Define, Plan, Build, Verify, Review, Ship)' },
+      { flag: '--explain', desc: 'Display evidence scoring and decision breakdown' },
+      { flag: '--budget <tokens>', desc: 'Context token budget limit (default: 8000)' },
       { flag: '--json', desc: 'Output resolution in JSON format' },
     ],
   },
+  explain: {
+    name: 'explain',
+    description: 'Inspect rule catalog, enforcement levels, and automated checkers',
+    usage: 'contextos explain [ruleId|skillId] [--rules] [--checkers] [--json]',
+    requiresProject: true,
+    options: [
+      { flag: '--rules', desc: 'Display all declared rules with enforcement levels' },
+      { flag: '--checkers', desc: 'Display all registered automated enforcement checkers' },
+      { flag: '--json', desc: 'Output rule and enforcement data in JSON format' },
+    ],
+  },
   stats: {
     name: 'stats',
     description: 'Display token context savings report',
@@ -217,11 +257,13 @@ const COMMAND_REGISTRY = {
   },
   detect: {
     name: 'detect',
-    description: 'Auto-detect project tech stack and recommend profile',
-    usage: 'contextos detect [--json]',
+    description: 'Auto-detect project tech stack, workspace evidence graph, and scope',
+    usage: 'contextos detect [--scope <path>] [--explain] [--json]',
     requiresProject: false,
     options: [
-      { flag: '--json', desc: 'Output detection result in JSON format' },
+      { flag: '--scope <path>', desc: 'Scope detection to nearest package of specific file or directory' },
+      { flag: '--explain', desc: 'Display evidence signals, internal dependencies, and stack breakdown' },
+      { flag: '--json', desc: 'Output workspace graph and detection in JSON format' },
     ],
   },
   'install-skill': {
@@ -240,22 +282,17 @@ const COMMAND_REGISTRY = {
     requiresProject: true,
     options: [],
   },
-  'setup-mcp': {
-    name: 'setup-mcp',
-    description: 'Add MCP execution server to an existing .agents/ project',
-    usage: 'contextos setup-mcp [--force]',
+  recover: {
+    name: 'recover',
+    description: 'Recover from interrupted or failed multi-file transactions',
+    usage: 'contextos recover [--status] [--rollback [txId]] [--continue [txId]]',
     requiresProject: true,
     options: [
-      { flag: '--force', desc: 'Overwrite existing .agents/mcp_config.json' },
+      { flag: '--status', desc: 'Inspect pending uncommitted transaction journals' },
+      { flag: '--rollback [txId]', desc: 'Roll back uncommitted or failed transaction' },
+      { flag: '--continue [txId]', desc: 'Attempt to resume and complete prepared transaction' },
     ],
   },
-  'clean-worktrees': {
-    name: 'clean-worktrees',
-    description: 'Clean up lingering .swarm-worktrees and swarm/* branches',
-    usage: 'contextos clean-worktrees',
-    requiresProject: false,
-    options: [],
-  },
 };
 
 /**

package/bin/index.js

@@ -61,10 +61,10 @@ Options:
   --agent <name>      Target AI agent or IDE (gemini, claude, cursor, auto)
   --dry-run           Preview what will be copied without making changes
   --force             Overwrite an existing .agents/ folder
-  --minimal           Install only 5 core skills (lightweight footprint)
+  --minimal           Install only 7 core skills (lightweight footprint)
   --profile <name>    Install a specific profile (mvp, startup, enterprise, frontend, backend)
   --auto              Auto-detect tech stack and apply recommended profile
-  --with-mcp, --mcp   Install with MCP execution server enabled (.agents/mcp/ & mcp_config.json)
+  --with-mcp, --mcp   [DEPRECATED] Use the separate @contextos/mcp package instead
   --skip-compile      Skip running ctx.js export after installation
   --add-skill <ref>   Install a community plugin skill after setup
 
@@ -76,6 +76,7 @@ Commands:
   doctor              Run full project diagnostic health check
   audit               Validate local skills (alias for validate)
   validate            Validate local skills, frontmatter, and sync
+  compile             Compile skill manifests into deterministic registry v2
   profile <subcmd>    Manage profiles (list, apply, show, remove)
   export <target>     Export skills (gemini, claude, cursor, copilot, aider, zed, all)
   resolve <prompt>    Dynamically resolve minimal skills for a prompt or files
@@ -83,7 +84,7 @@ Commands:
   watch               Start continuous file watcher and auto-sync daemon
   detect              Analyze project and display detected tech stack & IDE
   install-skill       Interactive skill installer (or pass <ref> / --from-repo)
-  setup-mcp           Add MCP execution server to an existing .agents/ project
+  setup-mcp           [DEPRECATED] Add MCP execution server to an existing .agents/ project
 
 Profiles:
   mvp                 Fastest shipping, minimalist monolith, excludes microservices & DDD
@@ -103,7 +104,7 @@ Plugin ref formats:
 Examples:
   npx contextos-agents init                     Install .agents/ with auto-detected stack
   npx contextos-agents init --agent auto        Install and configure for detected stack & IDE
-  npx contextos-agents init --minimal           Install only 5 core essential skills
+  npx contextos-agents init --minimal           Install only 7 core essential skills
   npx contextos status                          Show project configuration and lockfile status
   npx contextos doctor                          Run project health check
   npx contextos export gemini                   Compile skills for Gemini
@@ -138,16 +139,95 @@ if (mainCommand === 'status') {
 
 // Detect command
 if (mainCommand === 'detect') {
-  const detection = detectProjectAttributes(process.cwd());
-  if (flags.json) {
-    console.log(JSON.stringify(detection, null, 2));
+  const { WorkspaceGraphBuilder } = require('../.agents/workspace/workspace-graph.js');
+  const scopeIdx = args.indexOf('--scope');
+  const scopeArg = scopeIdx !== -1 && args[scopeIdx + 1] && !args[scopeIdx + 1].startsWith('--')
+    ? args[scopeIdx + 1]
+    : (args.find(a => a.startsWith('--scope=')) || '').split('=')[1];
+  const explain = args.includes('--explain');
+
+  const builder = new WorkspaceGraphBuilder();
+  const graph = builder.build(process.cwd());
+
+  if (scopeArg) {
+    const nearestPkg = builder.findNearestPackage(scopeArg, graph);
+    const evidence = builder.extractPackageEvidence(scopeArg, graph);
+
+    if (flags.json) {
+      console.log(JSON.stringify({
+        scope: scopeArg,
+        nearestPackage: nearestPkg,
+        evidence,
+      }, null, 2));
+    } else {
+      console.log('\n══════════════════════════════════════════');
+      console.log('  ContextOS — Workspace Scoped Detection');
+      console.log('══════════════════════════════════════════\n');
+      console.log(`  Scope Path       : ${scopeArg}`);
+      if (nearestPkg) {
+        console.log(`  Nearest Package  : ${nearestPkg.id} (${nearestPkg.ecosystem})`);
+        console.log(`  Package Root     : ${nearestPkg.root}`);
+        console.log(`  Languages        : ${nearestPkg.languages.join(', ') || 'unspecified'}`);
+        console.log(`  Dependencies     : ${nearestPkg.dependencies.length} (${nearestPkg.dependencies.slice(0, 8).join(', ')}${nearestPkg.dependencies.length > 8 ? '...' : ''})`);
+        console.log(`  Configs          : ${nearestPkg.configs.join(', ') || 'none'}`);
+        if (nearestPkg.internalDependencies.length > 0) {
+          console.log(`  Internal Links   : ${nearestPkg.internalDependencies.join(', ')}`);
+        }
+        if (evidence.length > 0) {
+          console.log('\n  Scoped Evidence:');
+          for (const ev of evidence.slice(0, 10)) {
+            console.log(`    • [${ev.source}] ${ev.target} (+${ev.weight}) — ${ev.description}`);
+          }
+          if (evidence.length > 10) {
+            console.log(`      ... and ${evidence.length - 10} more signals`);
+          }
+        }
+      } else {
+        console.log('  Nearest Package  : (none found)');
+      }
+      console.log('\n──────────────────────────────────────────\n');
+    }
+  } else if (flags.json) {
+    const detection = detectProjectAttributes(process.cwd());
+    console.log(JSON.stringify({
+      ...detection,
+      workspaceGraph: graph,
+    }, null, 2));
+  } else if (explain) {
+    console.log('\n══════════════════════════════════════════');
+    console.log('  ContextOS — Workspace Evidence Graph');
+    console.log('══════════════════════════════════════════\n');
+    console.log(`  Repository Root  : ${graph.repositoryRoot}`);
+    console.log(`  Fingerprint      : ${graph.fingerprint}`);
+    console.log(`  Packages Found   : ${graph.packages.length} ${graph.partial ? '(partial: true)' : ''}\n`);
+    for (const pkg of graph.packages) {
+      console.log(`  • ${pkg.id} [${pkg.ecosystem}]`);
+      console.log(`    Root           : ${pkg.root}`);
+      console.log(`    Manifests      : ${pkg.manifests.join(', ')}`);
+      console.log(`    Languages      : ${pkg.languages.join(', ') || 'unspecified'}`);
+      console.log(`    Dependencies   : ${pkg.dependencies.length}`);
+      if (pkg.configs.length > 0) {
+        console.log(`    Configs        : ${pkg.configs.join(', ')}`);
+      }
+      if (pkg.internalDependencies.length > 0) {
+        console.log(`    Internal Links : ${pkg.internalDependencies.join(', ')}`);
+      }
+      console.log('');
+    }
+    console.log('──────────────────────────────────────────\n');
   } else {
+    const detection = detectProjectAttributes(process.cwd());
     console.log('\nContextOS — Tech Stack & Environment Detection\n');
+    console.log(`  Repository Root       : ${graph.repositoryRoot}`);
+    console.log(`  Packages Detected     : ${graph.packages.map(p => `${p.id} (${p.root})`).join(', ')}`);
     console.log(`  Detected Technologies : ${detection.summary.technologies.join(', ')}`);
     console.log(`  Detected Environments : ${detection.summary.ides.join(', ')}`);
     console.log(`  Recommended Profile   : ${detection.summary.recommendedProfile}`);
     console.log(`  Recommended Agents    : ${detection.summary.recommendedAgents.join(', ')}`);
     console.log(`  Recommended Skills    : ${detection.summary.recommendedSkills.join(', ')}\n`);
+    console.log('  Commands:');
+    console.log('    contextos detect --scope <path>    Scope detection to a specific file/subproject');
+    console.log('    contextos detect --explain         Display full workspace evidence graph\n');
   }
   process.exit(0);
 }
@@ -155,14 +235,26 @@ if (mainCommand === 'detect') {
 // Doctor command
 if (mainCommand === 'doctor') {
   const doctorModule = require('../.agents/doctor.js');
-  const result = doctorModule.runDoctor(process.cwd(), { json: flags.json });
+  const result = doctorModule.runDoctor(process.cwd(), {
+    json: flags.json,
+    fix: args.includes('--fix'),
+    strict: args.includes('--strict'),
+  });
   process.exit(result && result.ok === false ? 1 : 0);
 }
 
+// Recover command
+if (mainCommand === 'recover') {
+  const recoverModule = require('./commands/recover.js');
+  recoverModule(args, flags);
+  process.exit(0);
+}
+
 // Proxy commands to .agents/ctx.js when executed in a ContextOS project
 const PROXY_COMMANDS = [
   'profile', 'export', 'validate', 'resolve', 'skill', 'index',
-  'clean-worktrees', 'stats', 'watch'
+  'clean-worktrees', 'stats', 'watch', 'compile', 'explain',
+  'thread'
 ];
 
 const ctxPath = path.join(process.cwd(), '.agents', 'ctx.js');
@@ -208,7 +300,7 @@ if (mainCommand === 'watch') {
   watchModule.runWatch(process.cwd());
 }
 
-const PROJECT_ONLY_COMMANDS = ['profile', 'export', 'validate', 'resolve', 'skill', 'index', 'clean-worktrees'];
+const PROJECT_ONLY_COMMANDS = ['profile', 'export', 'validate', 'resolve', 'skill', 'index', 'clean-worktrees', 'compile', 'explain'];
 if (mainCommand && PROJECT_ONLY_COMMANDS.includes(mainCommand) && !hasLocalCtx) {
   console.error('[ERROR] .agents/ctx.js not found in current directory.');
   console.error('        Are you in a ContextOS project? Run `contextos` or `npx contextos-agents` first.');
@@ -338,46 +430,10 @@ if (mainCommand === 'install-skill') {
     })();
   }
 } else if (mainCommand === 'setup-mcp') {
-  const targetPath = path.join(process.cwd(), '.agents');
-  if (!fs.existsSync(targetPath)) {
-    console.error('[ERROR] .agents/ folder not found in current directory.');
-    console.error('        Run `npx contextos-agents` first or `npx contextos-agents --with-mcp`.');
-    process.exit(1);
-  }
-
-  const sourceMcp = path.join(__dirname, '..', '.agents', 'mcp');
-  const targetMcp = path.join(targetPath, 'mcp');
-  if (!fs.existsSync(sourceMcp)) {
-    console.error('[ERROR] Source MCP server bundle not found in package.');
-    process.exit(1);
-  }
-
-  try {
-    fs.cpSync(sourceMcp, targetMcp, { recursive: true, force: true });
-    console.log('[OK] Installed ContextOS MCP execution server into .agents/mcp/');
-
-    const mcpConfigPath = path.join(targetPath, 'mcp_config.json');
-    if (!fs.existsSync(mcpConfigPath) || flags.force) {
-      const defaultMcpConfig = {
-        mcpServers: {
-          "contextos": {
-            command: "node",
-            args: ["./.agents/mcp/server.mjs", "--dir", "."]
-          }
-        }
-      };
-      fs.writeFileSync(mcpConfigPath, JSON.stringify(defaultMcpConfig, null, 2));
-      console.log('[OK] Created MCP configuration (.agents/mcp_config.json)');
-    } else {
-      console.log('[INFO] Existing .agents/mcp_config.json retained.');
-    }
-    console.log('\n[SUCCESS] ContextOS MCP execution layer is configured.');
-    console.log('You can now use parallel subagents and git worktrees in your MCP-compatible IDE.\n');
-  } catch (err) {
-    console.error('[ERROR] Failed to configure MCP:', err.message);
-    process.exit(1);
-  }
-  process.exit(0);
+  console.error('[DEPRECATED] The bundled MCP server has been moved to a separate package in v2.0.');
+  console.error('             To use the MCP Bridge or execution runtime, install @contextos/mcp:');
+  console.error('             npm install @contextos/mcp --save-dev');
+  process.exit(1);
 } else {
 
 // ── Paths ─────────────────────────────────────────────────────────────────────
@@ -389,7 +445,9 @@ const MINIMAL_SKILLS = new Set([
   'ponytail-mindset',
   'gstack-roles',
   'gemini-precision',
-  'react',
+  'context-os',
+  'context-manager',
+  'security',
 ]);
 
 function uniqueSiblingPath(basePath, suffix) {
@@ -415,10 +473,8 @@ function installAtomically(source, target, options = {}) {
       force: true,
       filter: (src) => {
         const norm = src.replace(/\\/g, '/');
-        if (!options.withMcp) {
-          if (norm.endsWith('/mcp') || norm.includes('/mcp/') || norm.endsWith('/mcp_config.json')) {
-            return false;
-          }
+        if (norm.endsWith('/mcp') || norm.includes('/mcp/') || norm.endsWith('/mcp_config.json')) {
+          return false;
         }
         if (options.minimal) {
           const skillMatch = norm.match(/\/core\/skills\/([^/]+)/);
@@ -564,7 +620,12 @@ try {
       version,
     });
   } catch (err) {
-    if (!flags.json) console.warn(`[WARN] Could not generate lockfile: ${err.message}`);
+    if (flags.json) {
+      console.error(JSON.stringify({ success: false, error: `Could not generate lockfile: ${err.message}` }));
+    } else {
+      console.error(`[ERROR] Could not generate lockfile: ${err.message}`);
+    }
+    process.exit(1);
   }
 
   if (!flags.json) {
@@ -582,21 +643,11 @@ try {
     }
   }
 
-  // ── Create mcp_config.json only if --with-mcp ────────────────────────────────
+  // ── Deprecation warning for --with-mcp ────────────────────────────────────────────────
   if (flags.withMcp) {
-    const mcpConfigPath = path.join(targetPath, 'mcp_config.json');
-    if (!fs.existsSync(mcpConfigPath)) {
-      const defaultMcpConfig = {
-        mcpServers: {
-          "contextos": {
-            command: "node",
-            args: ["./.agents/mcp/server.mjs", "--dir", "."]
-          }
-        }
-      };
-      fs.writeFileSync(mcpConfigPath, JSON.stringify(defaultMcpConfig, null, 2));
-      if (!flags.json) console.log('[OK] Created default MCP configuration (.agents/mcp_config.json)');
-    }
+    console.warn('\n[DEPRECATED] The --with-mcp flag is no longer supported in ContextOS v2.0.');
+    console.warn('             The MCP execution runtime has been moved to a separate package.');
+    console.warn('             To enable the MCP server, run: npm install @contextos/mcp --save-dev\n');
   }
 
   // ── Apply profile if requested or auto ──────────────────────────────────────
@@ -605,7 +656,12 @@ try {
       const applied = profiles.applyProfile(selectedProfile, process.cwd());
       if (!flags.json) console.log(`[OK] Applied profile '${applied.name}' (excluded: ${(applied.exclude_skills || []).join(', ') || 'none'})`);
     } catch (e) {
-      if (!flags.json) console.warn(`[WARN] Could not apply profile '${selectedProfile}': ${e.message}`);
+      if (flags.json) {
+        console.error(JSON.stringify({ success: false, error: `Could not apply profile '${selectedProfile}': ${e.message}` }));
+      } else {
+        console.error(`[ERROR] Could not apply profile '${selectedProfile}': ${e.message}`);
+      }
+      process.exit(1);
     }
   }
 
@@ -626,10 +682,12 @@ try {
             stdio: flags.json ? 'ignore' : 'inherit',
           });
         } catch (e) {
-          if (!flags.json) {
-            console.warn(`[WARN] Skill compilation for '${ag}' failed — run manually:`);
-            console.warn(`       contextos export ${ag}`);
+          if (flags.json) {
+            console.error(JSON.stringify({ success: false, error: `Skill compilation for '${ag}' failed` }));
+          } else {
+            console.error(`[ERROR] Skill compilation for '${ag}' failed — run manually: contextos export ${ag}`);
           }
+          process.exit(1);
         }
       }
     }
@@ -649,10 +707,12 @@ try {
           stdio: flags.json ? 'ignore' : 'inherit',
         });
       } catch (e) {
-        if (!flags.json) {
-          console.warn(`[WARN] Skill install failed — run manually:`);
-          console.warn(`       node .agents/ctx.js skill add ${flags.addSkill}`);
+        if (flags.json) {
+          console.error(JSON.stringify({ success: false, error: `Skill install failed for ${flags.addSkill}` }));
+        } else {
+          console.error(`[ERROR] Skill install failed — run manually: node .agents/ctx.js skill add ${flags.addSkill}`);
         }
+        process.exit(1);
       }
     }
   }
@@ -686,10 +746,7 @@ try {
   console.log('  6. Add community skills (plugins):');
   console.log('       contextos skill add   username/my-skill');
   console.log('       contextos skill list');
-  if (!flags.withMcp) {
-    console.log('  7. Enable MCP parallel subagents & worktrees (optional):');
-    console.log('       contextos setup-mcp');
-  }
+
   console.log('');
 
 } catch (error) {

package/bin/lib/lockfile.js

@@ -59,7 +59,7 @@ function createLockfileData(options = {}) {
   return {
     schemaVersion: 1,
     installedPackage: options.installedPackage || 'contextos-agents',
-    version: options.version || '1.7.0',
+    version: options.version || '1.7.1',
     selectedProfile: options.selectedProfile || 'default',
     installedAt: options.installedAt || new Date().toISOString(),
     managedFiles: options.managedFiles ? { ...options.managedFiles } : {},
@@ -124,8 +124,10 @@ function saveLockfile(projectDir, lockData) {
     try {
       if (fs.existsSync(tmpPath)) fs.unlinkSync(tmpPath);
     } catch {}
-    // Fallback direct write
-    fs.writeFileSync(lockfilePath, content, 'utf8');
+    const atomicError = new Error(`Atomic lockfile update failed; original lockfile was preserved: ${err.message}`);
+    atomicError.code = 'CTX_LOCKFILE_ATOMIC_WRITE_FAILED';
+    atomicError.cause = err;
+    throw atomicError;
   }
 }
 

package/bin/lib/safe-writer.js

@@ -32,13 +32,43 @@ function atomicWriteFile(targetPath, content) {
   const tmpPath = `${targetPath}.tmp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
   try {
     fs.writeFileSync(tmpPath, content, 'utf8');
-    fs.renameSync(tmpPath, targetPath);
+
+    let renamed = false;
+    let lastError = null;
+    const maxRetries = 3;
+    const delays = [10, 50, 100];
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        fs.renameSync(tmpPath, targetPath);
+        renamed = true;
+        break;
+      } catch (renameErr) {
+        lastError = renameErr;
+        // Check for transient locking errors common on Windows (EPERM, EBUSY, EACCES)
+        const isTransient = renameErr.code === 'EPERM' || renameErr.code === 'EBUSY' || renameErr.code === 'EACCES';
+        if (isTransient && attempt < maxRetries) {
+          const waitMs = delays[attempt];
+          try {
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, waitMs);
+          } catch {
+            const start = Date.now();
+            while (Date.now() - start < waitMs) {}
+          }
+        } else {
+          break;
+        }
+      }
+    }
+
+    if (!renamed) {
+      throw lastError || new Error(`Failed to atomically rename ${tmpPath} to ${targetPath}`);
+    }
   } catch (err) {
     try {
       if (fs.existsSync(tmpPath)) fs.unlinkSync(tmpPath);
     } catch {}
-    // Direct write fallback
-    fs.writeFileSync(targetPath, content, 'utf8');
+    throw err;
   }
 }
 
@@ -256,4 +286,5 @@ module.exports = {
   executeFileWrite,
   planFileDelete,
   executeFileDelete,
+  cleanEmptyParentDirectories,
 };