principles-disciple 1.51.0 → 1.53.0

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "principles-disciple",
   "name": "Principles Disciple",
   "description": "Evolutionary programming agent framework with strategic guardrails and reflection loops.",
-  "version": "1.51.0",
+  "version": "1.53.0",
   "skills": [
     "./skills"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "principles-disciple",
-  "version": "1.51.0",
+  "version": "1.53.0",
   "description": "Native OpenClaw plugin for Principles Disciple",
   "type": "module",
   "main": "./dist/bundle.js",

package/scripts/compile-principles.mjs

@@ -18,10 +18,20 @@ import { fileURLToPath } from 'url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
+/**
+ * Cross-platform home directory (Linux: HOME, Windows: USERPROFILE/HOMEDRIVE+HOMEPATH)
+ */
+function getHomeDir() {
+  return process.env.HOME
+    || process.env.USERPROFILE
+    || (process.env.HOMEDRIVE && process.env.HOMEPATH ? process.env.HOMEDRIVE + process.env.HOMEPATH : null)
+    || '.';
+}
+
 // Resolve workspace directory: CLI arg > env var > default
 const WORKSPACE_DIR = process.argv[2]
   || process.env.WORKSPACE_DIR
-  || join(process.env.HOME, '.openclaw', 'workspace-main');
+  || join(getHomeDir(), '.openclaw', 'workspace');
 
 const STATE_DIR = join(WORKSPACE_DIR, '.state');
 

package/scripts/sync-plugin.mjs

@@ -27,8 +27,36 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
 const SOURCE_DIR = join(__dirname, '..');
-const OPENCLAW_DIR = join(process.env.HOME, '.openclaw');
+
+/**
+ * Cross-platform home directory resolution.
+ * Linux/macOS: HOME=/home/user
+ * Windows: USERPROFILE=C:\Users\user or HOMEDRIVE/HOMEPATH
+ */
+function getHomeDir() {
+  return process.env.HOME
+    || process.env.USERPROFILE
+    || (process.env.HOMEDRIVE && process.env.HOMEPATH ? process.env.HOMEDRIVE + process.env.HOMEPATH : null)
+    || '.';
+}
+
+const OPENCLAW_DIR = join(getHomeDir(), '.openclaw');
 const INSTALL_DIR = join(OPENCLAW_DIR, 'extensions', 'principles-disciple');
+function getConfiguredWorkspaceDir() {
+  const configPath = join(OPENCLAW_DIR, 'openclaw.json');
+  try {
+    const raw = readFileSync(configPath, 'utf-8');
+    const config = JSON.parse(raw);
+    const workspace = config?.agents?.defaults?.workspace;
+    if (workspace && existsSync(workspace)) {
+      return workspace;
+    }
+  } catch {
+    // Fall through to fallback
+  }
+  // Fallback: try workspace-main (legacy default)
+  return join(OPENCLAW_DIR, 'workspace-main');
+}
 
 // Files and directories to sync
 const SYNC_ITEMS = [
@@ -177,7 +205,11 @@ function checkPrerequisites() {
         // Check for global package conflicts that cause module resolution traps
         console.log('🔍 Checking for global package conflicts...');
         try {
-            const globalConflict = execSync('npm list -g principles-disciple --depth=0 2>/dev/null', { encoding: 'utf-8' });
+            // Cross-platform: use stdio: 'pipe' to capture stderr, then check output
+            const globalConflict = execSync('npm list -g principles-disciple --depth=0', {
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'pipe']  // Capture all streams
+            });
             if (globalConflict.includes('principles-disciple')) {
                 console.error('\n❌ CONFLICT DETECTED: A version of "principles-disciple" is installed globally via npm.');
                 console.error('This will block OpenClaw from loading the extension version you are trying to install.');
@@ -187,7 +219,17 @@ function checkPrerequisites() {
             }
         } catch (e) {
             // npm list returns non-zero if not found, which is what we want
-            console.log('✅ No global package conflicts detected.');
+            // Check if the error output contains the package name
+            const output = e.stdout || e.stderr || '';
+            if (!output.includes('principles-disciple')) {
+                console.log('✅ No global package conflicts detected.');
+            } else {
+                console.error('\n❌ CONFLICT DETECTED: A version of "principles-disciple" is installed globally via npm.');
+                console.error('This will block OpenClaw from loading the extension version you are trying to install.');
+                console.error('\nACTION REQUIRED: Please run the following command first:');
+                console.error('   npm uninstall -g principles-disciple\n');
+                process.exit(1);
+            }
         }
     } catch {
         console.error('❌ npm not found. Please install Node.js with npm.');
@@ -481,7 +523,7 @@ function verifyInstalledFingerprint() {
 }
 
 /**
- * Remove existing installation directory.
+ * Remove existing installation directory with Windows-friendly retry logic.
  */
 function cleanTargetDir(force) {
     if (!existsSync(INSTALL_DIR)) return;
@@ -495,7 +537,34 @@ function cleanTargetDir(force) {
     }
 
     console.log('\n🗑️  Removing existing installation...');
-    rmSync(INSTALL_DIR, { recursive: true, force: true });
+
+    // Windows often returns EPERM due to file locks, add retry logic
+    const maxRetries = isWindows() ? 3 : 1;
+    let lastError = null;
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        try {
+            rmSync(INSTALL_DIR, { recursive: true, force: true });
+            console.log('   ✅ Removed successfully.');
+            return;
+        } catch (err) {
+            lastError = err;
+            if (err.code === 'EPERM' && attempt < maxRetries) {
+                console.log(`   ⚠️  Attempt ${attempt}/${maxRetries} failed (EPERM), retrying in 2s...`);
+                // Synchronous sleep for retry
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 2000);
+            }
+        }
+    }
+
+    // If all retries failed on Windows, try graceful fallback
+    if (isWindows() && lastError?.code === 'EPERM') {
+        console.log('   ⚠️  Windows file lock detected, skipping removal.');
+        console.log('   📁 Will overwrite files in place.');
+        return;  // Continue with overwrite installation
+    }
+
+    throw lastError;
 }
 
 /**
@@ -573,17 +642,115 @@ function cleanStaleBackups() {
 }
 
 /**
- * Restart OpenClaw Gateway.
+ * Check if running on Windows.
+ */
+function isWindows() {
+    return process.platform === 'win32';
+}
+
+/**
+ * Get temporary directory path (cross-platform).
+ */
+function getTempDir() {
+    if (isWindows()) {
+        return process.env.TEMP || process.env.TMP || 'C:\\Windows\\Temp';
+    }
+    return '/tmp';
+}
+
+/**
+ * Restart OpenClaw Gateway (cross-platform).
  */
 function restartGateway() {
     console.log('\n🔄 Restarting OpenClaw Gateway...');
+
+    if (isWindows()) {
+        return restartGatewayWindows();
+    } else {
+        return restartGatewayLinux();
+    }
+}
+
+/**
+ * Restart Gateway on Windows using PowerShell.
+ */
+function restartGatewayWindows() {
+    const logPath = join(getTempDir(), 'openclaw-auto-restart.log');
+
     try {
+        // Step 1: Find and terminate existing gateway processes
+        console.log('   Looking for existing gateway processes...');
+        try {
+            // PowerShell command to find and kill openclaw gateway processes
+            // Note: Use single quotes inside -like pattern for proper escaping
+            const findCmd = "Get-Process -Name 'node' -ErrorAction SilentlyContinue | Where-Object { $_.CommandLine -like '*openclaw*' } | Select-Object -ExpandProperty Id";
+            const pids = execSync(`powershell -NoProfile -Command "${findCmd}"`, { encoding: 'utf-8' }).trim();
+
+            if (pids) {
+                console.log(`   Terminating existing gateway process(es): ${pids.replace(/\n/g, ', ')}...`);
+                // Kill by PID
+                const pidList = pids.split('\n').filter(p => p.trim());
+                for (const pid of pidList) {
+                    try {
+                        execSync(`taskkill /PID ${pid.trim()} /F`, { stdio: 'pipe' });
+                    } catch { /* ignore if process already gone */ }
+                }
+                // Wait a moment for process to terminate
+                execSync('timeout /t 3 /nobreak > nul', { shell: true, stdio: 'ignore' });
+            }
+        } catch { /* no existing processes */ }
+
+        // Step 2: Start new gateway process in background
+        console.log(`   Starting new gateway (logs: ${logPath})...`);
+
+        // Use openclaw CLI to start gateway (more reliable than direct node invocation)
+        const gatewayCmd = join(getHomeDir(), '.openclaw', 'gateway.cmd');
+        const startCmd = `Start-Process -FilePath 'cmd.exe' -ArgumentList '/c ${gatewayCmd}' -WindowStyle Hidden -RedirectStandardOutput '${logPath}' -RedirectStandardError '${join(getTempDir(), 'openclaw-auto-restart.err')}'`;
+        execSync(`powershell -NoProfile -Command "${startCmd}"`, { stdio: 'inherit' });
+        console.log('✅ Gateway restart triggered.');
+
+        // Step 3: Wait and verify
+        setTimeout(() => {
+            try {
+                if (existsSync(logPath)) {
+                    const logs = readFileSync(logPath, 'utf-8');
+                    if (logs.includes('Principles Disciple Plugin registered')) {
+                        console.log('✅ SUCCESS: Principles Disciple plugin registered successfully!');
+                    } else if (logs.includes('failed to load') || logs.includes('Error: Cannot find module')) {
+                        console.error('\n❌ CRITICAL: Gateway started but PD plugin FAILED to load!');
+                        console.error('   Check logs at: ' + logPath);
+                        process.exit(1);
+                    } else {
+                        console.warn('⚠️  Gateway started but PD registration not confirmed in recent logs.');
+                        console.log('   Check logs at: ' + logPath);
+                    }
+                }
+            } catch (e) {
+                console.warn(`⚠️  Post-restart verification skipped: ${e.message}`);
+            }
+        }, 8000);
+
+    } catch (error) {
+        console.error(`\n❌ Failed to restart gateway: ${error.message}`);
+        console.error('   You may need to manually restart OpenClaw Gateway.');
+        process.exit(1);
+    }
+}
+
+/**
+ * Restart Gateway on Linux using systemctl or process management.
+ */
+function restartGatewayLinux() {
+    const logPath = '/tmp/openclaw-auto-restart.log';
+
+    try {
+        // Try systemctl first (Linux systemd)
         try {
             execSync('systemctl --user is-active openclaw-gateway.service', { stdio: 'pipe' });
             console.log('   Restarting via systemctl...');
             execSync('systemctl --user restart openclaw-gateway.service', { stdio: 'inherit' });
             console.log('✅ Gateway restarted via systemctl.');
-            
+
             console.log('   Waiting for Gateway to initialize and load PD plugin (8s)...');
             setTimeout(() => {
                 try {
@@ -608,8 +775,9 @@ function restartGateway() {
                 }
             }, 8000);
             return;
-        } catch { /* ignore */ }
+        } catch { /* systemctl not available, fall through to manual restart */ }
 
+        // Manual process management
         const pids = execSync('pgrep -f "openclaw-gateway|openclaw gateway"', { encoding: 'utf-8' }).trim();
         if (pids) {
             console.log(`   Terminating existing gateway process(es)...`);
@@ -617,11 +785,10 @@ function restartGateway() {
             execSync('sleep 3');
         }
 
-        const logPath = '/tmp/openclaw-auto-restart.log';
         console.log(`   Starting new gateway (logs: ${logPath})...`);
         execSync(`nohup openclaw gateway --force > ${logPath} 2>&1 &`, { stdio: 'ignore' });
         console.log('✅ Gateway restart triggered.');
-        
+
         setTimeout(() => {
             if (existsSync(logPath)) {
                 const logs = readFileSync(logPath, 'utf-8');
@@ -699,9 +866,10 @@ function main() {
     if (existsSync(bootstrapScript)) {
         console.log('\n🧠 Synchronizing principles to active rules (Bootstrap)...');
         try {
-            const targetStateDir = join(process.env.HOME, '.openclaw', 'workspace-main', '.state');
+            const workspaceDir = getConfiguredWorkspaceDir();
+            const targetStateDir = join(workspaceDir, '.state');
             if (existsSync(targetStateDir)) {
-                execSync(`STATE_DIR=${targetStateDir} BOOTSTRAP_LIMIT=100 node scripts/bootstrap-rules.mjs`, { cwd: SOURCE_DIR, stdio: 'inherit' });
+                execSync(`node scripts/bootstrap-rules.mjs`, { cwd: SOURCE_DIR, stdio: 'inherit', env: { ...process.env, STATE_DIR: targetStateDir, BOOTSTRAP_LIMIT: '100' } });
                 console.log('✅ Principles synchronized.');
             }
         } catch (e) {
@@ -713,7 +881,8 @@ function main() {
     if (existsSync(compileScript)) {
         console.log('\n⚙️  Compiling pain-derived principles into rules...');
         try {
-            const targetWorkspaceDir = join(process.env.HOME, '.openclaw', 'workspace-main');
+            const workspaceDir = getConfiguredWorkspaceDir();
+            const targetWorkspaceDir = workspaceDir;
             if (existsSync(targetWorkspaceDir)) {
                 execSync(`node scripts/compile-principles.mjs ${targetWorkspaceDir}`, { cwd: SOURCE_DIR, stdio: 'inherit' });
                 console.log('✅ Principle compilation complete.');
@@ -732,12 +901,6 @@ function main() {
     verifyInstalledFingerprint();
     if (args.dev || args.restart) cleanStaleBackups();
 
-    try {
-        const reloadSignal = join(OPENCLAW_DIR, '.plugin_reload_signal');
-        writeFileSync(reloadSignal, new Date().toISOString(), 'utf-8');
-        console.log(`\n🔔 Reload signal sent to ${reloadSignal}`);
-    } catch { /* ignore */ }
-
     console.log('\n╔════════════════════════════════════════════════════════════╗');
     console.log('║                  ✅ Installation Complete                  ║');
     console.log('╚════════════════════════════════════════════════════════════╝');
@@ -746,6 +909,7 @@ function main() {
         restartGateway();
     } else {
         console.log('\n💡 Restart OpenClaw Gateway to load the new version.');
+        console.log('   (Plugin code changes require a full gateway restart)');
     }
 }
 

package/src/core/bootstrap-rules.ts

@@ -13,8 +13,10 @@
  *   npm run bootstrap-rules                               (production)
  */
 
-import { loadLedger, createRule, updatePrinciple } from './principle-tree-ledger.js';
+import { loadLedger, createRule, updatePrinciple, addPrincipleToLedger } from './principle-tree-ledger.js';
+import type { LedgerPrinciple } from './principle-tree-ledger.js';
 import { loadStore } from './principle-training-state.js';
+import { CORE_THINKING_MODELS } from './init.js';
 
 export interface BootstrapResult {
   principleId: string;
@@ -77,12 +79,47 @@ export function selectPrinciplesForBootstrap(stateDir: string, limit = 3): strin
  * @throws Error if no deterministic principles found
  */
 export function bootstrapRules(stateDir: string, limit = 3): BootstrapResult[] {
+  // Migration: if T-01..T-10 exist in Training Store but not in Ledger Tree, backfill.
+  // This handles workspaces initialized before Ledger Tree was added.
+  const store = loadStore(stateDir);
+  const ledger = loadLedger(stateDir);
+  const hasTrainingT = Object.keys(store).some((id) => id.startsWith('T-'));
+  const hasAnyLedgerT = Object.keys(ledger.tree.principles).some((id) => id.startsWith('T-'));
+  if (hasTrainingT && !hasAnyLedgerT) {
+    console.warn('[bootstrap] Migrating T-01..T-10 from Training Store to Ledger Tree');
+    const now = new Date().toISOString();
+    for (const [id, entry] of Object.entries(store)) {
+      if (!id.startsWith('T-')) continue;
+      const model = CORE_THINKING_MODELS.find((m) => m.id === id);
+      if (!model) continue;
+      const lp: LedgerPrinciple = {
+        id,
+        version: 1,
+        text: model.description,
+        coreAxiomId: id,
+        triggerPattern: '',
+        action: '',
+        status: 'active',
+        priority: 'P1',
+        scope: 'general',
+        evaluability: entry.evaluability,
+        valueScore: 0,
+        adherenceRate: 0,
+        painPreventedCount: 0,
+        derivedFromPainIds: [],
+        ruleIds: [],
+        conflictsWithPrincipleIds: [],
+        createdAt: now,
+        updatedAt: now,
+        suggestedRules: [],
+      };
+      addPrincipleToLedger(stateDir, lp);
+    }
+  }
+
   // Select principles for bootstrap
   const selectedPrincipleIds = selectPrinciplesForBootstrap(stateDir, limit);
 
-  // Load current ledger state
-  const ledger = loadLedger(stateDir);
-
   const results: BootstrapResult[] = [];
 
   for (const principleId of selectedPrincipleIds) {

package/src/core/evolution-hook.ts

@@ -0,0 +1,74 @@
+/**
+ * EvolutionHook interface for the Evolution SDK.
+ *
+ * Provides a callback-based interface for observing evolution lifecycle
+ * events: pain detection, principle creation, and principle promotion.
+ *
+ * Per D-03, this interface contains only the 3 core event methods.
+ * Per D-04, consumers implement the interface directly (no EventEmitter).
+ * Hooks not needed can use the provided noOpEvolutionHook and override
+ * individual methods.
+ */
+import type { PainSignal } from './pain-signal.js';
+
+// ---------------------------------------------------------------------------
+// Event Types
+// ---------------------------------------------------------------------------
+
+/** Event payload for principle creation lifecycle events. */
+export interface PrincipleCreatedEvent {
+  /** Unique principle identifier */
+  id: string;
+  /** Principle text ("When X, then Y.") */
+  text: string;
+  /** What triggered this principle's creation */
+  trigger: string;
+}
+
+/** Event payload for principle promotion lifecycle events. */
+export interface PrinciplePromotedEvent {
+  /** Unique principle identifier */
+  id: string;
+  /** Previous status tier */
+  from: string;
+  /** New status tier */
+  to: string;
+}
+
+// ---------------------------------------------------------------------------
+// EvolutionHook Interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Callback interface for observing evolution lifecycle events.
+ *
+ * Implement all 3 methods, or spread noOpEvolutionHook and override
+ * only the methods you need:
+ *
+ * @example
+ * ```ts
+ * const myHook: EvolutionHook = {
+ *   ...noOpEvolutionHook,
+ *   onPainDetected(signal) { console.log(signal); },
+ * };
+ * ```
+ */
+export interface EvolutionHook {
+  /** Called when a pain signal is detected and recorded. */
+  onPainDetected(signal: PainSignal): void;
+  /** Called when a new principle candidate is created. */
+  onPrincipleCreated(event: PrincipleCreatedEvent): void;
+  /** Called when a principle is promoted to a higher tier. */
+  onPrinciplePromoted(event: PrinciplePromotedEvent): void;
+}
+
+// ---------------------------------------------------------------------------
+// No-op Helper
+// ---------------------------------------------------------------------------
+
+/** No-op implementation -- consumers can spread and override individual methods. */
+export const noOpEvolutionHook: EvolutionHook = {
+  onPainDetected(_signal: PainSignal): void {},
+  onPrincipleCreated(_event: PrincipleCreatedEvent): void {},
+  onPrinciplePromoted(_event: PrinciplePromotedEvent): void {},
+};

package/src/core/file-storage-adapter.ts

@@ -0,0 +1,203 @@
+/**
+ * FileStorageAdapter — file-backed implementation of StorageAdapter.
+ *
+ * Wraps principle-tree-ledger functions with the async StorageAdapter
+ * contract. Uses withLockAsync for thread-safe mutateLedger with
+ * retry with exponential backoff for lock acquisition (5 retries).
+ * Write failures are logged via SystemLogger and re-thrown.
+ *
+ * Guarantees:
+ * - Atomic writes via atomicWriteFileSync (temp + rename)
+ * - Thread-safe concurrent access via file locks
+ * - Consistent read-after-write visibility
+ * - Write failures logged to SystemLogger and re-thrown
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import type { StorageAdapter } from './storage-adapter.js';
+import type { HybridLedgerStore } from './principle-tree-ledger.js';
+import { TREE_NAMESPACE } from './principle-tree-ledger.js';
+import {
+  loadLedger as loadLedgerFromFile,
+  saveLedgerAsync,
+} from './principle-tree-ledger.js';
+import { withLockAsync, type LockOptions, LockAcquisitionError } from '../utils/file-lock.js';
+import { atomicWriteFileSync } from '../utils/io.js';
+import { SystemLogger } from './system-logger.js';
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+/** Maximum retries for lock acquisition in mutateLedger. */
+const MUTATE_RETRY_COUNT = 5;
+
+/** Base delay in ms for exponential backoff between retries. */
+const MUTATE_BACKOFF_BASE_MS = 50;
+
+/** Maximum backoff delay in ms. */
+const MUTATE_BACKOFF_MAX_MS = 500;
+
+const PRINCIPLE_TRAINING_FILE = 'principle_training_state.json';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Serialize the hybrid ledger store to JSON.
+ * Mirrors the unexported serializeLedger from principle-tree-ledger.ts.
+ */
+function serializeStore(store: HybridLedgerStore): string {
+  return JSON.stringify(
+    {
+      ...store.trainingStore,
+      [TREE_NAMESPACE]: {
+        ...store.tree,
+        lastUpdated: new Date().toISOString(),
+      },
+    },
+    null,
+    2,
+  );
+}
+
+/** Ensure the parent directory exists before writing. */
+function ensureParentDir(filePath: string): void {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// FileStorageAdapter
+// ---------------------------------------------------------------------------
+
+/**
+ * File-system backed storage adapter for the principle ledger.
+ *
+ * Delegates read/write operations to principle-tree-ledger while providing
+ * the async StorageAdapter interface. The mutateLedger method uses
+ * withLockAsync with exponential backoff retry for robust concurrent access.
+ */
+export class FileStorageAdapter implements StorageAdapter {
+  private readonly stateDir: string;
+  private readonly workspaceDir: string | undefined;
+
+  constructor(stateDir: string, workspaceDir?: string) {
+    this.stateDir = stateDir;
+    this.workspaceDir = workspaceDir;
+  }
+
+  /** Resolve the ledger file path for this state directory. */
+  private get filePath(): string {
+    return path.join(this.stateDir, PRINCIPLE_TRAINING_FILE);
+  }
+
+  /**
+   * Load the current ledger state from the file system.
+   *
+   * Returns an empty store if no persisted state exists (first run).
+   * Uses the synchronous loadLedger from principle-tree-ledger which
+   * handles missing/corrupted files gracefully.
+   */
+  async loadLedger(): Promise<HybridLedgerStore> {
+    return loadLedgerFromFile(this.stateDir);
+  }
+
+  /**
+   * Persist the full ledger state atomically.
+   *
+   * Delegates to principle-tree-ledger's saveLedgerAsync which uses
+   * withLockAsync internally. Logs failures via SystemLogger.
+   */
+  async saveLedger(store: HybridLedgerStore): Promise<void> {
+    try {
+      await saveLedgerAsync(this.stateDir, store);
+    } catch (err) {
+      SystemLogger.log(
+        this.workspaceDir,
+        'STORAGE_WRITE_FAILED',
+        `FileStorageAdapter.saveLedger failed: ${String(err)}`,
+      );
+      throw err;
+    }
+  }
+
+  /**
+   * Perform a read-modify-write cycle with automatic locking and retry.
+   *
+   * Uses withLockAsync to acquire a file lock, reads the current store,
+   * applies the mutate function, then writes the modified store atomically.
+   * On lock acquisition failure, retries up to MUTATE_RETRY_COUNT (5) times
+   * with exponential backoff + jitter to reduce contention.
+   *
+   * Write failures are logged to SystemLogger and re-thrown so callers
+   * can decide how to handle persistence errors.
+   */
+  async mutateLedger<T>(mutate: (store: HybridLedgerStore) => T | Promise<T>): Promise<T> {
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt < MUTATE_RETRY_COUNT; attempt++) {
+      try {
+        const lockOptions: LockOptions = {
+          maxRetries: 3,
+          baseRetryDelayMs: 10,
+          maxRetryDelayMs: 200,
+          lockStaleMs: 10_000,
+        };
+
+        const ledgerPath = this.filePath;
+
+        return await withLockAsync(ledgerPath, async () => {
+          const store = loadLedgerFromFile(this.stateDir);
+          const result = await mutate(store);
+
+          // Write directly — we already hold the lock, so we must NOT
+          // call saveLedger/saveLedgerAsync (they try to acquire the same lock).
+          try {
+            ensureParentDir(ledgerPath);
+            atomicWriteFileSync(ledgerPath, serializeStore(store));
+          } catch (writeErr) {
+            SystemLogger.log(
+              this.workspaceDir,
+              'STORAGE_WRITE_FAILED',
+              `FileStorageAdapter.mutateLedger write failed: ${String(writeErr)}`,
+            );
+            throw writeErr;
+          }
+
+          return result;
+        }, lockOptions);
+      } catch (err) {
+        lastError = err as Error;
+
+        // Only retry on lock acquisition errors
+        if (err instanceof LockAcquisitionError && attempt < MUTATE_RETRY_COUNT - 1) {
+          const delay = Math.min(
+            MUTATE_BACKOFF_BASE_MS * Math.pow(2, attempt),
+            MUTATE_BACKOFF_MAX_MS,
+          );
+          // Add jitter (0-20%) to avoid thundering herd
+          const jitter = delay * 0.2 * Math.random();
+          const totalDelay = Math.floor(delay + jitter);
+
+          await new Promise((resolve) => setTimeout(resolve, totalDelay));
+          continue;
+        }
+
+        // Non-retryable error or exhausted retries
+        SystemLogger.log(
+          this.workspaceDir,
+          'STORAGE_MUTATE_FAILED',
+          `FileStorageAdapter.mutateLedger failed after ${attempt + 1} attempts: ${String(err)}`,
+        );
+        throw err;
+      }
+    }
+
+    // Should not reach here, but satisfy the type checker
+    throw lastError ?? new Error('FileStorageAdapter.mutateLedger: unexpected state');
+  }
+}