@ouro.bot/cli 0.1.0-alpha.776 → 0.1.0-alpha.777

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.777",
+      "changes": [
+        "Hold Sanctuary external-event ownership until source-specific machine credentials are ready, acknowledge exact private-runtime turns over existing IPC, complete 32-member dispositions under existing tool limits, and immediately settle failed owned claims."
+      ]
+    },
     {
       "version": "0.1.0-alpha.776",
       "changes": [

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

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

package/deploy/unraid/sanctuary.xml

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

package/dist/heart/agent-entry.js

@@ -90,7 +90,18 @@ function isPrivateRuntimeWorkMessage(message) {
         || type === "shutdown"
         || type === "poke"
         || type === "chat"
-        || type === "message";
+        || type === "message"
+        || type === "ouro.privateRuntimeDispatchCancel";
+}
+function safeDispatchError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.startsWith("[agent-runnable]"))
+        return "[agent-runnable] Private-runtime work failed; inspect the agent's redacted runtime diagnostics and run the indicated repair.";
+    if (message.startsWith("[human-required]"))
+        return "[human-required] Private-runtime work needs human repair; inspect the agent's redacted runtime diagnostics.";
+    if (message.startsWith("[human-choice]"))
+        return "[human-choice] Private-runtime work needs an explicit human decision; inspect the agent's redacted runtime diagnostics.";
+    return "private-runtime worker failed; inspect the worker's redacted runtime diagnostics";
 }
 function forwardOrBufferRuntimeMessage(message) {
     if (isRuntimeCredentialBootstrapMessage(message)) {
@@ -177,16 +188,68 @@ Promise.resolve().then(() => __importStar(require("./runtime-credentials"))).the
             .catch(() => undefined);
     }
     const { startPrivateRuntimeWorker } = await Promise.resolve().then(() => __importStar(require("../senses/private-runtime-worker")));
-    const bufferedMessages = ipcState.bufferedMessages.splice(0);
     const worker = await startPrivateRuntimeWorker({
         attachProcessListeners: false,
-        bufferedMessages,
+        bufferedMessages: [],
     });
+    const { ensureSanctuarySourceRuntimeReady } = await Promise.resolve().then(() => __importStar(require("../senses/sanctuary-runtime")));
+    const readinessPendingDispatchIds = new Set();
+    const cancelledReadinessDispatchIds = new Set();
+    const handleWorkerMessage = async (message) => {
+        /* v8 ignore next -- sole caller is gated by isPrivateRuntimeWorkMessage, which rejects falsy payloads @preserve */
+        const envelope = message && typeof message === "object" ? message : null;
+        if (envelope?.type === "ouro.privateRuntimeDispatchCancel" && typeof envelope.dispatchId === "string") {
+            if (readinessPendingDispatchIds.has(envelope.dispatchId))
+                cancelledReadinessDispatchIds.add(envelope.dispatchId);
+            else
+                worker.cancelMessage(envelope.dispatchId);
+            return;
+        }
+        const dispatchId = typeof envelope?.dispatchId === "string" ? envelope.dispatchId : null;
+        try {
+            if (typeof envelope?.externalEvent?.source === "string") {
+                if (dispatchId)
+                    readinessPendingDispatchIds.add(dispatchId);
+                await ensureSanctuarySourceRuntimeReady(agentName, envelope.externalEvent.source);
+                if (dispatchId)
+                    readinessPendingDispatchIds.delete(dispatchId);
+                if (dispatchId && cancelledReadinessDispatchIds.delete(dispatchId))
+                    return;
+            }
+            await worker.handleMessage(message);
+            if (dispatchId)
+                process.send?.({ type: "ouro.privateRuntimeDispatchResult", dispatchId, ok: true });
+        }
+        catch (error) {
+            if (dispatchId) {
+                process.send?.({
+                    type: "ouro.privateRuntimeDispatchResult",
+                    dispatchId,
+                    ok: false,
+                    error: safeDispatchError(error),
+                });
+                return;
+            }
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                component: "senses",
+                event: "senses.private_runtime_dispatch_error",
+                message: "private-runtime work message failed",
+                meta: { agentName, error: error instanceof Error ? error.message : String(error) },
+            });
+        }
+        finally {
+            if (dispatchId) {
+                readinessPendingDispatchIds.delete(dispatchId);
+                cancelledReadinessDispatchIds.delete(dispatchId);
+            }
+        }
+    };
     ipcState.workerMessageHandler = (message) => {
-        void worker.handleMessage(message);
+        void handleWorkerMessage(message);
     };
