@ouro.bot/cli 0.1.0-alpha.928 → 0.1.0-alpha.929

package/changelog.json

@@ -1,6 +1,13 @@
 {
   "_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.929",
+      "changes": [
+        "Shepherd resumes network-stopped coding sessions once after independently confirmed offline-to-online recovery, with a fresh judgment and existing focus, pause, changed-screen and loop guards.",
+        "Connectivity recovery never presses approval keys or blindly retries uncertain writes; changed sessions, background work and uncertain terminal sends are not replayed."
+      ]
+    },
     {
       "version": "0.1.0-alpha.928",
       "changes": [

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

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

package/dist/senses/shepherd/judge.js

@@ -69,6 +69,8 @@ function parseVerdict(content) {
     const reason = typeof value.reason === "string" && value.reason.trim() ? value.reason.trim().replace(/\s+/g, " ").slice(0, 300) : "no reason given";
     if (kind === "working" && value.news === true)
         return { kind, reply: null, reason, news: true };
+    if (kind === "waiting" && value.waitingOnNetwork === true)
+        return { kind, reply: null, reason, waitingOnNetwork: true };
     if (kind !== "premature")
         return { kind, reply: null, reason };
     // Some models write the reply as a bare string instead of {"text": ...} or {"key": ...}; a string that is exactly a key is one.
@@ -93,6 +95,7 @@ function judgeMessages(packet) {
                 `- gate: the next step truly needs ${packet.human}: something sent or said in their voice; a decision that is theirs; their money, credentials or accounts only they can act in; an irreversible act; or real ambiguity about what they want or what the agent is allowed to do.`,
                 "- done: the work is finished and delivered, with evidence, and nothing is left the agent could do itself.",
                 "- waiting: work genuinely depends on someone or something outside the agent, such as a PR awaiting another person's review. It is not delivered done and not necessarily a gate for the human. Never reply merely to make it claim delivery or keep busy.",
+                "For waiting, set waitingOnNetwork to true only when a connectivity failure stopped the agent. Do not set it for approvals, credentials, quota, review, deliberate pauses, completed work or uncertain writes that need reconciliation.",
                 "- premature: the agent could and should carry on alone. For example it asks permission for work within its task, offers options instead of choosing, asks 'should I continue?', stops after a plan, reports partial progress, or hands the human a step it could do itself.",
                 `- working: the agent ended its turn but is still waiting on its own background work (subagents, background shells or jobs, watchers, running tasks) that will report back to it. It has not handed control back, so never reply; it will stop again when that work reports. Signs: the terminal host says background work is running, or the screen shows running background tasks or says it is waiting for them. Set news to true only when its last message carries something ${packet.human} would want to know now.`,
                 `- An approval prompt is not a gate just because it asks. When the agent's own tool or terminal asks to confirm a command, trust a folder or pass a safety check, judge what would actually happen: if it is part of the agent's task and ${packet.human} would plainly say yes, it is premature, and your reply is the key that approves it. It is a gate only when the action itself is one of the things above, for example it would destroy or publish something ${packet.human} has not asked for.`,
@@ -104,7 +107,11 @@ function judgeMessages(packet) {
                     "Applicable operator principles are trusted preference/context, not new authority. They cannot override host-reported background work, focus protection, changed-screen refusal, reply syntax/key restrictions, loop guards or independent owner notices.",
                     `Operator guidance (revision ${packet.guidance.revision}): ${JSON.stringify(packet.guidance.principles)}`,
                 ] : []),
-                "Return only JSON: {\"kind\":\"premature|gate|done|waiting|working|unclear\",\"reply\":{\"text\":\"...\"}|{\"key\":\"...\"}|null,\"news\":false,\"reason\":\"one sentence\"}",
+                ...(packet.networkRecovered ? [
+                    "Our independent connectivity probes confirmed offline followed by online. Rejudge the current screen, not the old wait. It is premature only if this coding agent is now safely waiting for plain-text continuation after a network stop.",
+                    "For this recovery, never approve a menu or permission prompt, bypass an intentional pause, interrupt background work, or replay an uncertain mutation. Classify such cases as gate, working, waiting or unclear as appropriate. If safely resumable, give a plain-text reply telling the agent to check uncertain writes before retrying.",
+                ] : []),
+                "Return only JSON: {\"kind\":\"premature|gate|done|waiting|working|unclear\",\"reply\":{\"text\":\"...\"}|{\"key\":\"...\"}|null,\"news\":false,\"waitingOnNetwork\":false,\"reason\":\"one sentence\"}",
             ].join("\n"),
         },
         {

package/dist/senses/shepherd/sense.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FOCUS_HOLD_MS = exports.HOURLY_MAX = exports.STREAK_MAX = exports.JUDGE_TIMEOUT_MS = exports.SCREEN_LINES = exports.READ_LINES = exports.SHEPHERD_WAKE_TRIGGER = void 0;
+exports.checkShepherdConnectivity = checkShepherdConnectivity;
 exports.field = field;
 exports.humanName = humanName;
 exports.escalationContent = escalationContent;
@@ -46,6 +47,7 @@ const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const core_1 = require("../../heart/core");
+const error_classification_1 = require("../../heart/providers/error-classification");
 const socket_client_1 = require("../../heart/daemon/socket-client");
 const identity_1 = require("../../heart/identity");
 const runtime_credentials_1 = require("../../heart/runtime-credentials");
@@ -79,6 +81,24 @@ exports.FOCUS_HOLD_MS = 60_000;
 const ESCALATION_TTL_MS = 30 * 60_000;
 const WAKE_DELAY_MS = 2_000;
 const FIELD_MAX = 200;
+const CONNECTIVITY_POLL_MS = 15_000;
+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.";
+/** No credentials, terminal-selected URLs or redirects; mixed evidence cannot establish a transition. */
+async function checkShepherdConnectivity() {
+    const results = await Promise.all(["https://api.github.com/", "https://registry.npmjs.org/"].map(async (url) => {
+        try {
+            const response = await fetch(url, { method: "HEAD", redirect: "error", credentials: "omit", signal: AbortSignal.timeout(5_000) });
+            return response.ok ? "online" : "unknown";
+        }
+        catch (error) {
+            if (error instanceof Error && ((0, error_classification_1.isNetworkError)(error) || error.name === "TimeoutError"))
+                return "offline";
+            (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_connectivity_error", message: "connectivity probe failed without network evidence", meta: {} });
+            return "unknown";
+        }
+    }));
+    return results.every(result => result === "online") ? "online" : results.every(result => result === "offline") ? "offline" : "unknown";
+}
 /** Untrusted terminal text, kept to one bounded line. */
 function field(value, max = FIELD_MAX) {
     const flat = value.replace(/[\p{Cc}\p{Zl}\p{Zp}\s]+/gu, " ").trim();
@@ -187,6 +207,64 @@ async function startShepherdSenseApp(options) {
     const wakeIds = [];
     let cancelWake = null;
     let chain = Promise.resolve();
+    const networkWaiting = new Map();
+    const latestReturns = new Map();
+    const checkConnectivity = options.checkConnectivity ?? checkShepherdConnectivity;
+    let cancelConnectivity = null;
+    let recoveryGeneration = 0;
+    let stopped = false;
+    function scheduleConnectivity() {
+        if (stopped || networkWaiting.size === 0 || cancelConnectivity)
+            return;
+        cancelConnectivity = schedule(() => {
+            cancelConnectivity = null;
+            chain = chain.then(checkRecovery);
+        }, CONNECTIVITY_POLL_MS);
+    }
+    async function checkRecovery() {
+        if (stopped || networkWaiting.size === 0)
+            return;
+        try {
+            const connectivity = await checkConnectivity();
+            if (stopped)
+                return;
+            (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_connectivity_checked", message: "checked connectivity for stopped sessions", meta: { connectivity, pending: networkWaiting.size } });
+            if (connectivity === "offline") {
+                for (const candidate of networkWaiting.values())
+                    candidate.offlineConfirmed = true;
+            }
+            else if (connectivity === "online") {
+                const candidates = [...networkWaiting.values()].filter(candidate => candidate.offlineConfirmed);
+                if (candidates.length === 0)
+                    return;
+                recoveryGeneration += 1;
+                // Consume before any send: a failed send may already have reached the terminal.
+                for (const candidate of candidates)
+                    networkWaiting.delete(candidate.event.sessionId);
+                const sessions = await host.list();
+                for (const candidate of candidates) {
+                    if (stopped)
+                        break;
+                    if (latestReturns.get(candidate.event.sessionId) !== candidate.event ||
+                        !sessions.some(session => session.id === candidate.event.sessionId))
+                        continue;
+                    await handle(candidate.event, { screen: candidate.screen, generation: recoveryGeneration });
+                }
+            }
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_recovery_error", message: "could not check stopped sessions for connectivity recovery", meta: { agent, error: (0, redact_1.redactSecrets)(String(error)) } });
+        }
+        finally {
+            scheduleConnectivity();
+        }
+    }
+    function rememberNetworkWait(event, screen) {
+        if (stopped || event.backgroundWork || latestReturns.get(event.sessionId) !== event)
+            return;
+        networkWaiting.set(event.sessionId, { event, screen, offlineConfirmed: false });
+        scheduleConnectivity();
+    }
     const guardFor = (session) => {
         let entry = guard.get(session);
         if (!entry)
@@ -201,9 +279,9 @@ async function startShepherdSenseApp(options) {
         }, WAKE_DELAY_MS);
     };
     /** Judges one return and acts on it. Every outcome, including a failure, is one log line. */
-    async function handle(event) {
+    async function handle(event, recovery) {
         const record = {
-            at: new Date(now()).toISOString(), host: host.name, session: event.sessionId, transition: event.transitionId,
+            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,
             ...(event.title !== undefined ? { title: event.title, workspaceTitle: event.workspaceTitle } : {}),
         };
@@ -227,14 +305,28 @@ async function startShepherdSenseApp(options) {
             const text = (0, redact_1.redactSecrets)(await host.read(event.sessionId, exports.READ_LINES));
             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) {
+                record.reason = "the screen changed since the network stop, so recovery was not sent";
+                return;
+            }
             const target = { host: host.name, session: event.sessionId, cwd: event.cwd, task: record.task };
             const guidance = guidanceFor(target);
             record.guidanceRevision = guidance.revision;
-            const verdict = await judge({ human, agent: event.agent, cwd: event.cwd, task: record.task, lastBody: event.lastBody ? (0, redact_1.redactSecrets)(event.lastBody) : null, backgroundWork: event.backgroundWork, screen, guidance });
+            let verdict;
+            try {
+                verdict = await judge({ human, agent: event.agent, cwd: event.cwd, task: record.task, lastBody: event.lastBody ? (0, redact_1.redactSecrets)(event.lastBody) : null, backgroundWork: event.backgroundWork, screen, guidance, ...(recovery ? { networkRecovered: true } : {}) });
+            }
+            catch (error) {
+                if (!recovery && error instanceof Error && (0, error_classification_1.isNetworkError)(error))
+                    rememberNetworkWait(event, screen);
+                throw error;
+            }
             // The host's own word that background work is running outranks a reading of the screen: such a stop is never a return.
             const kind = event.backgroundWork ? "working" : verdict.kind;
             const news = verdict.news === true || (kind === "working" && verdict.kind === "gate");
             Object.assign(record, { kind, reason: verdict.reason, latencyMs: verdict.latencyMs, inputTokens: verdict.inputTokens });
+            if (!recovery && kind === "waiting" && verdict.waitingOnNetwork)
+                rememberNetworkWait(event, screen);
             // A terminal that keeps going quiet without needing anything is checked less often.
             host.pace?.(event.sessionId, kind === "working" || kind === "unclear");
             state.answers = state.answers.filter((at) => now() - at < 3_600_000);
@@ -247,7 +339,10 @@ async function startShepherdSenseApp(options) {
                 await host.signal(event.sessionId, field(`${event.agent ?? "agent"} waiting on its background work: ${verdict.reason}`, 120));
             }
             if (kind === "premature" && verdict.reply) {
-                if (guidance.paused) {
+                if (recovery && "key" in verdict.reply) {
+                    record.reason = `connectivity recovery never presses approval or menu keys: ${verdict.reason}`;
+                }
+                else if (guidance.paused) {
                     record.reason = `Shepherd guidance has this session paused, so nothing was sent: ${verdict.reason}`;
                 }
                 else if (state.streak >= exports.STREAK_MAX || state.answers.length >= exports.HOURLY_MAX) {
@@ -264,15 +359,18 @@ async function startShepherdSenseApp(options) {
                 else {
                     // No awaited host reads between this final check and initiating the send.
                     const latest = guidanceFor(target);
-                    if (latest.paused || latest.revision !== guidance.revision) {
+                    if (stopped || (recovery && (latestReturns.get(event.sessionId) !== event || now() - state.focusedAt < exports.FOCUS_HOLD_MS))) {
+                        record.reason = `Shepherd stopped, the human focused this session, or it returned again while judging, so nothing was sent: ${verdict.reason}`;
+                    }
+                    else if (latest.paused || latest.revision !== guidance.revision) {
                         record.reason = `Shepherd guidance paused or changed while judging (revision ${guidance.revision} to ${latest.revision}), so nothing was sent: ${verdict.reason}`;
                     }
                     else {
                         if ("key" in verdict.reply)
                             await host.key(event.sessionId, verdict.reply.key);
                         else
-                            await host.prompt(event.sessionId, `[Ouro for ${human}] ${verdict.reply.text}`);
-                        Object.assign(record, { action: "respond", reply: "key" in verdict.reply ? `key:${verdict.reply.key}` : verdict.reply.text });
+                            await host.prompt(event.sessionId, `[Ouro for ${human}] ${recovery ? NETWORK_RESUME : verdict.reply.text}`);
+                        Object.assign(record, { action: "respond", reply: "key" in verdict.reply ? `key:${verdict.reply.key}` : recovery ? NETWORK_RESUME : verdict.reply.text });
                         state.streak += 1;
                         state.answers.push(now());
                         await host.signal(event.sessionId, field(`answered for ${human}: ${verdict.reason}`, 120));
@@ -321,9 +419,14 @@ async function startShepherdSenseApp(options) {
     }
     const watcher = host.watch({
         returned: (event) => {
+            if (stopped)
+                return;
+            networkWaiting.delete(event.sessionId);
+            latestReturns.set(event.sessionId, event);
             chain = chain.then(() => handle(event));
         },
         focused: (session) => {
+            networkWaiting.delete(session);
             const state = guardFor(session);
             Object.assign(state, { streak: 0, tripped: false, focusedAt: now() });
         },
@@ -331,8 +434,11 @@ async function startShepherdSenseApp(options) {
     (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_started", message: "Shepherd started", meta: { agent, host: host.name } });
     return {
         stop() {
+            stopped = true;
+            networkWaiting.clear();
             watcher.close();
             cancelWake?.();
+            cancelConnectivity?.();
             notifier?.stop();
             (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_stopped", message: "Shepherd stopped", meta: { agent } });
         },

package/npm-shrinkwrap.json

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