@ouro.bot/cli 0.1.0-alpha.855 → 0.1.0-alpha.856

package/changelog.json

@@ -1,6 +1,12 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.856",
+      "changes": [
+        "The daemon no longer freezes for minutes after an upgrade. Mailbox watched the whole agent bundle with Node's JavaScript recursive watcher on Linux, which blocked the event loop for about 7 s at every boot and for about 150 s when a host-side chown touched every bundle file, long enough to fail the container healthcheck and get the Butler restarted. Mailbox now watches directories without blocking: async discovery, event callbacks that never touch the filesystem, a catch-up report for new directories, a 3 s cap on event debouncing, and a warning event when watches run out."
+      ]
+    },
     {
       "version": "0.1.0-alpha.855",
       "changes": [

package/deploy/unraid/sanctuary.ouro/bundle-meta.json

@@ -1,5 +1,5 @@
 {
-  "runtimeVersion": "0.1.0-alpha.855",
+  "runtimeVersion": "0.1.0-alpha.856",
   "bundleSchemaVersion": 3,
   "lastUpdated": "2026-09-03T00:00:00.000Z"
 }

package/deploy/unraid/sanctuary.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <Container version="2">
   <Name>ouro-butler</Name>
-  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.855</Repository>
+  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.856</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

package/dist/heart/mailbox/mailbox-http-transport.js

@@ -37,9 +37,13 @@ exports.createSseBroadcaster = createSseBroadcaster;
 exports.createStateChangedBroadcast = createStateChangedBroadcast;
 exports.createBundleWatcher = createBundleWatcher;
 const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const runtime_1 = require("../../nerves/runtime");
 const DEFAULT_BUNDLE_WATCHER_DEPS = {
+    platform: process.platform,
     existsSync: fs.existsSync,
-    watch: fs.watch,
+    watch: (targetPath, options, listener) => fs.watch(targetPath, options, listener),
+    readdir: (targetPath) => fs.promises.readdir(targetPath, { withFileTypes: true }),
     setTimeout,
     clearTimeout,
 };
@@ -81,49 +85,188 @@ function createStateChangedBroadcast(sse) {
         sse.broadcast("state-changed", { at: new Date().toISOString() });
     };
 }
+const BUNDLE_WATCH_DEBOUNCE_MS = 500;
+// A continuous event stream must not postpone onChange forever.
+const BUNDLE_WATCH_MAX_WAIT_MS = 3_000;
+const BUNDLE_WATCH_DEGRADED_LOG_INTERVAL_MS = 60_000;
+const BUNDLE_WATCH_SKIPPED_DIRECTORIES = new Set([".git", "node_modules"]);
+function closeQuietly(handle) {
+    try {
+        handle.close();
+    }
+    catch {
+        // Already closed.
+    }
+}
+/**
+ * Report "something under the bundles root changed" to Mailbox, debounced.
+ *
+ * On Linux, Node implements `fs.watch(root, { recursive: true })` in JavaScript: it stats and
+ * inotify-watches every file in the tree before returning (7-10 s of blocked event loop for a
+ * 12k-file bundle), and it answers every file event on a directory by re-reading that whole
+ * directory. A host-side `chown -R` of a bundle holding directories of ~3.5k receipts therefore
+ * keeps the daemon's event loop busy for ~150 s, long enough to fail the container healthcheck.
+ *
+ * So on Linux we watch each directory (not each file) non-recursively. The tree is discovered
+ * with async readdir, and event callbacks never touch the filesystem: they only schedule a
+ * debounced onChange, plus, for create/delete/rename events, a debounced async re-read of that
+ * one directory to pick up added or removed subdirectories. macOS and Windows have a native
+ * recursive watcher that is cheap, so they keep it. Symlinked directories are not followed, and
+ * .git and node_modules are not watched.
+ */
 function createBundleWatcher(bundlesRoot, onChange, deps = DEFAULT_BUNDLE_WATCHER_DEPS) {
-    const watchers = [];
+    const watchers = new Map();
+    const pendingDirectories = new Set();
     let debounceTimer = null;
-    const debounceMs = 500;
+    let rescanTimer = null;
+    let maxWaitTimer = null;
+    let rescanRunning = false;
+    let stopped = false;
+    let resourceExhausted = false;
+    let lastDegradedLogAt = Number.NEGATIVE_INFINITY;
+    function flushOnChange() {
+        if (debounceTimer)
+            deps.clearTimeout(debounceTimer);
+        if (maxWaitTimer)
+            deps.clearTimeout(maxWaitTimer);
+        debounceTimer = null;
+        maxWaitTimer = null;
+        onChange();
+    }
     function debouncedOnChange() {
         if (debounceTimer)
             deps.clearTimeout(debounceTimer);
-        debounceTimer = deps.setTimeout(onChange, debounceMs);
+        debounceTimer = deps.setTimeout(flushOnChange, BUNDLE_WATCH_DEBOUNCE_MS);
+        if (!maxWaitTimer)
+            maxWaitTimer = deps.setTimeout(flushOnChange, BUNDLE_WATCH_MAX_WAIT_MS);
     }
-    try {
-        if (deps.existsSync(bundlesRoot)) {
-            const watcher = deps.watch(bundlesRoot, { recursive: true }, debouncedOnChange);
-            watcher.on?.("error", () => {
-                try {
-                    watcher.close();
-                }
-                catch {
-                    // Already closed.
-                }
-                const index = watchers.indexOf(watcher);
-                if (index >= 0)
-                    watchers.splice(index, 1);
+    function reportWatchDegraded(targetPath, error) {
+        const code = error?.code;
+        if (code === "ENOSPC" || code === "EMFILE")
+            resourceExhausted = true;
+        const now = Date.now();
+        if (now - lastDegradedLogAt < BUNDLE_WATCH_DEGRADED_LOG_INTERVAL_MS)
+            return;
+        lastDegradedLogAt = now;
+        const reason = typeof code === "string" ? code : error instanceof Error ? error.message : String(error);
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "daemon",
+            event: "daemon.mailbox_watch_degraded",
+            message: `mailbox watch degraded: ${reason} at ${targetPath}`,
+            meta: { path: targetPath, reason },
+        });
+    }
+    function watchPath(targetPath, recursive, listener) {
+        try {
+            const handle = deps.watch(targetPath, { recursive }, listener);
+            handle.on?.("error", (error) => {
+                closeQuietly(handle);
+                if (watchers.get(targetPath) === handle)
+                    watchers.delete(targetPath);
+                if (stopped)
+                    return;
+                reportWatchDegraded(targetPath, error);
                 debouncedOnChange();
             });
-            watchers.push(watcher);
+            watchers.set(targetPath, handle);
+            return true;
+        }
+        catch (error) {
+            // Watching is best-effort; manual broadcasts still keep Mailbox usable.
+            reportWatchDegraded(targetPath, error);
+            return false;
         }
     }
-    catch {
-        // Watching is best-effort; manual broadcasts still keep Mailbox usable.
+    function unwatchTree(directory) {
+        for (const [watched, handle] of watchers) {
+            if (watched === directory || watched.startsWith(`${directory}${path.sep}`)) {
+                closeQuietly(handle);
+                watchers.delete(watched);
+            }
+        }
+    }
+    function scheduleRescan(directory) {
+        pendingDirectories.add(directory);
+        if (rescanTimer)
+            return;
+        rescanTimer = deps.setTimeout(() => {
+            rescanTimer = null;
+            void drainRescans();
+        }, BUNDLE_WATCH_DEBOUNCE_MS);
+    }
+    async function drainRescans() {
+        if (rescanRunning)
+            return;
+        rescanRunning = true;
+        try {
+            while (!stopped && pendingDirectories.size > 0) {
+                const [directory] = pendingDirectories;
+                pendingDirectories.delete(directory);
+                await reconcileDirectory(directory, true);
+            }
+        }
+        finally {
+            rescanRunning = false;
+        }
+    }
+    function watchDirectory(directory) {
+        return watchPath(directory, false, (eventType) => {
+            debouncedOnChange();
+            if (eventType === "rename")
+                scheduleRescan(directory);
+        });
+    }
+    // catchUp is true for rescans after boot: files written into a directory before its watch existed
+    // produced no event, so a newly watched directory reports one change itself.
+    async function reconcileDirectory(directory, catchUp) {
+        let entries;
+        try {
+            entries = await deps.readdir(directory);
+        }
+        catch {
+            unwatchTree(directory);
+            return;
+        }
+        if (stopped)
+            return;
+        const subdirectories = new Set(entries.filter((entry) => entry.isDirectory() && !BUNDLE_WATCH_SKIPPED_DIRECTORIES.has(entry.name)).map((entry) => path.join(directory, entry.name)));
+        for (const watched of [...watchers.keys()]) {
+            if (path.dirname(watched) === directory && !subdirectories.has(watched))
+                unwatchTree(watched);
+        }
+        for (const subdirectory of subdirectories) {
+            if (stopped || resourceExhausted)
+                return;
+            if (watchers.has(subdirectory) || !watchDirectory(subdirectory))
+                continue;
+            if (catchUp)
+                debouncedOnChange();
+            await reconcileDirectory(subdirectory, catchUp);
+        }
+    }
+    if (deps.existsSync(bundlesRoot)) {
+        if (deps.platform === "linux") {
+            if (watchDirectory(bundlesRoot))
+                void reconcileDirectory(bundlesRoot, false);
+        }
+        else {
+            watchPath(bundlesRoot, true, debouncedOnChange);
+        }
     }
     return {
         stop() {
+            stopped = true;
             if (debounceTimer)
                 deps.clearTimeout(debounceTimer);
-            for (const watcher of watchers) {
-                try {
-                    watcher.close();
-                }
-                catch {
-                    // Already closed.
-                }
-            }
-            watchers.length = 0;
+            if (maxWaitTimer)
+                deps.clearTimeout(maxWaitTimer);
+            if (rescanTimer)
+                deps.clearTimeout(rescanTimer);
+            pendingDirectories.clear();
+            for (const handle of watchers.values())
+                closeQuietly(handle);
+            watchers.clear();
         },
     };
 }

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.855",
+  "version": "0.1.0-alpha.856",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@ouro.bot/cli",
-      "version": "0.1.0-alpha.855",
+      "version": "0.1.0-alpha.856",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.78.0",
         "@azure/identity": "^4.13.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.855",
+  "version": "0.1.0-alpha.856",
   "engines": {
     "node": ">=22"
   },