-    const messagesBufferedDuringStart = ipcState.bufferedMessages.splice(0);
-    for (const message of messagesBufferedDuringStart) {
+    const bufferedMessages = ipcState.bufferedMessages.splice(0);
+    for (const message of bufferedMessages) {
         ipcState.workerMessageHandler(message);
     }
 })

package/dist/heart/daemon/daemon.js

@@ -633,6 +633,7 @@ class OuroDaemon {
     schedulerFireVerifier;
     schedulerFireConsumer;
     orphanStartupDrain;
+    externalEventSourceReadiness;
     constructor(options) {
         this.socketPath = options.socketPath;
         this.processManager = options.processManager;
@@ -654,6 +655,10 @@ class OuroDaemon {
         this.schedulerFireVerifier = options.schedulerFireVerifier;
         this.schedulerFireConsumer = options.schedulerFireConsumer;
         this.orphanStartupDrain = options.orphanStartupDrain ?? drainOrphanProcessesBeforeStartup;
+        this.externalEventSourceReadiness = options.externalEventSourceReadiness ?? (async (agent, source) => {
+            const { ensureSanctuarySourceRuntimeReady } = await Promise.resolve().then(() => __importStar(require("../../senses/sanctuary-runtime")));
+            await ensureSanctuarySourceRuntimeReady(agent, source);
+        });
     }
     /* v8 ignore start -- default mailbox server wiring: production-only path, tests inject mailboxServerFactory stub instead. startMailboxHttpServer itself has full coverage in mailbox-http.test.ts @preserve */
     createDefaultMailboxServer() {
@@ -1561,6 +1566,10 @@ class OuroDaemon {
         const claimed = [];
         let failureClass;
         try {
+            for (const key of new Set(records.map((record) => `${record.agent}\0${record.source}`))) {
+                const [agent, source] = key.split("\0");
+                await this.externalEventSourceReadiness(agent, source);
+            }
             for (const record of records) {
                 const owner = `external-event:${record.agent}:${record.source}:${record.eventId}:generation:${record.generation}:attempt:${record.attemptCount + 1}`;
                 claimed.push((0, router_1.claimExternalEvent)(record.recordPath, { owner, expectedVersion: record.version, expectedGeneration: record.generation }));
@@ -1603,14 +1612,11 @@ class OuroDaemon {
         }
         catch (error) {
             for (const record of claimed) {
-                const latest = (0, router_1.readExternalEventRecord)(record.recordPath);
-                if (latest.executionState === "running" && latest.claimOwner === record.claimOwner) {
-                    (0, router_1.failExternalEventAttempt)(latest.recordPath, {
-                        owner: record.claimOwner, expectedVersion: latest.version, expectedGeneration: latest.generation,
-                        error: error instanceof Error ? error.message : String(error),
-                        ...(failureClass ? { failureClass } : {}),
-                    });
-                }
+                (0, router_1.settleExternalEventFailureIfOwned)(record.recordPath, {
+                    owner: record.claimOwner, expectedGeneration: record.generation,
+                    error: failureClass ? `external-event private-runtime dispatch failed: ${failureClass}` : "external-event private-runtime dispatch failed",
+                    ...(failureClass ? { failureClass } : {}),
+                });
             }
             throw error;
         }
@@ -1629,6 +1635,39 @@ class OuroDaemon {
                 this.privilegedEventScanner({ spoolRoot: this.privilegedEventSpoolRoot, eventRoot: this.externalEventRootPath() });
             }
             const statuses = (0, router_1.listExternalEventStatus)(this.externalEventRootPath());
+            const readinessKeys = new Set();
+            for (const status of statuses) {
+                if (status.corrupt)
+                    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);
+                const leaseExpired = candidate.executionState === "running" && candidate.claimExpiresAt !== null && Date.parse(candidate.claimExpiresAt) <= Date.parse(now);
+                const recoverableDeadLetter = candidate.executionState === "dead_letter"
+                    && (0, router_1.externalEventRecoveryFailure)(candidate) !== null
+                    && candidate.recoveryGrant?.generation !== candidate.generation;
+                const dispatchable = candidate.executionState === "received" || candidate.executionState === "queued" || retryDue || leaseExpired || recoverableDeadLetter;
+                if (dispatchable && (candidate.source === "sanctuary-health" || candidate.source === "sanctuary-usenet"))
+                    readinessKeys.add(`${candidate.agent}\0${candidate.source}`);
+            }
+            const blockedReadinessKeys = new Set();
+            for (const key of readinessKeys) {
+                const [agent, source] = key.split("\0");
+                try {
+                    await this.externalEventSourceReadiness(agent, source);
+                }
+                catch (error) {
+                    blockedReadinessKeys.add(key);
+                    (0, runtime_1.emitNervesEvent)({
+                        level: "warn",
+                        component: "daemon",
+                        event: "daemon.external_event_readiness_blocked",
+                        message: "external-event reconciliation is waiting for source runtime readiness",
+                        meta: { agent, source, error: (error instanceof Error ? error.message : String(error)).slice(0, 1_000) },
+                    });
+                }
+            }
             const dueRecords = [];
             const providerEvidenceByAgent = new Map();
             const runtimeEvidenceByAgent = new Map();
@@ -1639,6 +1678,8 @@ class OuroDaemon {
                 let record = (0, router_1.readExternalEventRecord)(status.recordPath);
                 if (record.dispatchEnabled === false)
                     continue;
+                if (blockedReadinessKeys.has(`${record.agent}\0${record.source}`))
+                    continue;
                 if (record.executionState === "dead_letter") {
                     const failure = (0, router_1.externalEventRecoveryFailure)(record);
                     if (!failure || record.recoveryGrant?.generation === record.generation)
@@ -1765,7 +1806,11 @@ class OuroDaemon {
         }
         await beforeDispatch?.(decision);
         await this.processManager.startAgent(command.agent);
-        this.processManager.sendToAgent?.(command.agent, this.buildPrivateRuntimeWorkerWakeMessage(command, decision, externalEvent));
+        const message = this.buildPrivateRuntimeWorkerWakeMessage(command, decision, externalEvent);
+        if (this.processManager.dispatchToAgent)
+            await this.processManager.dispatchToAgent(command.agent, message);
+        else
+            this.processManager.sendToAgent?.(command.agent, message);
         return {
             ok: true,
             message: `woke private runtime for ${command.agent}`,

package/dist/heart/daemon/process-manager.js

@@ -33,8 +33,9 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DaemonProcessManager = exports.RESPAWN_GUARD_WINDOW_MS = exports.RESPAWN_GUARD_MAX_RESTARTS = void 0;
+exports.DaemonProcessManager = exports.PRIVATE_RUNTIME_DISPATCH_ACK_TIMEOUT_MS = exports.RESPAWN_GUARD_WINDOW_MS = exports.RESPAWN_GUARD_MAX_RESTARTS = void 0;
 const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
 const path = __importStar(require("path"));
 const identity_1 = require("../identity");
 const runtime_1 = require("../../nerves/runtime");
@@ -54,6 +55,7 @@ function startOfHour(ms) {
 exports.RESPAWN_GUARD_MAX_RESTARTS = 5;
 exports.RESPAWN_GUARD_WINDOW_MS = 10 * 60_000;
 const MAX_PENDING_IPC_MESSAGES = 20;
+exports.PRIVATE_RUNTIME_DISPATCH_ACK_TIMEOUT_MS = 8 * 60_000;
 class DaemonProcessManager {
     agents = new Map();
     /** `stopAll()` is terminal for a manager instance. Once set, it fences
@@ -166,6 +168,7 @@ class DaemonProcessManager {
                 startAttemptedAtMs: null,
                 startAttemptId: 0,
                 pendingIpcMessages: [],
+                pendingDispatches: new Map(),
                 restartTimer: null,
                 crashTimestamps: [],
                 orchestratedRestartTimestamps: [],
@@ -328,6 +331,27 @@ class DaemonProcessManager {
             state.snapshot.status = "running";
             state.snapshot.pid = child.pid ?? null;
             state.snapshot.startedAt = new Date(this.currentTimeMs()).toISOString();
+            child.on("message", (message) => {
+                if (state.process !== child || !message || typeof message !== "object")
+                    return;
+                const result = message;
+                if (result.type !== "ouro.privateRuntimeDispatchResult" || typeof result.dispatchId !== "string")
+                    return;
+                const pending = state.pendingDispatches.get(result.dispatchId);
+                if (!pending || pending.child !== child)
+                    return;
+                state.pendingDispatches.delete(result.dispatchId);
+                this.clearTimeoutFn(pending.timer);
+                if (result.ok === true)
+                    pending.resolve();
+                else
+                    pending.reject(new Error(typeof result.error === "string" && result.error.trim() ? result.error.slice(0, 1_000) : "private-runtime dispatch failed"));
+            });
+            child.once("disconnect", () => {
+                if (state.process !== child)
+                    return;
+                this.rejectPendingDispatchesForChild(state, child, new Error(`Managed agent '${agent}' disconnected before acknowledged dispatch completed.`));
+            });
             const bootstrap = state.config.getRuntimeCredentialBootstrap?.() ?? null;
             if (bootstrap) {
                 const message = {
@@ -367,7 +391,16 @@ class DaemonProcessManager {
                 }
             }
             const pendingIpcMessages = state.pendingIpcMessages.splice(0);
-            for (const message of pendingIpcMessages) {
+            for (const pendingMessage of pendingIpcMessages) {
+                const { message, dispatchId } = pendingMessage;
+                if (dispatchId) {
+                    const pending = state.pendingDispatches.get(dispatchId);
+                    if (!pending)
+                        continue;
+                    pending.child = child;
+                    this.sendAcknowledgedMessage(state, child, dispatchId, message);
+                    continue;
+                }
                 try {
                     child.send?.(message);
                     (0, runtime_1.emitNervesEvent)({
@@ -413,6 +446,9 @@ class DaemonProcessManager {
             if (this.isStartAttemptCurrent(state, attemptId)) {
                 state.startInFlight = false;
                 state.startAttemptedAtMs = null;
+                if (!state.process) {
+                    this.rejectPendingDispatchesForChild(state, null, new Error(`Managed agent '${agent}' startup ended before acknowledged dispatch completed.`));
+                }
             }
         }
     }
@@ -421,6 +457,9 @@ class DaemonProcessManager {
         this.clearRestartTimer(state);
         this.clearCooldownTimer(state);
         state.stopRequested = true;
+        for (const [dispatchId] of state.pendingDispatches) {
+            this.rejectPendingDispatch(state, dispatchId, new Error(`Managed agent '${agent}' stopped before acknowledged dispatch completed.`));
+        }
         state.pendingIpcMessages = [];
         // NOTE: do not touch state.respawnLoopTripped / orchestratedRestartTimestamps
         // here. restartAgent calls stopAgent internally; clearing the guard here
@@ -626,9 +665,11 @@ class DaemonProcessManager {
         if (!state.process) {
             if (state.startInFlight) {
                 if (state.pendingIpcMessages.length >= MAX_PENDING_IPC_MESSAGES) {
-                    state.pendingIpcMessages.shift();
+                    const evicted = state.pendingIpcMessages.shift();
+                    if (evicted?.dispatchId)
+                        this.rejectPendingDispatch(state, evicted.dispatchId, new Error(`Managed agent '${agent}' startup IPC queue evicted acknowledged dispatch.`));
                 }
-                state.pendingIpcMessages.push(message);
+                state.pendingIpcMessages.push({ message });
                 (0, runtime_1.emitNervesEvent)({
                     component: "daemon",
                     event: "daemon.agent_ipc_queued_during_startup",
@@ -651,6 +692,73 @@ class DaemonProcessManager {
             });
         }
     }
+    dispatchToAgent(agent, message, options = {}) {
+        const state = this.requireAgent(agent);
+        const dispatchId = (0, crypto_1.randomUUID)();
+        const timeoutMs = options.timeoutMs ?? exports.PRIVATE_RUNTIME_DISPATCH_ACK_TIMEOUT_MS;
+        return new Promise((resolve, reject) => {
+            const timer = this.setTimeoutFn(() => {
+                const pending = state.pendingDispatches.get(dispatchId);
+                if (!pending)
+                    return;
+                state.pendingDispatches.delete(dispatchId);
+                if (pending.child && state.process === pending.child) {
+                    try {
+                        pending.child.send?.({ type: "ouro.privateRuntimeDispatchCancel", dispatchId });
+                    }
+                    catch { /* cancellation is best effort */ }
+                }
+                reject(new Error(`Private-runtime dispatch timed out after ${timeoutMs}ms.`));
+            }, timeoutMs);
+            const child = state.process?.connected === false ? null : state.process;
+            state.pendingDispatches.set(dispatchId, { child, timer, resolve, reject });
+            if (child) {
+                this.sendAcknowledgedMessage(state, child, dispatchId, message);
+                return;
+            }
+            if (state.startInFlight) {
+                if (state.pendingIpcMessages.length >= MAX_PENDING_IPC_MESSAGES) {
+                    const evicted = state.pendingIpcMessages.shift();
+                    if (evicted?.dispatchId)
+                        this.rejectPendingDispatch(state, evicted.dispatchId, new Error(`Managed agent '${agent}' startup IPC queue evicted acknowledged dispatch.`));
+                }
+                state.pendingIpcMessages.push({ message, dispatchId });
+                return;
+            }
+            this.rejectPendingDispatch(state, dispatchId, new Error(`Managed agent '${agent}' is unavailable for acknowledged dispatch.`));
+        });
+    }
+    rejectPendingDispatch(state, dispatchId, error) {
+        const pending = state.pendingDispatches.get(dispatchId);
+        if (!pending)
+            return;
+        state.pendingDispatches.delete(dispatchId);
+        this.clearTimeoutFn(pending.timer);
+        pending.reject(error);
+    }
+    rejectPendingDispatchesForChild(state, child, error) {
+        for (const [dispatchId, pending] of state.pendingDispatches) {
+            if (pending.child === child)
+                this.rejectPendingDispatch(state, dispatchId, error);
+        }
+        if (child === null)
+            state.pendingIpcMessages = state.pendingIpcMessages.filter((pending) => pending.dispatchId === undefined);
+    }
+    sendAcknowledgedMessage(state, child, dispatchId, message) {
+        try {
+            child.send?.({ ...message, dispatchId }, (error) => {
+                if (!error)
+                    return;
+                const pending = state.pendingDispatches.get(dispatchId);
+                if (!pending || pending.child !== child)
+                    return;
+                this.rejectPendingDispatch(state, dispatchId, error);
+            });
+        }
+        catch (error) {
+            this.rejectPendingDispatch(state, dispatchId, error instanceof Error ? error : new Error(String(error)));
+        }
+    }
     getAgentSnapshot(agent) {
         return this.agents.get(agent)?.snapshot;
     }
@@ -661,6 +769,7 @@ class DaemonProcessManager {
         /* v8 ignore next -- defensive: replacement cannot start before this child's one-shot exit listener drains @preserve */
         if (state.process !== child)
             return;
+        this.rejectPendingDispatchesForChild(state, child, new Error(`Managed agent '${state.config.name}' exited before acknowledged dispatch completed.`));
         state.process = null;
         state.startInFlight = false;
         state.startAttemptedAtMs = null;

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

@@ -46,6 +46,7 @@ exports.claimExternalEvent = claimExternalEvent;
 exports.renewExternalEventClaim = renewExternalEventClaim;
 exports.commitExternalEventDisposition = commitExternalEventDisposition;
 exports.failExternalEventAttempt = failExternalEventAttempt;
+exports.settleExternalEventFailureIfOwned = settleExternalEventFailureIfOwned;
 exports.isExactLegacyProviderRecoveryFailure = isExactLegacyProviderRecoveryFailure;
 exports.externalEventRecoveryFailure = externalEventRecoveryFailure;
 exports.reviveExternalEventAfterRecovery = reviveExternalEventAfterRecovery;
@@ -1280,6 +1281,19 @@ function failExternalEventAttempt(recordPath, input) {
         return commitMutation(recordPath, retryState(record, now, maxAttempts, baseDelayMs, input.error, input.failureClass), now);
     });
 }
+function settleExternalEventFailureIfOwned(recordPath, input) {
+    return withRecordLock(recordPath, () => {
+        const record = readExternalEventRecord(recordPath);
+        const now = input.now?.() ?? new Date().toISOString();
+        if (record.executionState !== "running"
+            || record.claimOwner !== input.owner
+            || record.generation !== input.expectedGeneration) {
+            return { settled: false, record };
+        }
+        const settled = commitMutation(recordPath, retryState(record, now, 5, 1_000, input.error, input.failureClass), now);
+        return { settled: true, record: settled };
+    });
+}
 function exactLegacyProviderFailure(record) {
     const escapedAgent = record.agent.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
     const canonical = new RegExp(`^private-runtime wake denied for ${escapedAgent}: provider lane resolution failed$`, "u");

package/dist/heart/tool-loop.js

@@ -183,7 +183,7 @@ function recordToolOutcome(state, toolName, args, result, success) {
 // ponder = continue thinking (private runtime) or hand off to private runtime (outer).
 // rest = end private runtime turn (added in Unit 8b).
 // Blocking these traps the agent: it can think all it wants but can never speak or stop.
-const CIRCUIT_BREAKER_EXEMPT = new Set(["settle", "surface", "ponder", "rest"]);
+const CIRCUIT_BREAKER_EXEMPT = new Set(["settle", "surface", "ponder", "rest", "external_event_disposition"]);
 function detectToolLoop(state, toolName, args) {
     if (state.history.length >= exports.GLOBAL_CIRCUIT_BREAKER_LIMIT && !CIRCUIT_BREAKER_EXEMPT.has(toolName)) {
         return emitDetection("global_circuit_breaker", toolName, state.history.length, `this turn has already made ${state.history.length} tool calls. stop thrashing, use the current evidence, and either change approach or answer truthfully with the best grounded status.`);