agents-library 0.1.0 → 0.1.2

package/dist/shadow-agent-factory.js

@@ -25,7 +25,6 @@
  * @module shadow-agent-factory
  */
 import { KadiClient, z } from '@kadi.build/core';
-import chokidar from 'chokidar';
 import fs from 'fs';
 import path from 'path';
 import { execSync } from 'child_process';
@@ -182,28 +181,15 @@ export class BaseShadowAgent {
      */
     usesBaseAgent;
     /**
-     * Filesystem watcher instance for monitoring worker worktree
-     *
-     * Monitors file operations (create, modify, delete) in worker worktree.
-     * Null until start() is called.
+     * Handler reference for broker file.changed events.
+     * Stored so we can unsubscribe on stop().
      */
-    fsWatcher = null;
+    fileEventHandler = null;
     /**
-     * Git ref watcher instance for monitoring worker branch commits
-     *
-     * Watches .git/refs/heads/{workerBranch} file for commit SHA changes.
-     * Uses fs.watch (not chokidar) for lightweight ref monitoring.
-     * Null until start() is called.
-     */
-    refWatcher = null;
-    /**
-     * Previous commit SHA from worker branch
-     *
-     * Stores last known commit SHA to detect actual commit changes.
-     * Used to differentiate real commits from other ref updates.
-     * Null until first commit is detected.
+     * Native ability-file-local instance for in-process file operations.
+     * Set via setNativeFileLocal() after loadNative in the consuming agent.
      */
-    previousCommitSha = null;
+    nativeFileLocal = null;
     /**
      * Set of changed file paths awaiting backup processing
      *
@@ -214,13 +200,6 @@ export class BaseShadowAgent {
      * Value: Debounce timeout handle
      */
     debounceMap = new Map();
-    /**
-     * Debounce timeout for git ref watcher
-     *
-     * Stores timeout handle for debouncing ref change events.
-     * Prevents processing rapid ref updates.
-     */
-    refDebounceTimeout = null;
     /**
      * Create a new BaseShadowAgent instance
      *
@@ -259,7 +238,7 @@ export class BaseShadowAgent {
         if (baseAgent) {
             this.client = baseAgent.client;
             this.usesBaseAgent = true;
-            logger.info(MODULE_AGENT, '   ✅ Using BaseAgent client (connection managed externally)', timer.elapsed('shadow-factory'));
+            logger.info(MODULE_AGENT, '   Using BaseAgent client (connection managed externally)', timer.elapsed('shadow-factory'));
         }
         else {
             this.client = new KadiClient({
@@ -272,13 +251,20 @@ export class BaseShadowAgent {
             });
             this.usesBaseAgent = false;
         }
-        logger.info(MODULE_AGENT, `🔧 BaseShadowAgent initialized for role: ${this.role}`, timer.elapsed('shadow-factory'));
+        logger.info(MODULE_AGENT, `BaseShadowAgent initialized for role: ${this.role}`, timer.elapsed('shadow-factory'));
         logger.info(MODULE_AGENT, `   Worker worktree: ${this.workerWorktreePath}`, timer.elapsed('shadow-factory'));
         logger.info(MODULE_AGENT, `   Shadow worktree: ${this.shadowWorktreePath}`, timer.elapsed('shadow-factory'));
         logger.info(MODULE_AGENT, `   Worker branch: ${this.workerBranch}`, timer.elapsed('shadow-factory'));
         logger.info(MODULE_AGENT, `   Shadow branch: ${this.shadowBranch}`, timer.elapsed('shadow-factory'));
         logger.info(MODULE_AGENT, `   Debounce delay: ${this.debounceMs}ms`, timer.elapsed('shadow-factory'));
     }
+    /**
+     * Set native ability-file-local for in-process file operations.
+     * Call this after loadNative('ability-file-local') in the consuming agent.
+     */
+    setNativeFileLocal(native) {
+        this.nativeFileLocal = native;
+    }
     /**
      * Start the shadow agent
      *
@@ -302,29 +288,26 @@ export class BaseShadowAgent {
      * ```
      */
     async start() {
-        logger.info(MODULE_AGENT, `🚀 Starting shadow agent for role: ${this.role}`, timer.elapsed('shadow-factory'));
+        logger.info(MODULE_AGENT, `Starting shadow agent for role: ${this.role}`, timer.elapsed('shadow-factory'));
         // Connect to KĀDI broker (skip if BaseAgent manages connection)
         if (this.usesBaseAgent) {
-            logger.info(MODULE_AGENT, '   ✅ Broker connection managed by BaseAgent (skipping)', timer.elapsed('shadow-factory'));
+            logger.info(MODULE_AGENT, '   Broker connection managed by BaseAgent (skipping)', timer.elapsed('shadow-factory'));
         }
         else {
             logger.info(MODULE_AGENT, '   → Connecting to KĀDI broker...', timer.elapsed('shadow-factory'));
             try {
                 await this.client.connect();
-                logger.info(MODULE_AGENT, '   ✅ Connected to KĀDI broker', timer.elapsed('shadow-factory'));
+                logger.info(MODULE_AGENT, '   Connected to KĀDI broker', timer.elapsed('shadow-factory'));
             }
             catch (error) {
-                logger.error(MODULE_AGENT, '❌ Broker connection error', timer.elapsed('shadow-factory'), error);
+                logger.error(MODULE_AGENT, 'Broker connection error', timer.elapsed('shadow-factory'), error);
                 process.exit(1);
             }
         }
-        // Setup filesystem watcher for worker worktree
-        await this.setupFilesystemWatcher();
-        logger.info(MODULE_AGENT, '✅ Filesystem watcher initialized', timer.elapsed('shadow-factory'));
-        // Setup git ref watcher for worker branch
-        await this.setupGitRefWatcher();
-        logger.info(MODULE_AGENT, '✅ Git ref watcher initialized', timer.elapsed('shadow-factory'));
-        logger.info(MODULE_AGENT, '✅ Shadow agent started and monitoring', timer.elapsed('shadow-factory'));
+        // Subscribe to file.changed broker events (emitted by ability-file-local)
+        await this.setupBrokerFileEventSubscription();
+        logger.info(MODULE_AGENT, 'Broker file event subscription active', timer.elapsed('shadow-factory'));
+        logger.info(MODULE_AGENT, 'Shadow agent started and monitoring via broker events', timer.elapsed('shadow-factory'));
     }
     /**
      * Stop the shadow agent
@@ -346,284 +329,111 @@ export class BaseShadowAgent {
      * ```
      */
     async stop() {
-        logger.info(MODULE_AGENT, `🛑 Stopping shadow agent for role: ${this.role}`, timer.elapsed('shadow-factory'));
-        // Stop filesystem watcher
-        if (this.fsWatcher) {
-            logger.info(MODULE_AGENT, '🛑 Stopping filesystem watcher...', timer.elapsed('shadow-factory'));
-            await this.fsWatcher.close();
-            this.fsWatcher = null;
-            logger.info(MODULE_AGENT, '✅ Filesystem watcher stopped', timer.elapsed('shadow-factory'));
-        }
-        // Stop git ref watcher
-        if (this.refWatcher) {
-            logger.info(MODULE_AGENT, '🛑 Stopping git ref watcher...', timer.elapsed('shadow-factory'));
-            this.refWatcher.close();
-            this.refWatcher = null;
-            logger.info(MODULE_AGENT, '✅ Git ref watcher stopped', timer.elapsed('shadow-factory'));
-        }
-        // Clear ref debounce timeout
-        if (this.refDebounceTimeout) {
-            logger.info(MODULE_AGENT, '🛑 Clearing ref debounce timeout...', timer.elapsed('shadow-factory'));
-            clearTimeout(this.refDebounceTimeout);
-            this.refDebounceTimeout = null;
-            logger.info(MODULE_AGENT, '✅ Ref debounce timeout cleared', timer.elapsed('shadow-factory'));
+        logger.info(MODULE_AGENT, `Stopping shadow agent for role: ${this.role}`, timer.elapsed('shadow-factory'));
+        // Unsubscribe from broker file events
+        if (this.fileEventHandler) {
+            logger.info(MODULE_AGENT, 'Unsubscribing from file.changed events...', timer.elapsed('shadow-factory'));
+            try {
+                await this.client.unsubscribe('file.changed', this.fileEventHandler);
+            }
+            catch {
+                // Best-effort unsubscribe — may not be supported in all KadiClient versions
+            }
+            this.fileEventHandler = null;
+            logger.info(MODULE_AGENT, 'File event subscription removed', timer.elapsed('shadow-factory'));
         }
         // Clear all pending debounce timers
         if (this.debounceMap.size > 0) {
-            logger.info(MODULE_AGENT, `🛑 Clearing ${this.debounceMap.size} pending debounce timers...`, timer.elapsed('shadow-factory'));
+            logger.info(MODULE_AGENT, `Clearing ${this.debounceMap.size} pending debounce timers...`, timer.elapsed('shadow-factory'));
             for (const timeout of this.debounceMap.values()) {
                 clearTimeout(timeout);
             }
             this.debounceMap.clear();
-            logger.info(MODULE_AGENT, '✅ Debounce timers cleared', timer.elapsed('shadow-factory'));
+            logger.info(MODULE_AGENT, 'Debounce timers cleared', timer.elapsed('shadow-factory'));
         }
         // Disconnect KĀDI client (skip if BaseAgent manages connection)
         if (this.usesBaseAgent) {
-            logger.info(MODULE_AGENT, '   ✅ Broker disconnection managed by BaseAgent (skipping)', timer.elapsed('shadow-factory'));
+            logger.info(MODULE_AGENT, '   Broker disconnection managed by BaseAgent (skipping)', timer.elapsed('shadow-factory'));
         }
         else {
             logger.info(MODULE_AGENT, '   → Disconnecting from KĀDI broker...', timer.elapsed('shadow-factory'));
             await this.client.disconnect();
-            logger.info(MODULE_AGENT, '   ✅ Disconnected from KĀDI broker', timer.elapsed('shadow-factory'));
+            logger.info(MODULE_AGENT, '   Disconnected from KĀDI broker', timer.elapsed('shadow-factory'));
         }
-        logger.info(MODULE_AGENT, '✅ Shadow agent stopped', timer.elapsed('shadow-factory'));
+        logger.info(MODULE_AGENT, 'Shadow agent stopped', timer.elapsed('shadow-factory'));
     }
     /**
-     * Setup filesystem watcher for worker worktree
-     *
-     * Monitors worker worktree for file operations (create, modify, delete) using chokidar.
-     * File changes are debounced and stored for batch backup processing.
-     *
-     * Configuration:
-     * - Watches: config.workerWorktreePath
-     * - Excludes: .git directory, node_modules, .env files
-     * - Debounce: config.debounceMs (default: 1000ms)
-     * - Stability threshold: Waits for file writes to complete
+     * Subscribe to file.changed broker events from ability-file-local
      *
-     * Event Handling:
-     * - 'add': File created in worktree
-     * - 'change': Existing file modified
-     * - 'unlink': File deleted from worktree
-     * - 'error': Watcher errors (logged but non-fatal)
-     * - 'ready': Watcher initialization complete
+     * Instead of using chokidar directly (unreliable on /mnt/c/ in WSL containers),
+     * the shadow agent subscribes to `file.changed` events published by ability-file-local
+     * which runs on the host where filesystem events work natively.
      *
-     * Debouncing Strategy:
-     * - Stores timeout handle in debounceMap for each file
-     * - Clears previous timeout if file changes again before debounce completes
-     * - Only processes file after debounceMs of inactivity
-     * - Prevents rapid-fire commits for the same file
+     * Event payload from ability-file-local:
+     *   { watchId: string, event: 'add'|'change'|'unlink', path: string }
      *
-     * @throws {Error} If watcher initialization fails
-     *
-     * @example
-     * ```typescript
-     * await this.setupFilesystemWatcher();
-     * // Watcher is now monitoring worker worktree for file changes
-     * ```
+     * The shadow agent filters events to only process those matching its workerWorktreePath,
+     * then debounces and creates shadow backup commits.
      */
-    async setupFilesystemWatcher() {
-        logger.info(MODULE_AGENT, `👁️  Setting up filesystem watcher: ${this.workerWorktreePath}`, timer.elapsed('shadow-factory'));
-        // Create chokidar watcher with configuration
-        this.fsWatcher = chokidar.watch(this.workerWorktreePath, {
-            persistent: true,
-            ignoreInitial: true, // Don't trigger for existing files on startup
-            ignored: [
-                '**/node_modules/**',
-                '**/.git/**',
-                '**/.git', // Also ignore .git file (for worktrees)
-                '**/.env',
-                '**/.env.*'
-            ],
-            awaitWriteFinish: {
-                stabilityThreshold: this.debounceMs,
-                pollInterval: 100
-            }
-        });
-        // Event: File created
-        this.fsWatcher.on('add', (filePath) => {
-            logger.info(MODULE_AGENT, `➕ File created: ${filePath}`, timer.elapsed('shadow-factory'));
-            // Debounce to avoid rapid-fire commits
-            if (this.debounceMap.has(filePath)) {
-                clearTimeout(this.debounceMap.get(filePath));
-            }
-            const timeout = setTimeout(async () => {
-                logger.info(MODULE_AGENT, `📝 Processing created file: ${filePath}`, timer.elapsed('shadow-factory'));
-                const relativePath = path.relative(this.workerWorktreePath, filePath);
-                await this.createShadowBackup('Created', relativePath);
-                this.debounceMap.delete(filePath);
-            }, this.debounceMs);
-            this.debounceMap.set(filePath, timeout);
-        });
-        // Event: File modified
-        this.fsWatcher.on('change', (filePath) => {
-            logger.info(MODULE_AGENT, `✏️  File modified: ${filePath}`, timer.elapsed('shadow-factory'));
-            // Debounce to avoid rapid-fire commits
-            if (this.debounceMap.has(filePath)) {
-                clearTimeout(this.debounceMap.get(filePath));
-            }
-            const timeout = setTimeout(async () => {
-                logger.info(MODULE_AGENT, `📝 Processing modified file: ${filePath}`, timer.elapsed('shadow-factory'));
-                const relativePath = path.relative(this.workerWorktreePath, filePath);
-                await this.createShadowBackup('Modified', relativePath);
-                this.debounceMap.delete(filePath);
-            }, this.debounceMs);
-            this.debounceMap.set(filePath, timeout);
-        });
-        // Event: File deleted
-        this.fsWatcher.on('unlink', (filePath) => {
-            logger.info(MODULE_AGENT, `🗑️  File deleted: ${filePath}`, timer.elapsed('shadow-factory'));
-            // Debounce to avoid rapid-fire commits
-            if (this.debounceMap.has(filePath)) {
-                clearTimeout(this.debounceMap.get(filePath));
-            }
-            const timeout = setTimeout(async () => {
-                logger.info(MODULE_AGENT, `📝 Processing deleted file: ${filePath}`, timer.elapsed('shadow-factory'));
+    async setupBrokerFileEventSubscription() {
+        logger.info(MODULE_AGENT, `Subscribing to file.changed broker events for: ${this.workerWorktreePath}`, timer.elapsed('shadow-factory'));
+        const handler = async (event) => {
+            try {
+                const data = (event?.data || event);
+                if (!data.path || !data.event)
+                    return;
+                const filePath = data.path;
+                // Filter: only process events for our worker worktree
+                // Normalize both paths for comparison (handle Windows/Unix path differences)
+                const normalizedFile = filePath.replace(/\\/g, '/').toLowerCase();
+                const normalizedWorktree = this.workerWorktreePath.replace(/\\/g, '/').toLowerCase();
+                if (!normalizedFile.startsWith(normalizedWorktree))
+                    return;
+                // Skip .git, node_modules, .env files
                 const relativePath = path.relative(this.workerWorktreePath, filePath);
-                await this.createShadowBackup('Deleted', relativePath);
-                this.debounceMap.delete(filePath);
-            }, this.debounceMs);
-            this.debounceMap.set(filePath, timeout);
-        });
-        // Event: Watcher error
-        this.fsWatcher.on('error', (error) => {
-            logger.error(MODULE_AGENT, '❌ Filesystem watcher error', timer.elapsed('shadow-factory'), error);
-            // Non-fatal - watcher continues operating
-        });
-        // Event: Watcher ready
-        this.fsWatcher.on('ready', () => {
-            logger.info(MODULE_AGENT, '✅ Filesystem watcher ready', timer.elapsed('shadow-factory'));
-        });
-    }
-    /**
-     * Setup git ref watcher for worker branch commits
-     *
-     * Monitors worker branch ref file (.git/refs/heads/{workerBranch}) for commit SHA changes
-     * using fs.watch. Detects new commits and triggers createShadowBackup after debounce period.
-     *
-     * Architecture:
-     * - Uses fs.watch (not chokidar) for lightweight ref monitoring
-     * - Reads commit SHA from ref file on each change
-     * - Compares with previousCommitSha to detect actual commits
-     * - Debounces to handle rapid ref updates (e.g., during rebase)
-     * - Triggers backup only for real commit changes
-     *
-     * Ref File Location:
-     * - {workerWorktreePath}/.git/refs/heads/{workerBranch}
-     * - Contains commit SHA as plain text (40 hex characters)
-     * - Updated by git on each commit to branch
-     *
-     * Change Detection Strategy:
-     * 1. fs.watch fires on any ref file modification
-     * 2. Read current SHA from ref file
-     * 3. Compare with previousCommitSha
-     * 4. If different, debounce and trigger backup
-     * 5. Update previousCommitSha for next comparison
-     *
-     * Debouncing:
-     * - Uses config.debounceMs delay (default: 1000ms)
-     * - Clears previous timeout if ref changes again
-     * - Prevents multiple backups during rapid commits
-     *
-     * @throws {Error} If ref file doesn't exist or can't be watched
-     *
-     * @example
-     * ```typescript
-     * await this.setupGitRefWatcher();
-     * // Watcher is now monitoring worker branch for commits
-     * ```
-     */
-    async setupGitRefWatcher() {
-        // Construct path to worker branch ref file
-        // Handle both regular repos and git worktrees
-        let gitDir = path.join(this.workerWorktreePath, '.git');
-        // Check if .git is a file (worktree) or directory (regular repo)
-        if (fs.existsSync(gitDir)) {
-            const gitStat = fs.statSync(gitDir);
-            if (gitStat.isFile()) {
-                // This is a worktree - read the .git file to get actual git directory
-                const gitFileContent = fs.readFileSync(gitDir, 'utf-8').trim();
-                const match = gitFileContent.match(/^gitdir:\s*(.+)$/);
-                if (match) {
-                    gitDir = match[1].trim();
-                    logger.info(MODULE_AGENT, `📁 Detected git worktree, actual git dir: ${gitDir}`, timer.elapsed('shadow-factory'));
-                    // For worktrees, refs are stored in the common (main) git directory
-                    // Read the commondir file to get the path to the main git directory
-                    const commondirPath = path.join(gitDir, 'commondir');
-                    if (fs.existsSync(commondirPath)) {
-                        const commondirContent = fs.readFileSync(commondirPath, 'utf-8').trim();
-                        // commondir contains a relative path to the main git directory
-                        const mainGitDir = path.resolve(gitDir, commondirContent);
-                        logger.info(MODULE_AGENT, `📁 Worktree refs stored in common dir: ${mainGitDir}`, timer.elapsed('shadow-factory'));
-                        gitDir = mainGitDir;
-                    }
-                }
-            }
-        }
-        const refFilePath = path.join(gitDir, 'refs/heads', this.workerBranch);
-        logger.info(MODULE_AGENT, `👁️  Setting up git ref watcher: ${refFilePath}`, timer.elapsed('shadow-factory'));
-        // Verify ref file exists before watching
-        if (!fs.existsSync(refFilePath)) {
-            logger.warn(MODULE_AGENT, `⚠️  Ref file not found: ${refFilePath}`, timer.elapsed('shadow-factory'));
-            logger.warn(MODULE_AGENT, `   Worker branch may not exist yet. Skipping ref watcher setup.`, timer.elapsed('shadow-factory'));
-            return;
-        }
-        // Read initial commit SHA
-        try {
-            this.previousCommitSha = fs.readFileSync(refFilePath, 'utf-8').trim();
-            logger.info(MODULE_AGENT, `📋 Initial commit SHA: ${this.previousCommitSha.substring(0, 7)}`, timer.elapsed('shadow-factory'));
-        }
-        catch (error) {
-            logger.error(MODULE_AGENT, `❌ Failed to read initial commit SHA: ${error.message}`, timer.elapsed('shadow-factory'), error);
-            this.previousCommitSha = null;
-        }
-        // Setup fs.watch for ref file
-        try {
-            this.refWatcher = fs.watch(refFilePath, (eventType, _filename) => {
-                // Handle 'change' and 'rename' events (rename can occur during git operations)
-                if (eventType !== 'change' && eventType !== 'rename') {
+                if (relativePath.startsWith('.git') ||
+                    relativePath.includes('node_modules') ||
+                    relativePath.startsWith('.env'))
                     return;
+                const eventType = data.event; // 'add' | 'change' | 'unlink'
+                const operation = eventType === 'add' ? 'Created'
+                    : eventType === 'unlink' ? 'Deleted'
+                        : 'Modified';
+                logger.info(MODULE_AGENT, `📁 Broker file event: ${operation} ${relativePath}`, timer.elapsed('shadow-factory'));
+                // Debounce to avoid rapid-fire commits
+                if (this.debounceMap.has(filePath)) {
+                    clearTimeout(this.debounceMap.get(filePath));
                 }
-                logger.info(MODULE_AGENT, `🔄 Git ref change detected: ${eventType}`, timer.elapsed('shadow-factory'));
-                // Clear previous debounce timeout
-                if (this.refDebounceTimeout) {
-                    clearTimeout(this.refDebounceTimeout);
-                }
-                // Debounce to handle rapid ref updates
-                this.refDebounceTimeout = setTimeout(async () => {
-                    try {
-                        // Read current commit SHA from ref file
-                        const currentSha = fs.readFileSync(refFilePath, 'utf-8').trim();
-                        // Check if SHA actually changed (ignore non-commit ref updates)
-                        if (currentSha === this.previousCommitSha) {
-                            logger.info(MODULE_AGENT, `ℹ️  Ref updated but SHA unchanged - skipping`, timer.elapsed('shadow-factory'));
-                            return;
-                        }
-                        logger.info(MODULE_AGENT, `🔄 Worker commit detected on ${this.workerBranch}`, timer.elapsed('shadow-factory'));
-                        logger.info(MODULE_AGENT, `   Previous SHA: ${this.previousCommitSha?.substring(0, 7) || 'none'}`, timer.elapsed('shadow-factory'));
-                        logger.info(MODULE_AGENT, `   Current SHA:  ${currentSha.substring(0, 7)}`, timer.elapsed('shadow-factory'));
-                        // Update tracked SHA
-                        this.previousCommitSha = currentSha;
-                        // Trigger shadow backup for commit
-                        await this.createShadowBackup('COMMIT', `Commit ${currentSha.substring(0, 7)}`);
-                    }
-                    catch (error) {
-                        logger.error(MODULE_AGENT, `❌ Failed to process ref change: ${error.message}`, timer.elapsed('shadow-factory'), error);
-                        // Non-fatal - watcher continues operating
-                    }
+                const timeout = setTimeout(async () => {
+                    logger.info(MODULE_AGENT, `Processing ${operation.toLowerCase()} file: ${relativePath}`, timer.elapsed('shadow-factory'));
+                    await this.createShadowBackup(operation, relativePath);
+                    this.debounceMap.delete(filePath);
                 }, this.debounceMs);
-            });
-            logger.info(MODULE_AGENT, '✅ Git ref watcher ready', timer.elapsed('shadow-factory'));
+                this.debounceMap.set(filePath, timeout);
+            }
+            catch (err) {
+                logger.error(MODULE_AGENT, `Error processing file.changed event: ${err.message}`, timer.elapsed('shadow-factory'), err);
+            }
+        };
+        this.fileEventHandler = handler;
+        await this.client.subscribe('file.changed', handler);
+        logger.info(MODULE_AGENT, 'Subscribed to file.changed broker events', timer.elapsed('shadow-factory'));
+        // Invoke ability-file-local's watch_folder to start emitting file.changed events
+        if (this.nativeFileLocal) {
+            try {
+                await this.nativeFileLocal.invoke('watch_folder', {
+                    folderPath: this.workerWorktreePath,
+                    watchId: `shadow-${this.role}`,
+                });
+                logger.info(MODULE_AGENT, `Started file watcher via native ability-file-local for: ${this.workerWorktreePath}`, timer.elapsed('shadow-factory'));
+            }
+            catch (err) {
+                logger.warn(MODULE_AGENT, `Could not start native file watcher: ${err.message}`, timer.elapsed('shadow-factory'));
+            }
         }
-        catch (error) {
-            logger.error(MODULE_AGENT, `❌ Failed to setup git ref watcher: ${error.message}`, timer.elapsed('shadow-factory'), error);
-            this.refWatcher = null;
-            // Non-fatal - agent continues with filesystem watching only
+        else {
+            logger.warn(MODULE_AGENT, 'ability-file-local not loaded natively — file watcher disabled (broker fallback not available)', timer.elapsed('shadow-factory'));
         }
-        // Handle watcher errors
-        this.refWatcher?.on('error', (error) => {
-            logger.error(MODULE_AGENT, '❌ Git ref watcher error', timer.elapsed('shadow-factory'), error);
-            // Non-fatal - watcher may auto-recover
-        });
     }
     /**
      * Create shadow backup commit
@@ -650,13 +460,13 @@ export class BaseShadowAgent {
         logger.info(MODULE_AGENT, `📦 Creating shadow backup: ${operation} - ${fileName}`, timer.elapsed('shadow-factory'));
         // Check circuit breaker state before attempting git operations
         if (this.checkCircuitBreaker()) {
-            logger.warn(MODULE_AGENT, `⚠️  Circuit breaker open - skipping backup operation`, timer.elapsed('shadow-factory'));
+            logger.warn(MODULE_AGENT, `Circuit breaker open - skipping backup operation`, timer.elapsed('shadow-factory'));
             return;
         }
         try {
             // For COMMIT operations, parse worker commit and copy changed files
             if (operation === 'COMMIT') {
-                logger.info(MODULE_AGENT, `📋 Processing worker commit mirror...`, timer.elapsed('shadow-factory'));
+                logger.info(MODULE_AGENT, `Processing worker commit mirror...`, timer.elapsed('shadow-factory'));
                 // Step 1: Get latest commit hash from worker worktree
                 const commitHash = execSync('git log -1 --format=%H', {
                     cwd: this.workerWorktreePath,
@@ -709,7 +519,7 @@ export class BaseShadowAgent {
                     }
                     catch (copyError) {
                         // File may have been deleted - that's ok, git will handle it
-                        logger.info(MODULE_AGENT, `   ℹ️  Could not copy ${file}: ${copyError.message}`, timer.elapsed('shadow-factory'));
+                        logger.info(MODULE_AGENT, `   Could not copy ${file}: ${copyError.message}`, timer.elapsed('shadow-factory'));
                     }
                 }
                 // Step 5: Stage all changes in shadow worktree
@@ -721,7 +531,7 @@ export class BaseShadowAgent {
                 try {
                     execSync('git diff --cached --quiet', { cwd: this.shadowWorktreePath });
                     // Exit code 0 = nothing staged — FS watcher already backed up this change
-                    logger.info(MODULE_AGENT, `ℹ️  No new changes to commit (already backed up by filesystem watcher)`, timer.elapsed('shadow-factory'));
+                    logger.info(MODULE_AGENT, `No new changes to commit (already backed up by filesystem watcher)`, timer.elapsed('shadow-factory'));
                     this.recordGitSuccess();
                     await this.publishBackupStatus(true, changedFiles, 'mirror-commit-skipped');
                     return;
@@ -740,7 +550,7 @@ export class BaseShadowAgent {
                     cwd: this.shadowWorktreePath,
                     encoding: 'utf-8'
                 }).trim();
-                logger.info(MODULE_AGENT, `✅ Shadow commit created: ${shadowCommitHash.substring(0, 7)}`, timer.elapsed('shadow-factory'));
+                logger.info(MODULE_AGENT, `Shadow commit created: ${shadowCommitHash.substring(0, 7)}`, timer.elapsed('shadow-factory'));
                 // Record success and reset failure count
                 this.recordGitSuccess();
                 // Publish backup success event using standardized method
@@ -748,7 +558,7 @@ export class BaseShadowAgent {
             }
             else {
                 // For file operations (Created, Modified, Deleted), handle individual file
-                logger.info(MODULE_AGENT, `📋 Processing file operation: ${operation} - ${fileName}`, timer.elapsed('shadow-factory'));
+                logger.info(MODULE_AGENT, `Processing file operation: ${operation} - ${fileName}`, timer.elapsed('shadow-factory'));
                 const srcPath = path.join(this.workerWorktreePath, fileName);
                 const destPath = path.join(this.shadowWorktreePath, fileName);
                 // Create destination directory if needed
@@ -783,7 +593,7 @@ export class BaseShadowAgent {
                 try {
                     execSync('git diff --cached --quiet', { cwd: this.shadowWorktreePath });
                     // Exit code 0 = nothing staged — content is identical to HEAD
-                    logger.info(MODULE_AGENT, `ℹ️  No new changes to commit (file unchanged)`, timer.elapsed('shadow-factory'));
+                    logger.info(MODULE_AGENT, `No new changes to commit (file unchanged)`, timer.elapsed('shadow-factory'));
                     this.recordGitSuccess();
                     await this.publishBackupStatus(true, [fileName], `file-${operation.toLowerCase()}-skipped`);
                     return;
@@ -802,7 +612,7 @@ export class BaseShadowAgent {
                     cwd: this.shadowWorktreePath,
                     encoding: 'utf-8'
                 }).trim();
-                logger.info(MODULE_AGENT, `✅ Shadow backup commit created: ${commitHash.substring(0, 7)}`, timer.elapsed('shadow-factory'));
+                logger.info(MODULE_AGENT, `Shadow backup commit created: ${commitHash.substring(0, 7)}`, timer.elapsed('shadow-factory'));
                 // Record success and reset failure count
                 this.recordGitSuccess();
                 // Publish backup success event using standardized method
@@ -810,7 +620,7 @@ export class BaseShadowAgent {
             }
         }
         catch (error) {
-            logger.error(MODULE_AGENT, `❌ Shadow backup failed: ${error.message}`, timer.elapsed('shadow-factory'), error);
+            logger.error(MODULE_AGENT, `Shadow backup failed: ${error.message}`, timer.elapsed('shadow-factory'), error);
             // Record failure and potentially open circuit breaker
             this.recordGitFailure('createShadowBackup', error);
             // Only publish failure event if circuit is not open (avoid spam)
@@ -860,7 +670,7 @@ export class BaseShadowAgent {
         }
         // Publish event using KadiClient
         await this.client.publish(topic, payload, { broker: 'default', network: 'global' });
-        logger.info(MODULE_AGENT, `📤 Published backup ${success ? 'success' : 'failure'} event to ${topic}`, timer.elapsed('shadow-factory'));
+        logger.info(MODULE_AGENT, `Published backup ${success ? 'success' : 'failure'} event to ${topic}`, timer.elapsed('shadow-factory'));
     }
     /**
      * Check circuit breaker state for git operations
@@ -892,7 +702,7 @@ export class BaseShadowAgent {
      */
     recordGitFailure(operation, error) {
         this.gitFailureCount++;
-        logger.error(MODULE_AGENT, `❌ Git operation failed (${this.gitFailureCount}/${this.MAX_GIT_FAILURES}): ${operation}`, timer.elapsed('shadow-factory'), error);
+        logger.error(MODULE_AGENT, `Git operation failed (${this.gitFailureCount}/${this.MAX_GIT_FAILURES}): ${operation}`, timer.elapsed('shadow-factory'), error);
         if (this.gitFailureCount >= this.MAX_GIT_FAILURES) {
             this.gitCircuitOpen = true;
             logger.error(MODULE_AGENT, `🚨 Circuit breaker opened - too many git failures`, timer.elapsed('shadow-factory'));
@@ -900,7 +710,7 @@ export class BaseShadowAgent {
             setTimeout(() => {
                 this.gitCircuitOpen = false;
                 this.gitFailureCount = 0;
-                logger.info(MODULE_AGENT, `🔄 Circuit breaker reset - retrying git operations`, timer.elapsed('shadow-factory'));
+                logger.info(MODULE_AGENT, `Circuit breaker reset - retrying git operations`, timer.elapsed('shadow-factory'));
             }, this.CIRCUIT_RESET_TIME);
         }
     }
@@ -947,7 +757,7 @@ export class BaseShadowAgent {
  *   debounceMs: 2000 // optional
  * };
  *
- * ShadowAgentConfigSchema.parse(validConfig); // ✅ Passes validation
+ * ShadowAgentConfigSchema.parse(validConfig); // Passes validation
  * ```
  */
 export const ShadowAgentConfigSchema = z.object({
@@ -1015,13 +825,13 @@ export const ShadowAgentConfigSchema = z.object({
  * ```typescript
  * try {
  *   const agent = ShadowAgentFactory.createAgent({
- *     role: '', // ❌ Empty role will fail validation
+ *     role: '', // Empty role will fail validation
  *     workerWorktreePath: 'C:/p4/Personal/SD/agent-playground-artist',
  *     shadowWorktreePath: 'C:/p4/Personal/SD/shadow-artist-backup',
  *     workerBranch: 'main',
  *     shadowBranch: 'shadow-main',
  *     brokerUrl: 'ws://localhost:8080/kadi',
- *     networks: []  // ❌ Empty networks array will fail validation
+ *     networks: []  // Empty networks array will fail validation
  *   });
  * } catch (error) {
  *   console.error('Configuration validation failed:', error.message);