cli: implement local→CouchDB file watching via chokidar

- Add chokidar ^4.0.0 as dependency (root package.json, runtime-package.json)
- Mark chokidar as external in vite.config.ts (not bundled, loaded at runtime)
- Implement CLIWatchAdapter.beginWatch() with chokidar:
  - ignoreInitial: true (startup files handled by mirror scan)
  - awaitWriteFinish to prevent partial-write events
  - Excludes dotfiles and .livesync/ directory at watcher level
  - Maps add/change/unlink/addDir/unlinkDir to IStorageEventWatchHandlers
  - Fatal error handler: logs clearly and releases watcher resources
- Add close() to CLIWatchAdapter, StorageEventManagerCLI for clean shutdown
- Register onUnload hook in CLIServiceModules to close watcher on shutdown

src/apps/cli/managers/CLIStorageEventManagerAdapter.ts

@@ -11,8 +11,10 @@ import type {
 } from "@lib/managers/adapters";
 import type { FileEventItemSentinel } from "@lib/managers/StorageEventManager";
 import type { NodeFile, NodeFolder } from "../adapters/NodeTypes";
+import type { Stats } from "fs";
 import * as fs from "fs/promises";
 import * as path from "path";
+import { watch as chokidarWatch, type FSWatcher } from "chokidar";
 
 /**
  * CLI-specific type guard adapter
@@ -56,22 +58,11 @@ class CLIPersistenceAdapter implements IStorageEventPersistenceAdapter {
 }
 
 /**
- * CLI-specific status adapter (console logging)
+ * CLI-specific status adapter (no-op — daemon uses journald for status)
  */
 class CLIStatusAdapter implements IStorageEventStatusAdapter {
-    private lastUpdate = 0;
-    private updateInterval = 5000; // Update every 5 seconds
-
-    updateStatus(status: { batched: number; processing: number; totalQueued: number }): void {
-        const now = Date.now();
-        if (now - this.lastUpdate > this.updateInterval) {
-            if (status.totalQueued > 0 || status.processing > 0) {
-                // console.log(
-                //     `[StorageEventManager] Batched: ${status.batched}, Processing: ${status.processing}, Total Queued: ${status.totalQueued}`
-                // );
-            }
-            this.lastUpdate = now;
-        }
+    updateStatus(_status: { batched: number; processing: number; totalQueued: number }): void {
+        // intentional no-op
     }
 }
 
@@ -100,15 +91,100 @@ class CLIConverterAdapter implements IStorageEventConverterAdapter<NodeFile> {
 }
 
 /**
- * CLI-specific watch adapter (optional file watching with chokidar)
+ * CLI-specific watch adapter using chokidar for real-time filesystem monitoring.
  */
 class CLIWatchAdapter implements IStorageEventWatchAdapter {
-    constructor(private basePath: string) {}
+    private _watcher: FSWatcher | undefined;
+
+    constructor(private basePath: string, private watchEnabled: boolean = false) {}
+
+    private _toNodeFile(filePath: string, stats: Stats | undefined): NodeFile {
+        return {
+            path: path.relative(this.basePath, filePath) as FilePath,
+            stat: {
+                ctime: stats?.ctimeMs ?? Date.now(),
+                mtime: stats?.mtimeMs ?? Date.now(),
+                size: stats?.size ?? 0,
+                type: "file",
+            },
+        };
+    }
+
+    private _toNodeFileStub(filePath: string): NodeFile {
+        return {
+            path: path.relative(this.basePath, filePath) as FilePath,
+            stat: {
+                ctime: Date.now(),
+                mtime: Date.now(),
+                size: 0,
+                type: "file",
+            },
+        };
+    }
+
+    private _toNodeFolder(dirPath: string): NodeFolder {
+        return {
+            path: path.relative(this.basePath, dirPath) as FilePath,
+            isFolder: true,
+        };
+    }
 
     async beginWatch(handlers: IStorageEventWatchHandlers): Promise<void> {
-        // File watching is not activated in the CLI.
-        // Because the CLI is designed for push/pull operations, not real-time sync.
-        // console.error("[CLIWatchAdapter] File watching is not enabled in CLI version");
+        if (!this.watchEnabled) return;
+        const watcher = chokidarWatch(this.basePath, {
+            ignored: [
+                /(^|[/\\])\./,
+            ],
+            ignoreInitial: true,
+            persistent: true,
+            awaitWriteFinish: {
+                stabilityThreshold: 500,
+                pollInterval: 100,
+            },
+        });
+
+        watcher.on("add", (filePath, stats) => {
+            const nodeFile = this._toNodeFile(filePath, stats);
+            handlers.onCreate(nodeFile);
+        });
+
+        watcher.on("change", (filePath, stats) => {
+            const nodeFile = this._toNodeFile(filePath, stats);
+            handlers.onChange(nodeFile);
+        });
+
+        watcher.on("unlink", (filePath) => {
+            const nodeFile = this._toNodeFileStub(filePath);
+            handlers.onDelete(nodeFile);
+        });
+
+        watcher.on("addDir", (dirPath) => {
+            const nodeFolder = this._toNodeFolder(dirPath);
+            handlers.onCreate(nodeFolder);
+        });
+
+        watcher.on("unlinkDir", (dirPath) => {
+            const nodeFolder = this._toNodeFolder(dirPath);
+            handlers.onDelete(nodeFolder);
+        });
+
+        watcher.on("error", (err) => {
+            console.error("[CLIWatchAdapter] Fatal watcher error — file watching stopped:", err);
+            console.error("[CLIWatchAdapter] Exiting for systemd restart.");
+            void watcher.close();
+            this._watcher = undefined;
+            // Use exit(1) rather than SIGTERM so systemd Restart=on-failure engages.
+            process.exit(1);
+        });
+
+        await new Promise<void>((resolve) => watcher.once("ready", resolve));
+        this._watcher = watcher;
+    }
+
+    close(): Promise<void> {
+        if (this._watcher) {
+            return this._watcher.close();
+        }
         return Promise.resolve();
     }
 }
@@ -123,11 +199,15 @@ export class CLIStorageEventManagerAdapter implements IStorageEventManagerAdapte
     readonly status: CLIStatusAdapter;
     readonly converter: CLIConverterAdapter;
 
-    constructor(basePath: string) {
+    constructor(basePath: string, watchEnabled: boolean = false) {
         this.typeGuard = new CLITypeGuardAdapter();
         this.persistence = new CLIPersistenceAdapter(basePath);
-        this.watch = new CLIWatchAdapter(basePath);
+        this.watch = new CLIWatchAdapter(basePath, watchEnabled);
         this.status = new CLIStatusAdapter();
         this.converter = new CLIConverterAdapter();
     }
+
+    close(): Promise<void> {
+        return this.watch.close();
+    }
 }

src/apps/cli/managers/CLIStorageEventManagerAdapter.unit.spec.ts

@@ -0,0 +1,126 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import type { IStorageEventWatchHandlers } from "@lib/managers/adapters";
+import type { NodeFile } from "../adapters/NodeTypes";
+
+// ── chokidar mock ──────────────────────────────────────────────────────────────
+// Must be hoisted before imports that pull in chokidar.
+
+const mockWatcher = {
+    on: vi.fn().mockReturnThis(),
+    once: vi.fn((event: string, cb: () => void) => {
+        if (event === "ready") cb();
+        return mockWatcher;
+    }),
+    close: vi.fn(() => Promise.resolve()),
+};
+
+vi.mock("chokidar", () => ({
+    watch: vi.fn(() => mockWatcher),
+}));
+
+import * as chokidar from "chokidar";
+import { CLIStorageEventManagerAdapter } from "./CLIStorageEventManagerAdapter";
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function makeHandlers(): IStorageEventWatchHandlers {
+    return {
+        onCreate: vi.fn(),
+        onChange: vi.fn(),
+        onDelete: vi.fn(),
+        onRename: vi.fn(),
+    } as any;
+}
+
+// ── tests ─────────────────────────────────────────────────────────────────────
+
+describe("CLIStorageEventManagerAdapter", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        // Restore the default once() behaviour (ready fires synchronously).
+        mockWatcher.once.mockImplementation((event: string, cb: () => void) => {
+            if (event === "ready") cb();
+            return mockWatcher;
+        });
+    });
+
+    it("beginWatch is no-op when watchEnabled=false", async () => {
+        const adapter = new CLIStorageEventManagerAdapter("/base", undefined, false);
+        const handlers = makeHandlers();
+
+        await adapter.watch.beginWatch(handlers);
+
+        expect(chokidar.watch).not.toHaveBeenCalled();
+    });
+
+    it("beginWatch calls chokidar.watch when watchEnabled=true", async () => {
+        const adapter = new CLIStorageEventManagerAdapter("/base", undefined, true);
+        const handlers = makeHandlers();
+
+        await adapter.watch.beginWatch(handlers);
+
+        expect(chokidar.watch).toHaveBeenCalledTimes(1);
+        expect(chokidar.watch).toHaveBeenCalledWith(
+            "/base",
+            expect.objectContaining({ ignoreInitial: true })
+        );
+    });
+
+    it("add event produces NodeFile with correct relative path via onCreate", async () => {
+        const basePath = "/vault/base";
+        const adapter = new CLIStorageEventManagerAdapter(basePath, undefined, true);
+        const handlers = makeHandlers();
+
+        await adapter.watch.beginWatch(handlers);
+
+        // Find the callback registered for the "add" event.
+        const addCall = mockWatcher.on.mock.calls.find(([event]) => event === "add");
+        expect(addCall).toBeDefined();
+        const addCallback = addCall![1] as (filePath: string, stats: any) => void;
+
+        const fakeStats = { ctimeMs: 1000, mtimeMs: 2000, size: 42 };
+        addCallback(`${basePath}/subdir/note.md`, fakeStats);
+
+        expect(handlers.onCreate).toHaveBeenCalledTimes(1);
+        const created = (handlers.onCreate as ReturnType<typeof vi.fn>).mock.calls[0][0] as NodeFile;
+        expect(created.path).toBe("subdir/note.md");
+        expect(created.stat?.size).toBe(42);
+    });
+
+    it("close() calls watcher.close()", async () => {
+        const adapter = new CLIStorageEventManagerAdapter("/base", undefined, true);
+        const handlers = makeHandlers();
+
+        await adapter.watch.beginWatch(handlers);
+        await adapter.close();
+
+        expect(mockWatcher.close).toHaveBeenCalledTimes(1);
+    });
+
+    it("close() is safe when no watcher was started", async () => {
+        const adapter = new CLIStorageEventManagerAdapter("/base", undefined, false);
+
+        // Should not throw.
+        await expect(adapter.close()).resolves.toBeUndefined();
+        expect(mockWatcher.close).not.toHaveBeenCalled();
+    });
+
+    it("error event triggers process.exit(1)", async () => {
+        const adapter = new CLIStorageEventManagerAdapter("/base", undefined, true);
+        const handlers = makeHandlers();
+
+        await adapter.watch.beginWatch(handlers);
+
+        const processExitSpy = vi.spyOn(process, "exit").mockImplementation((() => {}) as any);
+
+        const errorCall = mockWatcher.on.mock.calls.find(([event]) => event === "error");
+        expect(errorCall).toBeDefined();
+        const errorCallback = errorCall![1] as (err: Error) => void;
+
+        errorCallback(new Error("disk failure"));
+
+        expect(processExitSpy).toHaveBeenCalledWith(1);
+
+        processExitSpy.mockRestore();
+    });
+});

src/apps/cli/managers/StorageEventManagerCLI.ts

@@ -10,9 +10,10 @@ export class StorageEventManagerCLI extends StorageEventManagerBase<CLIStorageEv
     constructor(
         basePath: string,
         core: LiveSyncBaseCore<ServiceContext, IMinimumLiveSyncCommands>,
-        dependencies: StorageEventManagerBaseDependencies
+        dependencies: StorageEventManagerBaseDependencies,
+        watchEnabled?: boolean
     ) {
-        const adapter = new CLIStorageEventManagerAdapter(basePath);
+        const adapter = new CLIStorageEventManagerAdapter(basePath, watchEnabled);
         super(adapter, dependencies);
         this.core = core;
     }
@@ -25,4 +26,11 @@ export class StorageEventManagerCLI extends StorageEventManagerBase<CLIStorageEv
         // No-op in CLI version
         // Internal file handling is not needed
     }
+
+    /**
+     * Close the file watcher. Call this during graceful shutdown.
+     */
+    close(): Promise<void> {
+        return this.adapter.close();
+    }
 }