aether-colony 3.1.17 → 5.1.0

package/bin/lib/update-transaction.js

@@ -161,61 +161,45 @@ class UpdateTransaction {
     // Hub paths (from cli.js)
     this.HOME = process.env.HOME || process.env.USERPROFILE;
     this.HUB_DIR = path.join(this.HOME, '.aether');
-    this.HUB_COMMANDS_CLAUDE = path.join(this.HUB_DIR, 'commands', 'claude');
-    this.HUB_COMMANDS_OPENCODE = path.join(this.HUB_DIR, 'commands', 'opencode');
-    this.HUB_AGENTS = path.join(this.HUB_DIR, 'agents');
+    this.HUB_SYSTEM_DIR = path.join(this.HUB_DIR, 'system');
+    this.HUB_COMMANDS_CLAUDE = path.join(this.HUB_SYSTEM_DIR, 'commands', 'claude');
+    this.HUB_COMMANDS_OPENCODE = path.join(this.HUB_SYSTEM_DIR, 'commands', 'opencode');
+    this.HUB_AGENTS = path.join(this.HUB_SYSTEM_DIR, 'agents');
+    this.HUB_AGENTS_CLAUDE = path.join(this.HUB_SYSTEM_DIR, 'agents-claude');
+    this.HUB_RULES = path.join(this.HUB_SYSTEM_DIR, 'rules');
     this.HUB_VERSION = path.join(this.HUB_DIR, 'version.json');
     this.HUB_REGISTRY = path.join(this.HUB_DIR, 'registry.json');
 
-    // Directories to exclude from sync (user data, local state)
-    this.EXCLUDE_DIRS = ['data', 'dreams', 'checkpoints', 'locks', 'temp'];
+    // Directories to exclude from sync (user data, local state, and separately-synced dirs)
+    // v4.0: archive and chambers added — these are private and must not sync to target repos
+    // v6.0: oracle, midden, exchange added for complete user data protection
+    this.EXCLUDE_DIRS = ['data', 'dreams', 'oracle', 'midden', 'checkpoints', 'locks', 'temp', 'agents', 'commands', 'rules', 'archive', 'chambers', 'exchange'];
+
+    // Files to exclude from sync (user wisdom, protected files)
+    this.EXCLUDE_FILES = ['QUEEN.md'];
 
     // Target directories for git safety checks
-    this.targetDirs = ['.aether', '.claude/commands/ant', '.opencode/commands/ant', '.opencode/agents'];
-
-    // System files allowlist (from cli.js)
-    this.SYSTEM_FILES = [
-      'aether-utils.sh',
-      'coding-standards.md',
-      'debugging.md',
-      'DISCIPLINES.md',
-      'learning.md',
-      'planning.md',
-      'QUEEN_ANT_ARCHITECTURE.md',
-      'tdd.md',
-      'verification-loop.md',
-      'verification.md',
-      'workers.md',
-      'workers-new-castes.md',
-      'docs/biological-reference.md',
-      'docs/command-sync.md',
-      'docs/constraints.md',
-      'docs/namespace.md',
-      'docs/pathogen-schema-example.json',
-      'docs/pathogen-schema.md',
-      'docs/PHEROMONE-INJECTION.md',
-      'docs/PHEROMONE-INTEGRATION.md',
-      'docs/PHEROMONE-SYSTEM-DESIGN.md',
-      'docs/pheromones.md',
-      'docs/progressive-disclosure.md',
-      'docs/README.md',
-      'docs/VISUAL-OUTPUT-SPEC.md',
-      'docs/known-issues.md',
-      'docs/implementation-learnings.md',
-      'docs/codebase-review.md',
-      'docs/planning-discipline.md',
-      'utils/atomic-write.sh',
-      'utils/chamber-compare.sh',
-      'utils/chamber-utils.sh',
-      'utils/colorize-log.sh',
-      'utils/error-handler.sh',
-      'utils/file-lock.sh',
-      'utils/spawn-tree.sh',
-      'utils/spawn-with-model.sh',
-      'utils/state-loader.sh',
-      'utils/swarm-display.sh',
-      'utils/watch-spawn-tree.sh',
-      'templates/QUEEN.md.template',
+    this.targetDirs = ['.aether', '.claude/commands/ant', '.claude/agents/ant', '.claude/rules', '.opencode/commands/ant', '.opencode/agents'];
+
+    // Managed paths for update safety checks (must align with files update can actually modify)
+    this.protectedAetherDirs = new Set([
+      'data',
+      'dreams',
+      'oracle',
+      'midden',
+      'checkpoints',
+      'locks',
+      'temp',
+      'archive',
+      'chambers',
+      'exchange',
+    ]);
+    this.managedPrefixes = [
+      '.claude/commands/ant',
+      '.claude/agents/ant',
+      '.claude/rules',
+      '.opencode/commands/ant',
+      '.opencode/agents',
     ];
   }
 
@@ -251,7 +235,22 @@ class UpdateTransaction {
    */
   writeJsonSync(filePath, data) {
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n');
+    const content = JSON.stringify(data, null, 2) + '\n';
+    const tmpPath = filePath + '.tmp';
+    try {
+      fs.writeFileSync(tmpPath, content);
+      fs.renameSync(tmpPath, filePath);
+    } catch (err) {
+      // Clean up temp file on failure
+      try {
+        if (fs.existsSync(tmpPath)) {
+          fs.unlinkSync(tmpPath);
+        }
+      } catch {
+        // Ignore cleanup errors
+      }
+      throw err;
+    }
   }
 
   /**
@@ -269,6 +268,40 @@ class UpdateTransaction {
     }
   }
 
+  /**
+   * Copy file atomically using temp file + rename pattern
+   * Prevents partial file corruption on process interruption
+   * @param {string} srcPath - Source file path
+   * @param {string} destPath - Destination file path
+   * @private
+   */
+  copyFileAtomic(srcPath, destPath) {
+    const tempPath = `${destPath}.tmp.${process.pid}.${Date.now()}`;
+
+    try {
+      // Copy to temp file first
+      fs.copyFileSync(srcPath, tempPath);
+
+      // Atomic rename (POSIX guarantees atomicity)
+      fs.renameSync(tempPath, destPath);
+
+      // Set executable permission for shell scripts
+      if (destPath.endsWith('.sh')) {
+        fs.chmodSync(destPath, 0o755);
+      }
+    } catch (err) {
+      // Clean up temp file on failure
+      try {
+        if (fs.existsSync(tempPath)) {
+          fs.unlinkSync(tempPath);
+        }
+      } catch {
+        // Ignore cleanup errors
+      }
+      throw err;
+    }
+  }
+
   /**
    * Check if path is a git repository
    * @returns {boolean} True if git repo
@@ -283,6 +316,54 @@ class UpdateTransaction {
     }
   }
 
+  /**
+   * Normalize git porcelain path output.
+   * Handles rename syntax and quoted/escaped paths.
+   * @param {string} filePath - Raw path fragment from git porcelain
+   * @returns {string} Normalized path
+   * @private
+   */
+  normalizePorcelainPath(filePath) {
+    let normalized = filePath;
+
+    if (normalized.includes(' -> ')) {
+      normalized = normalized.split(' -> ').pop();
+    }
+
+    if (normalized.startsWith('"') && normalized.endsWith('"')) {
+      normalized = normalized
+        .slice(1, -1)
+        .replace(/\\"/g, '"')
+        .replace(/\\\\/g, '\\');
+    }
+
+    return normalized;
+  }
+
+  /**
+   * True when a path is managed by update and may be overwritten by sync.
+   * Paths under .aether/data and other protected runtime dirs are intentionally excluded.
+   * @param {string} filePath - Normalized or raw path
+   * @returns {boolean} Whether update should treat this path as managed
+   * @private
+   */
+  isManagedUpdatePath(filePath) {
+    const p = this.normalizePorcelainPath(filePath);
+
+    if (p === '.aether' || p.startsWith('.aether/')) {
+      const rel = p === '.aether' ? '' : p.slice('.aether/'.length);
+      if (!rel) return true;
+
+      const first = rel.split('/')[0];
+      if (!first || first.startsWith('.')) return false;
+      if (this.protectedAetherDirs.has(first)) return false;
+      if (rel === 'QUEEN.md') return false;
+      return true;
+    }
+
+    return this.managedPrefixes.some(prefix => p === prefix || p.startsWith(`${prefix}/`));
+  }
+
   /**
    * Detect dirty repository state with detailed categorization
    * @returns {object} Dirty state info: { isDirty, tracked, untracked, staged }
@@ -298,14 +379,25 @@ class UpdateTransaction {
         encoding: 'utf8',
       });
 
-      const lines = result.trim().split('\n').filter(Boolean);
+      // Preserve the two-column porcelain status prefix on each line.
+      // Using `trim()` on the whole output would strip leading spaces from
+      // the first line and can misclassify unstaged vs staged changes.
+      const lines = result.split('\n').filter(line => line.trim().length > 0);
       const tracked = [];
       const untracked = [];
       const staged = [];
+      let managedCount = 0;
 
       for (const line of lines) {
         const status = line.slice(0, 2);
-        const filePath = line.slice(3);
+        const rawPath = line.slice(3);
+        const filePath = this.normalizePorcelainPath(rawPath);
+
+        if (!this.isManagedUpdatePath(filePath)) {
+          continue;
+        }
+
+        managedCount++;
 
         // Staged changes (in index)
         if (status[0] !== ' ' && status[0] !== '?') {
@@ -322,7 +414,7 @@ class UpdateTransaction {
       }
 
       return {
-        isDirty: lines.length > 0,
+        isDirty: managedCount > 0,
         tracked,
         untracked,
         staged,
@@ -621,10 +713,7 @@ class UpdateTransaction {
           }
 
           if (shouldCopy) {
-            fs.copyFileSync(srcPath, destPath);
-            if (relPath.endsWith('.sh')) {
-              fs.chmodSync(destPath, 0o755);
-            }
+            this.copyFileAtomic(srcPath, destPath);
             copied++;
           }
         } catch (err) {
@@ -687,74 +776,59 @@ class UpdateTransaction {
   }
 
   /**
-   * Sync system files from hub
-   * @param {string} srcDir - Source directory
-   * @param {string} destDir - Destination directory
-   * @param {object} opts - Options
-   * @returns {object} Sync result: { copied, removed, skipped }
+   * Check if a path should be excluded from sync
+   * @param {string} relPath - Relative path
+   * @returns {boolean} True if should be excluded
    * @private
    */
-  syncSystemFilesWithCleanup(srcDir, destDir, opts) {
-    opts = opts || {};
-    const dryRun = opts.dryRun || false;
-
-    let copied = 0;
-    let skipped = 0;
-
-    for (const file of this.SYSTEM_FILES) {
-      const srcPath = path.join(srcDir, file);
-      const destPath = path.join(destDir, file);
-      if (fs.existsSync(srcPath)) {
-        if (!dryRun) {
-          // Compute hashes to determine if copy is needed
-          const srcHash = this.hashFileSync(srcPath);
-          const destHash = fs.existsSync(destPath) ? this.hashFileSync(destPath) : null;
-
-          if (srcHash === destHash) {
-            // Files are identical, skip copying
-            skipped++;
-            continue;
-          }
-
-          fs.mkdirSync(path.dirname(destPath), { recursive: true });
-          fs.copyFileSync(srcPath, destPath);
-          if (file.endsWith('.sh')) {
-            fs.chmodSync(destPath, 0o755);
-          }
-        }
-        copied++;
-      }
-    }
-
-    // Remove allowlisted files that no longer exist in src
-    const removed = [];
-    for (const file of this.SYSTEM_FILES) {
-      const srcPath = path.join(srcDir, file);
-      const destPath = path.join(destDir, file);
-      if (!fs.existsSync(srcPath) && fs.existsSync(destPath)) {
-        removed.push(file);
-        if (!dryRun) {
-          fs.unlinkSync(destPath);
-        }
-      }
+  shouldExclude(relPath) {
+    const parts = relPath.split(path.sep);
+    // Check for excluded directories
+    if (parts.some(part => this.EXCLUDE_DIRS.includes(part))) {
+      return true;
     }
-
-    if (!dryRun && removed.length > 0) {
-      this.cleanEmptyDirs(destDir);
+    // Check for excluded files (QUEEN.md protection)
+    const basename = path.basename(relPath);
+    if (this.EXCLUDE_FILES.includes(basename)) {
+      return true;
     }
-
-    return { copied, removed, skipped };
+    return false;
   }
 
   /**
-   * Check if a path should be excluded from sync
-   * @param {string} relPath - Relative path
-   * @returns {boolean} True if should be excluded
-   * @private
+   * Get files that the update would actually overwrite (hub version differs from repo version).
+   * Used by the dirty-file check to only warn about files that matter.
+   * @returns {string[]} Repo-relative paths of files that would be overwritten
    */
-  shouldExclude(relPath) {
-    const parts = relPath.split(path.sep);
-    return parts.some(part => this.EXCLUDE_DIRS.includes(part));
+  getConflictingFiles() {
+    const conflicts = [];
+
+    // Helper: check a hub->repo dir pair for differing files
+    const checkDir = (hubDir, repoDir, prefix) => {
+      if (!fs.existsSync(hubDir)) return;
+      const srcFiles = this.listFilesRecursive(hubDir);
+      for (const relPath of srcFiles) {
+        if (this.shouldExclude(relPath)) continue;
+        const destPath = path.join(repoDir, relPath);
+        if (fs.existsSync(destPath)) {
+          const srcHash = this.hashFileSync(path.join(hubDir, relPath));
+          const destHash = this.hashFileSync(destPath);
+          if (srcHash !== destHash) {
+            conflicts.push(`${prefix}${relPath}`);
+          }
+        }
+      }
+    };
+
+    const repoAether = path.join(this.repoPath, '.aether');
+    checkDir(this.HUB_SYSTEM_DIR, repoAether, '.aether/');
+    checkDir(this.HUB_COMMANDS_CLAUDE, path.join(this.repoPath, '.claude', 'commands', 'ant'), '.claude/commands/ant/');
+    checkDir(this.HUB_COMMANDS_OPENCODE, path.join(this.repoPath, '.opencode', 'commands', 'ant'), '.opencode/commands/ant/');
+    checkDir(this.HUB_AGENTS, path.join(this.repoPath, '.opencode', 'agents'), '.opencode/agents/');
+    checkDir(this.HUB_AGENTS_CLAUDE, path.join(this.repoPath, '.claude', 'agents', 'ant'), '.claude/agents/ant/');
+    checkDir(this.HUB_RULES, path.join(this.repoPath, '.claude', 'rules'), '.claude/rules/');
+
+    return conflicts;
   }
 
   /**
@@ -800,28 +874,30 @@ class UpdateTransaction {
       const srcPath = path.join(srcDir, relPath);
       const destPath = path.join(destDir, relPath);
 
+      // Hash comparison: determine if copy is needed (runs for both dry-run and actual)
+      let shouldCopy = true;
+      if (fs.existsSync(destPath)) {
+        const srcHash = this.hashFileSync(srcPath);
+        const destHash = this.hashFileSync(destPath);
+        if (srcHash === destHash) {
+          shouldCopy = false;
+          skipped++;
+        }
+      }
+
       if (!dryRun) {
         fs.mkdirSync(path.dirname(destPath), { recursive: true });
 
-        // Hash comparison
-        let shouldCopy = true;
-        if (fs.existsSync(destPath)) {
-          const srcHash = this.hashFileSync(srcPath);
-          const destHash = this.hashFileSync(destPath);
-          if (srcHash === destHash) {
-            shouldCopy = false;
-            skipped++;
-          }
+        if (shouldCopy) {
+          this.copyFileAtomic(srcPath, destPath);
+          copied++;  // FIX: Only increment when actually copied
         }
-
+      } else {
+        // dry-run: count files that WOULD be copied
         if (shouldCopy) {
-          fs.copyFileSync(srcPath, destPath);
-          if (relPath.endsWith('.sh')) {
-            fs.chmodSync(destPath, 0o755);
-          }
+          copied++;  // Count only files that would actually be copied
         }
       }
-      copied++;
     }
 
     // Cleanup: remove files in dest that aren't in source
@@ -867,6 +943,116 @@ class UpdateTransaction {
     return { copied, removed, skipped };
   }
 
+  /**
+   * Move a file or directory to trash instead of deleting
+   * @param {string} itemPath - Path to file or directory
+   * @param {string} repoPath - Repository root for trash location
+   * @returns {boolean} True if moved to trash successfully
+   * @private
+   */
+  moveToTrash(itemPath, repoPath) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    const trashDir = path.join(repoPath, '.aether', '.trash', timestamp);
+    const basename = path.basename(itemPath);
+    const trashPath = path.join(trashDir, basename);
+
+    try {
+      fs.mkdirSync(trashDir, { recursive: true });
+      fs.renameSync(itemPath, trashPath);
+      return true;
+    } catch (err) {
+      // If rename fails (cross-device), fall back to copy + delete
+      try {
+        fs.mkdirSync(trashDir, { recursive: true });
+        if (fs.statSync(itemPath).isDirectory()) {
+          fs.cpSync(itemPath, path.join(trashDir, basename), { recursive: true });
+          fs.rmSync(itemPath, { recursive: true, force: true });
+        } else {
+          fs.copyFileSync(itemPath, path.join(trashDir, basename));
+          fs.unlinkSync(itemPath);
+        }
+        return true;
+      } catch (fallbackErr) {
+        return false;
+      }
+    }
+  }
+
+  /**
+   * Remove known stale directories and files left behind by pre-3.0.0 versions.
+   *
+   * IMPORTANT: Removed items are moved to .aether/.trash/ NOT deleted.
+   * Users can inspect and manually clean trash when ready.
+   * Trash folders are timestamped for easy identification.
+   *
+   * Protected paths (never cleaned):
+   * - .aether/data/ - Colony state
+   * - .aether/dreams/ - Session notes
+   * - .aether/oracle/ - Research progress
+   * - .aether/midden/ - Failure tracking
+   * - .aether/QUEEN.md - User's wisdom file
+   *
+   * Idempotent: safe to call when items do not exist.
+   *
+   * @param {string} repoPath - Absolute path to the target repository root
+   * @returns {{ cleaned: string[], failed: Array<{label: string, error: string}>, trashDir: string }}
+   */
+  cleanupStaleAetherDirs(repoPath) {
+    // Safety check: never clean protected directories
+    const protectedDirs = ['data', 'dreams', 'oracle', 'midden'];
+    const protectedFiles = ['QUEEN.md'];
+
+    // Verify none of our stale items are in protected paths
+    const aetherDir = path.join(repoPath, '.aether');
+    for (const dir of protectedDirs) {
+      const protectedPath = path.join(aetherDir, dir);
+      if (fs.existsSync(protectedPath)) {
+        // Log that protected dir exists and will be preserved
+        this.log?.(`  Preserving protected directory: .aether/${dir}/`);
+      }
+    }
+
+    const staleItems = [
+      {
+        path: path.join(repoPath, '.aether', 'agents'),
+        label: '.aether/agents/ (stale duplicate)',
+        type: 'dir',
+      },
+      {
+        path: path.join(repoPath, '.aether', 'commands'),
+        label: '.aether/commands/ (stale duplicate)',
+        type: 'dir',
+      },
+      {
+        path: path.join(repoPath, '.aether', 'planning.md'),
+        label: '.aether/planning.md (phantom file)',
+        type: 'file',
+      },
+    ];
+
+    const cleaned = [];
+    const failed = [];
+
+    for (const item of staleItems) {
+      if (!fs.existsSync(item.path)) {
+        // Already clean — idempotent skip
+        continue;
+      }
+
+      try {
+        if (this.moveToTrash(item.path, repoPath)) {
+          cleaned.push(item.label);
+        } else {
+          failed.push({ label: item.label, error: 'Failed to move to trash' });
+        }
+      } catch (err) {
+        failed.push({ label: item.label, error: err.message });
+      }
+    }
+
+    return { cleaned, failed, trashDir: path.join(repoPath, '.aether', '.trash') };
+  }
+
   /**
    * Sync files from hub to repo
    * @param {string} sourceVersion - Version to sync from
@@ -880,14 +1066,16 @@ class UpdateTransaction {
       system: { copied: 0, removed: 0, skipped: 0 },
       commands: { copied: 0, removed: 0, skipped: 0 },
       agents: { copied: 0, removed: 0, skipped: 0 },
+      agents_claude: { copied: 0, removed: [], skipped: 0 },
+      rules: { copied: 0, removed: 0, skipped: 0 },
       errors: [],
     };
 
     const repoAether = path.join(this.repoPath, '.aether');
 
     // Sync .aether/ from hub to repo (excluding user data directories)
-    if (fs.existsSync(this.HUB_DIR)) {
-      results.system = this.syncAetherToRepo(this.HUB_DIR, repoAether, { dryRun });
+    if (fs.existsSync(this.HUB_SYSTEM_DIR)) {
+      results.system = this.syncAetherToRepo(this.HUB_SYSTEM_DIR, repoAether, { dryRun });
     }
 
     // Sync commands from hub
@@ -911,6 +1099,18 @@ class UpdateTransaction {
       results.agents = this.syncDirWithCleanup(this.HUB_AGENTS, repoAgents, { dryRun });
     }
 
+    // Sync claude agents from hub to .claude/agents/ant/
+    const repoClaudeAgents = path.join(this.repoPath, '.claude', 'agents', 'ant');
+    if (fs.existsSync(this.HUB_AGENTS_CLAUDE)) {
+      results.agents_claude = this.syncDirWithCleanup(this.HUB_AGENTS_CLAUDE, repoClaudeAgents, { dryRun });
+    }
+
+    // Sync rules from hub to .claude/rules/
+    const repoRules = path.join(this.repoPath, '.claude', 'rules');
+    if (fs.existsSync(this.HUB_RULES)) {
+      results.rules = this.syncDirWithCleanup(this.HUB_RULES, repoRules, { dryRun });
+    }
+
     this.syncResult = results;
     return results;
   }
@@ -953,10 +1153,12 @@ class UpdateTransaction {
     };
 
     const repoAether = path.join(this.repoPath, '.aether');
-    verifyDir(this.HUB_DIR, repoAether);
+    verifyDir(this.HUB_SYSTEM_DIR, repoAether);
     verifyDir(this.HUB_COMMANDS_CLAUDE, path.join(this.repoPath, '.claude', 'commands', 'ant'));
     verifyDir(this.HUB_COMMANDS_OPENCODE, path.join(this.repoPath, '.opencode', 'commands', 'ant'));
     verifyDir(this.HUB_AGENTS, path.join(this.repoPath, '.opencode', 'agents'));
+    verifyDir(this.HUB_AGENTS_CLAUDE, path.join(this.repoPath, '.claude', 'agents', 'ant'));
+    verifyDir(this.HUB_RULES, path.join(this.repoPath, '.claude', 'rules'));
 
     return {
       valid: errors.length === 0,
@@ -1002,6 +1204,8 @@ class UpdateTransaction {
     checkDir(this.HUB_COMMANDS_CLAUDE, 'commands/claude');
     checkDir(this.HUB_COMMANDS_OPENCODE, 'commands/opencode');
     checkDir(this.HUB_AGENTS, 'agents');
+    checkDir(this.HUB_AGENTS_CLAUDE, 'agents-claude');
+    checkDir(this.HUB_RULES, 'rules');
     checkDir(this.HUB_VERSION, 'version');
 
     // Check if source files exist
@@ -1098,10 +1302,11 @@ class UpdateTransaction {
     };
 
     const repoAether = path.join(this.repoPath, '.aether');
-    checkDir(this.HUB_DIR, repoAether);
+    checkDir(this.HUB_SYSTEM_DIR, repoAether);
     checkDir(this.HUB_COMMANDS_CLAUDE, path.join(this.repoPath, '.claude', 'commands', 'ant'));
     checkDir(this.HUB_COMMANDS_OPENCODE, path.join(this.repoPath, '.opencode', 'commands', 'ant'));
     checkDir(this.HUB_AGENTS, path.join(this.repoPath, '.opencode', 'agents'));
+    checkDir(this.HUB_RULES, path.join(this.repoPath, '.claude', 'rules'));
 
     return {
       isPartial: missing.length > 0 || corrupted.length > 0,
@@ -1260,6 +1465,14 @@ class UpdateTransaction {
    * @returns {Promise<boolean>} True if rollback succeeded
    */
   async rollback() {
+    // Clear pending sentinel on rollback — we've cleanly returned to prior state
+    const pendingPath = path.join(this.repoPath, '.aether', '.update-pending');
+    try {
+      if (fs.existsSync(pendingPath)) {
+        fs.unlinkSync(pendingPath);
+      }
+    } catch { /* ignore — rollback cleanup is best-effort */ }
+
     this.state = TransactionStates.ROLLING_BACK;
     this.log('  Rolling back to checkpoint...');
 
@@ -1270,6 +1483,23 @@ class UpdateTransaction {
         return false;
       }
 
+      // Restore backed-up managed files before stash pop
+      // Stash only contains the user's local modifications; managed files
+      // overwritten by syncFiles must be restored from the checkpoint backup.
+      if (this.checkpoint.backedUpFiles && this.checkpoint.backedUpFiles.length > 0) {
+        for (const entry of this.checkpoint.backedUpFiles) {
+          try {
+            if (fs.existsSync(entry.backupPath)) {
+              fs.mkdirSync(path.dirname(path.join(this.repoPath, entry.relPath)), { recursive: true });
+              fs.copyFileSync(entry.backupPath, path.join(this.repoPath, entry.relPath));
+              this.log(`  Restored managed file: ${entry.relPath}`);
+            }
+          } catch (err) {
+            this.log(`  Warning: could not restore ${entry.relPath}: ${err.message}`);
+          }
+        }
+      }
+
       // Restore from stash if available
       if (this.checkpoint.stashRef) {
         try {
@@ -1342,6 +1572,13 @@ class UpdateTransaction {
   async execute(sourceVersion, options = {}) {
     const dryRun = options.dryRun || false;
 
+    // Write pending sentinel BEFORE any work — marks update as in-flight
+    const pendingPath = path.join(this.repoPath, '.aether', '.update-pending');
+    this.writeJsonSync(pendingPath, {
+      target_version: sourceVersion,
+      started_at: new Date().toISOString(),
+    });
+
     try {
       // Phase 0: Validate repo state (before any modifications)
       // Check for dirty repo and provide clear recovery instructions
@@ -1368,6 +1605,9 @@ class UpdateTransaction {
 
       await this.createCheckpoint();
 
+      // Clean up known stale directories/files from previous versions
+      this.cleanupResult = this.cleanupStaleAetherDirs(this.repoPath);
+
       // Phase 2: Sync (with network error handling)
       this.state = TransactionStates.SYNCING;
       try {
@@ -1403,15 +1643,26 @@ class UpdateTransaction {
         this.state = TransactionStates.COMMITTING;
         this.updateVersion(sourceVersion);
         this.state = TransactionStates.COMMITTED;
+
+        // Delete pending sentinel — update is now complete
+        try {
+          if (fs.existsSync(pendingPath)) {
+            fs.unlinkSync(pendingPath);
+          }
+        } catch (err) {
+          this.log(`  Warning: could not clear update sentinel: ${err.message}`);
+        }
       }
 
       // Calculate totals
       const filesSynced = (this.syncResult?.system?.copied || 0) +
                          (this.syncResult?.commands?.copied || 0) +
-                         (this.syncResult?.agents?.copied || 0);
+                         (this.syncResult?.agents?.copied || 0) +
+                         (this.syncResult?.rules?.copied || 0);
       const filesRemoved = (this.syncResult?.system?.removed?.length || 0) +
                           (this.syncResult?.commands?.removed?.length || 0) +
-                          (this.syncResult?.agents?.removed?.length || 0);
+                          (this.syncResult?.agents?.removed?.length || 0) +
+                          (this.syncResult?.rules?.removed?.length || 0);
 
       return {
         success: true,
@@ -1420,6 +1671,7 @@ class UpdateTransaction {
         files_synced: filesSynced,
         files_removed: filesRemoved,
         sync_result: this.syncResult,
+        cleanup_result: this.cleanupResult || { cleaned: [], failed: [] },
       };
 
     } catch (error) {
@@ -1449,4 +1701,4 @@ module.exports = {
   UpdateError,
   UpdateErrorCodes,
   TransactionStates,
-};
+};