@ouro.bot/cli 0.1.0-alpha.938 → 0.1.0-alpha.939

package/changelog.json

@@ -1,6 +1,15 @@
 {
   "_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.939",
+      "changes": [
+        "Shepherd attributes failed observations to itself without inventing an agent stop or a human decision, and keeps explicit HTTP responses separate from pure transport failures.",
+        "Retain bounded pre-dispatch judgment retries and real offline-to-online evidence, advance new outage probes, and prevent a stalled judge from blocking unrelated sessions with bounded per-session scheduling.",
+        "Capture queued generations, coalesce stale per-session work, preserve uncertain-send replay barriers and existing focus/pause/menu guards, and wait for active observations before closing custody.",
+        "This P0-only release preserves existing legacy automation warnings; native guarded admission and full Shepherd v1 remain unqualified."
+      ]
+    },
     {
       "version": "0.1.0-alpha.938",
       "changes": [

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

@@ -1,5 +1,5 @@
 {
-  "runtimeVersion": "0.1.0-alpha.938",
+  "runtimeVersion": "0.1.0-alpha.939",
   "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.938</Repository>
+  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.939</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

package/dist/heart/providers/error-classification.js

@@ -30,6 +30,8 @@ const NETWORK_ERROR_MESSAGE_PATTERNS = [
 // True if the error looks like a transient network issue (no HTTP status, just
 // a socket/DNS/timeout failure from the underlying transport).
 function isNetworkError(error) {
+    if (error.status !== undefined)
+        return false;
     const code = error.code || "";
     if (NETWORK_ERROR_CODES.has(code))
         return true;

package/dist/senses/shepherd/owner-notice.js

@@ -127,9 +127,9 @@ function noticeLine(record, location) {
         case "working":
             return `${subject} is still working in the background and has news. ${why}`;
         case "unclear":
-            return `${subject} stopped and I could not tell what it needs, so I left it. ${why}`;
+            return `Shepherd could not determine the current state of ${subject}. ${why}`;
         default:
-            return `${subject} stopped but I could not judge it, so I left it. ${why}`;
+            return `Shepherd could not complete its observation of ${subject}; the agent's state was not determined. ${why}`;
     }
 }
 /** A bounded display of latest observations; all input records retain delivery custody. */

package/dist/senses/shepherd/sense.js

@@ -87,6 +87,8 @@ const ESCALATION_TTL_MS = 30 * 60_000;
 const WAKE_DELAY_MS = 2_000;
 const FIELD_MAX = 200;
 const CONNECTIVITY_POLL_MS = 15_000;
+const RECOVERY_JUDGE_ATTEMPTS = 3;
+const CONCURRENT_OBSERVATIONS = 4;
 const NETWORK_RESUME = "Connectivity has recovered. Continue the existing task only if safe. Check uncertain writes before retrying. Do not bypass approvals or deliberate pauses.";
 exports.PERIODIC_RESUME = "Reassess your existing task and continue only already-authorized remaining work. Respect human decisions and pauses. Reconcile uncertain effects before retrying; do not wait for a scheduled tick when you can work now.";
 const fingerprint = (value) => (0, node_crypto_1.createHash)("sha256").update(JSON.stringify(value)).digest("hex");
@@ -225,10 +227,14 @@ async function startShepherdSenseApp(options) {
     const wakeIds = [];
     let cancelWake = null;
     let chain = Promise.resolve();
+    const pending = [];
+    const active = new Set();
+    const activeSessions = new Set();
     const networkWaiting = new Map();
     const latestReturns = new Map();
     const checkConnectivity = options.checkConnectivity ?? checkShepherdConnectivity;
     let cancelConnectivity = null;
+    let connectivityImmediate = false;
     let recoveryGeneration = 0;
     let stopped = false;
     let cancelCheckIn = null;
@@ -238,6 +244,37 @@ async function startShepherdSenseApp(options) {
     const history = new Map((0, returns_1.readReturns)(agentRoot).filter(record => record.host === host.name).map(record => [record.session, record]));
     const generationFor = (session) => generations.get(session) ?? 0;
     const invalidate = (session) => generations.set(session, generationFor(session) + 1);
+    function enqueue(event, trigger = { kind: "immediate" }, generation = generationFor(event.sessionId)) {
+        const index = pending.findIndex(job => job.event.sessionId === event.sessionId);
+        const previous = pending[index];
+        if (previous && (previous.generation > generation ||
+            (previous.generation === generation && previous.trigger.kind !== "periodic" && trigger.kind === "periodic")))
+            return;
+        const job = { event, trigger, generation };
+        if (previous)
+            pending[index] = job;
+        else
+            pending.push(job);
+        drain();
+    }
+    function drain() {
+        while (!stopped && active.size < CONCURRENT_OBSERVATIONS) {
+            const index = pending.findIndex(job => !activeSessions.has(job.event.sessionId));
+            if (index === -1)
+                return;
+            const job = pending.splice(index, 1)[0];
+            activeSessions.add(job.event.sessionId);
+            const task = Promise.resolve().then(() => handle(job.event, job.trigger, job.generation)).catch(error => {
+                (0, runtime_1.emitNervesEvent)({ level: "error", component: "senses", event: "senses.shepherd_chain_error",
+                    message: "Shepherd observation failed; other sessions remain scheduled", meta: { agent, session: job.event.sessionId, error: (0, redact_1.redactSecrets)(String(error)) } });
+            }).finally(() => {
+                active.delete(task);
+                activeSessions.delete(job.event.sessionId);
+                drain();
+            });
+            active.add(task);
+        }
+    }
     function scheduleCheckIn() {
         if (stopped || checkInMs === 0 || !host.inspect || cancelCheckIn)
             return;
@@ -281,14 +318,14 @@ async function startShepherdSenseApp(options) {
                 return;
             cancelQuietBatch = schedule(() => {
                 cancelQuietBatch = null;
-                chain = chain.then(async () => {
+                chain = chain.then(() => {
                     for (const candidate of candidates) {
                         if (stopped)
                             break;
                         const current = candidate.trigger.first;
-                        await handle({ sessionId: candidate.sessionId, transitionId: `periodic:${candidate.trigger.pass}:${candidate.sessionId}`,
+                        enqueue({ sessionId: candidate.sessionId, transitionId: `periodic:${candidate.trigger.pass}:${candidate.sessionId}`,
                             agent: current.session.agent, cwd: current.session.cwd ?? null, lastBody: null, backgroundWork: current.backgroundWork,
-                            title: current.session.title, workspaceTitle: current.session.workspaceTitle }, candidate.trigger);
+                            title: current.session.title, workspaceTitle: current.session.workspaceTitle }, candidate.trigger, candidate.trigger.generation);
                     }
                 });
             }, cmux_1.QUIET_MS);
@@ -301,13 +338,20 @@ async function startShepherdSenseApp(options) {
             scheduleCheckIn();
         }
     }
-    function scheduleConnectivity() {
-        if (stopped || networkWaiting.size === 0 || cancelConnectivity)
+    function scheduleConnectivity(delay = CONNECTIVITY_POLL_MS) {
+        if (stopped || networkWaiting.size === 0)
             return;
+        if (cancelConnectivity) {
+            if (delay !== 0 || connectivityImmediate)
+                return;
+            cancelConnectivity();
+        }
+        connectivityImmediate = delay === 0;
         cancelConnectivity = schedule(() => {
             cancelConnectivity = null;
+            connectivityImmediate = false;
             chain = chain.then(checkRecovery);
-        }, CONNECTIVITY_POLL_MS);
+        }, delay);
     }
     async function checkRecovery() {
         if (stopped || networkWaiting.size === 0)
@@ -322,7 +366,7 @@ async function startShepherdSenseApp(options) {
                     candidate.offlineConfirmed = true;
             }
             else if (connectivity === "online") {
-                const candidates = [...networkWaiting.values()].filter(candidate => candidate.offlineConfirmed);
+                const candidates = [...networkWaiting.values()].filter(candidate => candidate.offlineConfirmed || candidate.recheck);
                 if (candidates.length === 0)
                     return;
                 recoveryGeneration += 1;
@@ -333,10 +377,14 @@ async function startShepherdSenseApp(options) {
                 for (const candidate of candidates) {
                     if (stopped)
                         break;
-                    if (latestReturns.get(candidate.event.sessionId) !== candidate.event ||
+                    if ((!candidate.recheck || candidate.recheck.kind !== "periodic") && latestReturns.get(candidate.event.sessionId) !== candidate.event ||
+                        candidate.eventGeneration !== generationFor(candidate.event.sessionId) ||
                         !sessions.some(session => session.id === candidate.event.sessionId))
                         continue;
-                    await handle(candidate.event, { kind: "network", screen: candidate.screen, generation: recoveryGeneration });
+                    const recheck = candidate.recheck?.kind === "immediate" && candidate.offlineConfirmed ? undefined : candidate.recheck;
+                    enqueue(candidate.event, recheck ?? {
+                        kind: "network", screen: candidate.screen, generation: recoveryGeneration, attempt: candidate.attempts + 1,
+                    }, candidate.eventGeneration);
                 }
             }
         }
@@ -347,11 +395,15 @@ async function startShepherdSenseApp(options) {
             scheduleConnectivity();
         }
     }
-    function rememberNetworkWait(event, screen) {
-        if (stopped || event.backgroundWork || latestReturns.get(event.sessionId) !== event)
-            return;
-        networkWaiting.set(event.sessionId, { event, screen, offlineConfirmed: false });
-        scheduleConnectivity();
+    function rememberNetworkWait(event, screen, eventGeneration, recoveryAttempt = 0, recheck) {
+        if (stopped || event.backgroundWork || (recheck?.kind !== "periodic" && latestReturns.get(event.sessionId) !== event) ||
+            eventGeneration !== generationFor(event.sessionId))
+            return false;
+        networkWaiting.set(event.sessionId, {
+            event, screen, offlineConfirmed: !recheck && recoveryAttempt > 0, eventGeneration, attempts: recoveryAttempt, recheck,
+        });
+        scheduleConnectivity(recoveryAttempt === 0 || (recheck && recoveryAttempt === 1) ? 0 : CONNECTIVITY_POLL_MS);
+        return true;
     }
     const guardFor = (session) => {
         let entry = guard.get(session);
@@ -408,11 +460,12 @@ async function startShepherdSenseApp(options) {
         return true;
     }
     /** Judges one return and acts on it. Every outcome, including a failure, is one log line. */
-    async function handle(event, trigger = { kind: "immediate" }) {
+    async function handle(event, trigger, eventGeneration) {
         if (stopped)
             return;
         const recovery = trigger.kind === "network" ? trigger : null;
         const periodic = trigger.kind === "periodic" ? trigger : null;
+        const observationRetry = trigger.kind === "immediate" ? trigger.retry : undefined;
         const record = {
             at: new Date(now()).toISOString(), host: host.name, session: event.sessionId, transition: recovery ? `network:${recovery.generation}:${event.transitionId}` : event.transitionId,
             agent: event.agent, cwd: event.cwd, task: null, kind: "unclear", action: "let_through", reason: "", reply: null, latencyMs: null, inputTokens: null,
@@ -467,7 +520,7 @@ async function startShepherdSenseApp(options) {
             const text = (0, redact_1.redactSecrets)(rawScreen);
             record.task = [...text.matchAll(/Desk-Task:\s*(\S+)/g)].pop()?.[1] ?? null;
             const screen = (0, redact_1.screenTail)(text, exports.SCREEN_LINES);
-            if (recovery && screen !== recovery.screen) {
+            if ((recovery || observationRetry) && screen !== (recovery?.screen ?? observationRetry.screen)) {
                 record.actionBlockReason = "state_changed";
                 record.reason = "the screen changed since the network stop, so recovery was not sent";
                 return;
@@ -484,6 +537,19 @@ async function startShepherdSenseApp(options) {
             };
             const guidance = checkedGuidance();
             record.guidanceRevision = guidance.revision;
+            if (stopped) {
+                notice = false;
+                record.actionBlockReason = "stopped";
+                record.reason = "Shepherd stopped before judgment; no input or notice sent";
+                return;
+            }
+            if ((observationRetry || periodic?.attempt) &&
+                (guidance.paused || current?.session.focused || current?.backgroundWork || now() - state.focusedAt < exports.FOCUS_HOLD_MS)) {
+                notice = false;
+                record.actionBlockReason = guidance.paused ? "guidance" : "state_changed";
+                record.reason = "the failed observation retry is now protected; no judgment or input sent";
+                return;
+            }
             let verdict;
             try {
                 const prior = history.get(event.sessionId);
@@ -494,8 +560,19 @@ async function startShepherdSenseApp(options) {
                     ...(periodic ? { periodicCheckIn: { priorJudgment: prior ? { kind: prior.kind, reason: prior.reason, at: prior.at } : null } } : {}) });
             }
             catch (error) {
-                if (!recovery && !periodic && error instanceof Error && (0, error_classification_1.isNetworkError)(error))
-                    rememberNetworkWait(event, screen);
+                if (periodic)
+                    notice = !stopped && eventGeneration === generationFor(event.sessionId) && !guidance.paused &&
+                        current?.session.focused !== true && current?.backgroundWork !== true && now() - state.focusedAt >= exports.FOCUS_HOLD_MS;
+                if (error instanceof Error && (0, error_classification_1.isNetworkError)(error)) {
+                    const attempt = recovery?.attempt ?? periodic?.attempt ?? observationRetry?.attempt ?? 1;
+                    if (attempt < RECOVERY_JUDGE_ATTEMPTS && !guidance.paused &&
+                        current?.session.focused !== true && current?.backgroundWork !== true &&
+                        now() - state.focusedAt >= exports.FOCUS_HOLD_MS &&
+                        rememberNetworkWait(event, screen, eventGeneration, attempt, recovery ? undefined :
+                            periodic ? { ...periodic, attempt: attempt + 1 } : { kind: "immediate", retry: { screen, attempt: attempt + 1 } })) {
+                        notice = false;
+                    }
+                }
                 throw error;
             }
             judged = true;
@@ -510,7 +587,7 @@ async function startShepherdSenseApp(options) {
             Object.assign(record, { kind, judgeKind: verdict.kind, reason: verdict.reason, latencyMs: verdict.latencyMs, inputTokens: verdict.inputTokens,
                 ...(verdict.replyIssue ? { replyIssue: verdict.replyIssue } : {}) });
             if (!recovery && !periodic && kind === "waiting" && verdict.waitingOnNetwork)
-                rememberNetworkWait(event, screen);
+                rememberNetworkWait(event, screen, eventGeneration);
             const noticeScreen = screen.replace(/\b\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})\b/g, "<observation-time>");
             noticeBasis = [host.name, event.sessionId, record.agent, record.cwd, record.task, noticeScreen, guidance.revision];
             notice = true;
@@ -575,7 +652,8 @@ async function startShepherdSenseApp(options) {
                         }
                         // No awaited host reads between this final check and initiating the send.
                         const latest = checkedGuidance();
-                        if (stopped || (recovery && (latestReturns.get(event.sessionId) !== event || now() - state.focusedAt < exports.FOCUS_HOLD_MS)) ||
+                        if (stopped || eventGeneration !== generationFor(event.sessionId) ||
+                            (recovery && (latestReturns.get(event.sessionId) !== event || now() - state.focusedAt < exports.FOCUS_HOLD_MS)) ||
                             periodic && (periodic.generation !== generationFor(event.sessionId) || now() - state.focusedAt < exports.FOCUS_HOLD_MS)) {
                             record.actionBlockReason = stopped ? "stopped" : now() - state.focusedAt < exports.FOCUS_HOLD_MS ? "focus" : "state_changed";
                             record.reason = `Shepherd stopped, the human focused this session, or it returned again while judging, so nothing was sent: ${verdict.reason}`;
@@ -697,7 +775,7 @@ async function startShepherdSenseApp(options) {
             invalidate(event.sessionId);
             networkWaiting.delete(event.sessionId);
             latestReturns.set(event.sessionId, event);
-            chain = chain.then(() => handle(event));
+            enqueue(event);
         },
         focused: (session) => {
             if (stopped)
@@ -718,13 +796,13 @@ async function startShepherdSenseApp(options) {
             stopped = true;
             observations.stop();
             networkWaiting.clear();
+            pending.length = 0;
             watcher.close();
             cancelWake?.();
             cancelConnectivity?.();
             cancelCheckIn?.();
             cancelQuietBatch?.();
-            void chain.then(() => custody.close(), error => {
-                custody.close();
+            void chain.finally(() => Promise.all(active)).finally(() => custody.close()).catch(error => {
                 (0, runtime_1.emitNervesEvent)({ level: "error", component: "senses", event: "senses.shepherd_chain_error",
                     message: "Shepherd chain failed during shutdown", meta: { agent, error: (0, redact_1.redactSecrets)(String(error)) } });
             });

package/npm-shrinkwrap.json

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