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

package/changelog.json

@@ -1,6 +1,19 @@
 {
   "_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.857",
+      "changes": [
+        "The daemon now caches external-event records by file stat so the one-second reconcile tick no longer re-reads and re-parses every unchanged record, cutting idle CPU.",
+        "The record cache never keeps a filesystem read error and re-reads any entry older than a minute, so a transient read failure or a missed change cannot hide a record."
+      ]
+    },
+    {
+      "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.857",
   "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.857</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

package/dist/heart/daemon/daemon.js

@@ -637,6 +637,7 @@ class OuroDaemon {
     externalEventRoot;
     privilegedEventSpoolRoot;
     privilegedEventScanner;
+    externalEventScanCache = new router_1.ExternalEventScanCache();
     rsvpHabitRunner;
     nativeHabitRunner;
     nativeHabitMatch;
@@ -1701,12 +1702,11 @@ class OuroDaemon {
             if (fs.existsSync(this.privilegedEventSpoolRoot)) {
                 this.privilegedEventScanner({ spoolRoot: this.privilegedEventSpoolRoot, eventRoot: this.externalEventRootPath() });
             }
-            const statuses = (0, router_1.listExternalEventStatus)(this.externalEventRootPath());
+            const scanned = this.externalEventScanCache.scan(this.externalEventRootPath());
             const readinessKeys = new Set();
-            for (const status of statuses) {
-                if (status.corrupt)
+            for (const { record: candidate } of scanned) {
+                if (!candidate)
                     continue;
-                const candidate = (0, router_1.readExternalEventRecord)(status.recordPath);
                 if (candidate.dispatchEnabled === false)
                     continue;
                 const retryDue = candidate.executionState === "retry_wait" && candidate.nextAttemptAt !== null && Date.parse(candidate.nextAttemptAt) <= Date.parse(now);
@@ -1739,10 +1739,10 @@ class OuroDaemon {
             const providerEvidenceByAgent = new Map();
             const runtimeEvidenceByAgent = new Map();
             const recoveredByClass = new Map();
-            for (const status of statuses) {
-                if (status.corrupt)
+            for (const { record: scannedRecord } of scanned) {
+                if (!scannedRecord)
                     continue;
-                let record = (0, router_1.readExternalEventRecord)(status.recordPath);
+                let record = scannedRecord;
                 if (record.dispatchEnabled === false)
                     continue;
                 if (blockedReadinessKeys.has(`${record.agent}\0${record.source}`))

package/dist/heart/external-events/router.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExternalEventScanCache = void 0;
 exports.getExternalEventRoot = getExternalEventRoot;
 exports.externalEventRecordPath = externalEventRecordPath;
 exports.readExternalEventRecord = readExternalEventRecord;
@@ -622,6 +623,78 @@ function listExternalEventStatus(root) {
     }
     return rows.sort((left, right) => left.agent.localeCompare(right.agent) || left.source.localeCompare(right.source) || left.eventId.localeCompare(right.eventId));
 }
+/**
+ * Stat-keyed record cache for the daemon's reconcile tick. Records are written by atomic rename, so any write
+ * changes inode, mtime or ctime and invalidates the entry. Cached records are only used to decide what is due;
+ * every mutation (claim, revive, reconcile) re-reads the file under its own lock and compare-and-swap check, so a
+ * stale cached record can at worst cause one rejected attempt that the next tick retries from fresh data.
+ * As a backstop against a change the stat key misses, an entry older than `maxAgeMs` is re-read anyway, and a
+ * filesystem read error (one carrying an fs `code`, such as EIO or EMFILE) is reported for this scan but never
+ * cached, so a transient failure cannot hide a healthy record until its file next changes.
+ */
+class ExternalEventScanCache {
+    entries = new Map();
+    maxAgeMs;
+    now;
+    constructor(options = {}) {
+        this.maxAgeMs = options.maxAgeMs ?? 60_000;
+        this.now = options.now ?? Date.now;
+    }
+    scan(root) {
+        const seen = new Set();
+        const rows = [];
+        const nowMs = this.now();
+        if (fs.existsSync(root)) {
+            for (const agent of fs.readdirSync(root, { withFileTypes: true })) {
+                if (!agent.isDirectory() || agent.name.startsWith("."))
+                    continue;
+                const agentPath = path.join(root, agent.name);
+                for (const source of fs.readdirSync(agentPath, { withFileTypes: true })) {
+                    if (!source.isDirectory() || source.name.startsWith("."))
+                        continue;
+                    const sourcePath = path.join(agentPath, source.name);
+                    for (const file of fs.readdirSync(sourcePath, { withFileTypes: true })) {
+                        if (!file.isFile() || file.name.startsWith(".") || !file.name.endsWith(".json"))
+                            continue;
+                        const recordPath = path.join(sourcePath, file.name);
+                        let stat;
+                        try {
+                            stat = fs.statSync(recordPath);
+                        }
+                        catch {
+                            continue;
+                        }
+                        seen.add(recordPath);
+                        const cached = this.entries.get(recordPath);
+                        if (cached && cached.ino === stat.ino && cached.size === stat.size && cached.mtimeMs === stat.mtimeMs && cached.ctimeMs === stat.ctimeMs && nowMs - cached.cachedAtMs < this.maxAgeMs) {
+                            rows.push(cached.entry);
+                            continue;
+                        }
+                        let entry;
+                        let cacheable = true;
+                        try {
+                            entry = { recordPath, record: readExternalEventRecord(recordPath), error: null };
+                        }
+                        catch (error) {
+                            entry = { recordPath, record: null, error: error instanceof Error ? error.message : /* v8 ignore next -- filesystem and JSON parsers throw Error objects @preserve */ String(error) };
+                            cacheable = !(error && typeof error === "object" && typeof error.code === "string");
+                        }
+                        if (cacheable)
+                            this.entries.set(recordPath, { ino: stat.ino, size: stat.size, mtimeMs: stat.mtimeMs, ctimeMs: stat.ctimeMs, cachedAtMs: nowMs, entry });
+                        else
+                            this.entries.delete(recordPath);
+                        rows.push(entry);
+                    }
+                }
+            }
+        }
+        for (const key of this.entries.keys())
+            if (!seen.has(key))
+                this.entries.delete(key);
+        return rows;
+    }
+}
+exports.ExternalEventScanCache = ExternalEventScanCache;
 function readExisting(recordPath) {
     if (!fs.existsSync(recordPath))
         return { record: null, corruptDuplicateCount: 0 };

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.857",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@ouro.bot/cli",
-      "version": "0.1.0-alpha.855",
+      "version": "0.1.0-alpha.857",
       "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.857",
   "engines": {
     "node": ">=22"
   },