@ouro.bot/cli 0.1.0-alpha.923 → 0.1.0-alpha.925

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

@@ -0,0 +1,262 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noticeRecordId = noticeRecordId;
+exports.readNoticeOutbox = readNoticeOutbox;
+exports.enqueueNotice = enqueueNotice;
+exports.noticeDeliveryState = noticeDeliveryState;
+exports.knownNotice = knownNotice;
+exports.declareNoticeTargets = declareNoticeTargets;
+exports.claimPendingNotices = claimPendingNotices;
+exports.recordNoticeDelivery = recordNoticeDelivery;
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_util_1 = require("node:util");
+const file_lock_1 = require("../../heart/file-lock");
+const runtime_1 = require("../../nerves/runtime");
+const redact_1 = require("./redact");
+const returns_1 = require("./returns");
+const MAX_BYTES = 2 * 1024 * 1024;
+const RECENT_SENT = 256;
+const STATES = new Set(["pending", "sent", "unknown"]);
+const KINDS = new Set(["premature", "gate", "done", "working", "waiting", "unclear", "error", "loop_guard"]);
+const fileFor = (root) => path.join((0, returns_1.shepherdStateDir)(root), "notice-outbox.json");
+const object = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const nullableString = (value) => value === null || typeof value === "string";
+function isReturn(value) {
+    return object(value)
+        && ["at", "host", "session", "transition", "kind", "action", "reason"].every(key => typeof value[key] === "string")
+        && KINDS.has(String(value.kind)) && ["respond", "let_through"].includes(String(value.action))
+        && ["agent", "cwd", "task", "reply"].every(key => nullableString(value[key]))
+        && ["latencyMs", "inputTokens"].every(key => value[key] === null || typeof value[key] === "number")
+        && (value.title === undefined || typeof value.title === "string")
+        && (value.workspaceTitle === undefined || nullableString(value.workspaceTitle));
+}
+function isDelivery(value) {
+    return object(value) && typeof value.state === "string" && STATES.has(value.state)
+        && typeof value.at === "string" && Number.isSafeInteger(value.attempts) && Number(value.attempts) >= 0
+        && (value.reason === undefined || typeof value.reason === "string")
+        && (value.messageId === undefined || typeof value.messageId === "string");
+}
+function noticeRecordId(record) {
+    return (0, node_crypto_1.createHash)("sha256").update(JSON.stringify([record.host, record.session, record.transition, record.at])).digest("hex");
+}
+function readNoticeOutbox(root) {
+    let raw;
+    try {
+        raw = fs.readFileSync(fileFor(root), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    if (Buffer.byteLength(raw) > MAX_BYTES)
+        throw new Error("Shepherd notice outbox exceeds its 2 MiB limit");
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("Shepherd notice outbox is malformed JSON");
+    }
+    if (!object(value) || value.schemaVersion !== 1 || !Array.isArray(value.entries))
+        throw new Error("invalid Shepherd notice outbox schema");
+    const entries = [];
+    const seen = new Set();
+    for (const entry of value.entries) {
+        if (!object(entry) || typeof entry.id !== "string" || !isReturn(entry.record)
+            || !object(entry.deliveries) || !Object.values(entry.deliveries).every(isDelivery)
+            || entry.id !== noticeRecordId(entry.record) || seen.has(entry.id))
+            throw new Error("invalid Shepherd notice outbox entry");
+        seen.add(entry.id);
+        entries.push({ id: entry.id, record: entry.record, deliveries: entry.deliveries });
+    }
+    return entries;
+}
+function atomicWrite(file, value) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const encoded = JSON.stringify(value);
+    if (Buffer.byteLength(encoded) > MAX_BYTES)
+        throw new Error("Shepherd notice outbox exceeds its 2 MiB limit");
+    const temp = `${file}.${(0, node_crypto_1.randomUUID)()}.tmp`;
+    const fd = fs.openSync(temp, "wx", 0o600);
+    try {
+        fs.writeFileSync(fd, encoded);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    fs.renameSync(temp, file);
+}
+function persist(root, entries) {
+    const sent = entries.filter(entry => Object.keys(entry.deliveries).length > 0 && Object.values(entry.deliveries).every(value => value.state === "sent"));
+    const older = sent.slice(0, Math.max(0, sent.length - RECENT_SENT));
+    const ids = new Set(older.map(entry => entry.id));
+    // Archive acceptances before removing their payloads from the active snapshot.
+    for (const entry of older)
+        atomicWrite(path.join((0, returns_1.shepherdStateDir)(root), "notice-receipts", `${entry.id}.json`), entry);
+    atomicWrite(fileFor(root), { schemaVersion: 1, entries: entries.filter(entry => !ids.has(entry.id)) });
+}
+function archived(root, id) {
+    const file = path.join((0, returns_1.shepherdStateDir)(root), "notice-receipts", `${id}.json`);
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    const value = JSON.parse(raw);
+    if (!object(value) || value.id !== id || !isReturn(value.record) || !object(value.deliveries)
+        || !Object.values(value.deliveries).every(isDelivery))
+        throw new Error("invalid archived Shepherd notice receipt");
+    return { id, record: value.record, deliveries: value.deliveries };
+}
+function mutate(root, change) {
+    const dir = (0, returns_1.shepherdStateDir)(root);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return (0, file_lock_1.withFileLock)(dir, "notice-outbox", () => {
+        const entries = readNoticeOutbox(root);
+        const result = change(entries);
+        persist(root, entries);
+        return result;
+    }, { waitMs: 1000 });
+}
+function enqueueNotice(root, record) {
+    if (!isReturn(record))
+        return Promise.reject(new Error("invalid Shepherd return for a notice"));
+    const redacted = {
+        ...record,
+        reason: (0, redact_1.redactSecrets)(record.reason),
+        reply: record.reply === null ? null : (0, redact_1.redactSecrets)(record.reply),
+        ...(record.title !== undefined ? { title: (0, redact_1.redactSecrets)(record.title) } : {}),
+        ...(record.workspaceTitle !== undefined && record.workspaceTitle !== null ? { workspaceTitle: (0, redact_1.redactSecrets)(record.workspaceTitle) } : {}),
+    };
+    const normalized = JSON.parse(JSON.stringify(redacted));
+    if (!isReturn(normalized))
+        return Promise.reject(new Error("invalid normalized Shepherd return for a notice"));
+    const safe = normalized;
+    const id = noticeRecordId(safe);
+    return mutate(root, entries => {
+        const existing = entries.find(entry => entry.id === id) ?? archived(root, id);
+        if (existing && !(0, node_util_1.isDeepStrictEqual)(existing.record, safe))
+            throw new Error("the same return has a different notice body");
+        if (!existing)
+            entries.push({ id, record: safe, deliveries: {} });
+        return id;
+    }).then(value => {
+        (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_notice_queued", message: "persisted a Shepherd owner notice intent", meta: { id } });
+        return value;
+    });
+}
+function noticeDeliveryState(entry, friendId) {
+    return Object.hasOwn(entry.deliveries, friendId) ? entry.deliveries[friendId].state : "pending";
+}
+function knownNotice(root, id, entries) {
+    if (!/^[a-f0-9]{64}$/.test(id))
+        throw new Error(`unknown notice: ${id}`);
+    return entries.find(value => value.id === id) ?? archived(root, id);
+}
+function validTarget(friendId) {
+    return !!friendId && !["__proto__", "constructor", "prototype"].includes(friendId);
+}
+function selectedEntries(root, entries, ids) {
+    return ids.map(id => {
+        const entry = knownNotice(root, id, entries);
+        if (!entry)
+            throw new Error(`unknown notice: ${id}`);
+        return entry;
+    });
+}
+function declareNoticeTargets(root, ids, friendIds, at) {
+    if (!friendIds.every(validTarget))
+        return Promise.reject(new Error("invalid notice target"));
+    return mutate(root, entries => {
+        for (const entry of selectedEntries(root, entries, ids)) {
+            if (!entries.includes(entry) && friendIds.some(friendId => !Object.hasOwn(entry.deliveries, friendId)))
+                throw new Error("notice is already settled; it cannot acquire new recipients");
+            for (const friendId of friendIds) {
+                if (!Object.hasOwn(entry.deliveries, friendId))
+                    entry.deliveries[friendId] = { state: "pending", at, attempts: 0 };
+            }
+        }
+    });
+}
+/** Claim under the same cross-process lock as receipts, before any transport side effect. */
+function claimPendingNotices(root, ids, friendId, at) {
+    if (!validTarget(friendId))
+        return Promise.reject(new Error("invalid notice target"));
+    return mutate(root, entries => {
+        const claimed = selectedEntries(root, entries, ids).filter(entry => noticeDeliveryState(entry, friendId) === "pending");
+        for (const entry of claimed) {
+            if (!entries.includes(entry))
+                throw new Error("notice is already settled; it cannot acquire new recipients");
+            entry.deliveries[friendId] = {
+                state: "unknown", at, reason: "awaiting transport acceptance", attempts: (entry.deliveries[friendId]?.attempts ?? 0) + 1,
+            };
+        }
+        return claimed;
+    });
+}
+function recordNoticeDelivery(root, ids, friendId, receipt) {
+    if (!validTarget(friendId))
+        return Promise.reject(new Error("invalid notice target"));
+    return mutate(root, entries => {
+        let updated = 0;
+        for (const entry of selectedEntries(root, entries, ids)) {
+            if (!entries.includes(entry) && !Object.hasOwn(entry.deliveries, friendId))
+                throw new Error("notice is already settled; it cannot acquire new recipients");
+            const previous = Object.hasOwn(entry.deliveries, friendId) ? entry.deliveries[friendId] : undefined;
+            // A late failure cannot erase an acceptance another worker already recorded.
+            if (previous?.state === "sent")
+                continue;
+            entry.deliveries[friendId] = {
+                ...receipt,
+                ...(receipt.reason ? { reason: (0, redact_1.redactSecrets)(receipt.reason) } : {}),
+                attempts: previous?.state === "unknown" ? previous.attempts : (previous?.attempts ?? 0) + 1,
+            };
+            updated += 1;
+        }
+        return updated;
+    }).then(updated => {
+        if (updated > 0)
+            (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_notice_receipt", message: "persisted a Shepherd owner notice delivery outcome", meta: { friendId, state: receipt.state, notices: updated } });
+    });
+}

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

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NOTICE_LIST_MAX = exports.NOTICE_COALESCE_MS = void 0;
+exports.NOTICE_RETRY_MS = exports.NOTICE_LIST_MAX = exports.NOTICE_COALESCE_MS = void 0;
 exports.noticeWanted = noticeWanted;
 exports.plain = plain;
 exports.noticeLine = noticeLine;
@@ -47,6 +47,8 @@ const friends_1 = require("@ouro.bot/friends");
 const await_alert_1 = require("../../heart/awaiting/await-alert");
 const config_1 = require("../../heart/config");
 const runtime_1 = require("../../nerves/runtime");
+const returns_1 = require("./returns");
+const notice_outbox_1 = require("./notice-outbox");
 /**
  * The owner notice: after a judged return, the agent's owner hears what happened in one short plain message on their
  * own channel. It is deterministic, written here and sent with no model turn, so the owner hears about every return the
@@ -55,6 +57,7 @@ const runtime_1 = require("../../nerves/runtime");
 exports.NOTICE_COALESCE_MS = 5_000;
 /** Returns named one by one in a coalesced message; the rest are counted. */
 exports.NOTICE_LIST_MAX = 6;
+exports.NOTICE_RETRY_MS = 30_000;
 const NAME_MAX = 60;
 const REASON_MAX = 300;
 const REPLY_MAX = 240;
@@ -105,6 +108,8 @@ function noticeLine(record, location) {
             return `${subject} needs you. ${why}`;
         case "done":
             return `${subject} says it is done. ${why}`;
+        case "waiting":
+            return `${subject} is waiting on an outside dependency; the work is not yet delivered. ${why}`;
         case "loop_guard":
             return `${subject}: I stopped answering it after too many replies, so it is waiting for you. ${why}`;
         case "working":
@@ -184,7 +189,7 @@ function createTeamsNoticeSender(agentRoot, deps = {}) {
             bot.catch(() => bots.delete(config.clientId));
         }
         const { sendProactiveTeamsMessageToSession } = await Promise.resolve().then(() => __importStar(require("../teams")));
-        return sendProactiveTeamsMessageToSession({ friendId: target.friendId, sessionKey: target.key, text, textFormat: "plain", intent: "generic_outreach" }, { botApi: await bot, store: new friends_1.FileFriendStore(path.join(agentRoot, "friends")) });
+        return sendProactiveTeamsMessageToSession({ friendId: target.friendId, sessionKey: target.key, text, textFormat: "plain", intent: "generic_outreach", captureReceipt: true }, { botApi: await bot, store: new friends_1.FileFriendStore(path.join(agentRoot, "friends")) });
     };
 }
 /** Collects notices for NOTICE_COALESCE_MS after the first, then sends them as one message. It never throws. */
@@ -192,15 +197,39 @@ function createOwnerNotifier(options) {
     const { agent, policy } = options;
     const resolveTargets = options.resolveTargets ?? (() => resolveNoticeTargets(options.agentRoot));
     const send = options.send ?? createTeamsNoticeSender(options.agentRoot);
-    const waiting = [];
+    const retryWrites = new Map();
+    const writes = new Set();
     let cancel = null;
-    async function flush() {
+    let stopped = false;
+    let flushing = null;
+    function schedule(ms) {
+        if (!stopped && policy !== "off")
+            cancel ??= options.schedule(() => { void flush(); }, ms);
+    }
+    function persistIntent(record) {
+        const key = `${record.host}:${record.session}:${record.transition}:${record.at}`;
+        retryWrites.set(key, record);
+        const write = (0, notice_outbox_1.enqueueNotice)(options.agentRoot, record).then(() => {
+            retryWrites.delete(key);
+        }).catch(error => {
+            (0, runtime_1.emitNervesEvent)({ level: "error", component: "senses", event: "senses.shepherd_notice_error", message: "could not persist a Shepherd owner notice intent; it remains waiting", meta: { agent, error: error.message } });
+            schedule(exports.NOTICE_RETRY_MS);
+        }).finally(() => { writes.delete(write); });
+        writes.add(write);
+        return write;
+    }
+    async function runFlush() {
         cancel?.();
         cancel = null;
-        const records = waiting.splice(0);
-        if (records.length === 0)
+        if (stopped || policy === "off")
             return;
+        await Promise.all([...writes]);
+        for (const record of [...retryWrites.values()])
+            await persistIntent(record);
         try {
+            const entries = (0, notice_outbox_1.readNoticeOutbox)(options.agentRoot).filter(entry => noticeWanted(policy, entry.record) && (Object.keys(entry.deliveries).length === 0 || Object.values(entry.deliveries).some(value => value.state !== "sent")));
+            if (entries.length === 0)
+                return;
             const refs = new Map();
             try {
                 for (const session of await options.listSessions())
@@ -209,41 +238,86 @@ function createOwnerNotifier(options) {
             catch {
                 // Without the host's handles, each notice names a short session id instead.
             }
-            const text = noticeMessage(records, refs);
             const targets = await resolveTargets();
             if (targets.length === 0) {
-                (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_notice_no_target", message: "no family friend is reachable on Teams, so the Shepherd owner notice was not sent", meta: { agent, returns: records.length } });
+                (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_notice_no_target", message: "no family friend is reachable on Teams, so the Shepherd owner notice was not sent", meta: { agent, returns: entries.length } });
+                schedule(exports.NOTICE_RETRY_MS);
                 return;
             }
+            await (0, notice_outbox_1.declareNoticeTargets)(options.agentRoot, entries.map(entry => entry.id), targets.map(target => target.friendId), new Date().toISOString());
+            const reachable = new Set(targets.map(target => target.friendId));
+            let retry = entries.some(entry => Object.entries(entry.deliveries).some(([friendId, delivery]) => delivery.state === "pending" && !reachable.has(friendId)));
             for (const target of targets) {
-                try {
-                    const result = await send(target, text);
-                    (0, runtime_1.emitNervesEvent)({
-                        level: result.delivered ? "info" : "warn",
-                        component: "senses",
-                        event: result.delivered ? "senses.shepherd_notice_sent" : "senses.shepherd_notice_not_sent",
-                        message: result.delivered ? "sent the Shepherd owner notice" : "the Shepherd owner notice was not delivered",
-                        meta: { agent, friendId: target.friendId, returns: records.length, ...(result.delivered ? {} : { reason: result.reason ?? "unknown" }) },
-                    });
-                }
-                catch (error) {
-                    (0, runtime_1.emitNervesEvent)({ level: "error", component: "senses", event: "senses.shepherd_notice_error", message: "sending the Shepherd owner notice failed", meta: { agent, friendId: target.friendId, error: error.message } });
+                const pending = entries.filter(entry => (0, notice_outbox_1.noticeDeliveryState)(entry, target.friendId) === "pending");
+                for (let start = 0; start < pending.length && !stopped; start += exports.NOTICE_LIST_MAX) {
+                    // Only the worker that atomically claims a pending entry may initiate transport.
+                    const batch = await (0, notice_outbox_1.claimPendingNotices)(options.agentRoot, pending.slice(start, start + exports.NOTICE_LIST_MAX).map(entry => entry.id), target.friendId, new Date().toISOString());
+                    if (batch.length === 0)
+                        continue;
+                    const ids = batch.map(entry => entry.id);
+                    try {
+                        const result = await send(target, noticeMessage(batch.map(entry => entry.record), refs));
+                        const state = result.delivered ? "sent"
+                            : result.delivery ? result.delivery.state === "not_sent" ? "pending" : "unknown"
+                                : result.reason && result.reason !== "send_error" ? "pending" : "unknown";
+                        await (0, notice_outbox_1.recordNoticeDelivery)(options.agentRoot, ids, target.friendId, {
+                            state, at: new Date().toISOString(), ...(result.reason ? { reason: result.reason } : {}),
+                            ...(result.delivery?.messageId ? { messageId: result.delivery.messageId } : {}),
+                        });
+                        retry ||= state === "pending";
+                        (0, runtime_1.emitNervesEvent)({
+                            level: result.delivered ? "info" : "warn", component: "senses",
+                            event: result.delivered ? "senses.shepherd_notice_sent" : "senses.shepherd_notice_not_sent",
+                            message: result.delivered ? "sent the Shepherd owner notice" : "the Shepherd owner notice was not delivered",
+                            meta: { agent, friendId: target.friendId, returns: batch.length, ...(result.delivered ? {} : { reason: result.reason ?? "unknown" }) },
+                        });
+                    }
+                    catch (error) {
+                        (0, runtime_1.emitNervesEvent)({ level: "error", component: "senses", event: "senses.shepherd_notice_error", message: "sending the Shepherd owner notice failed; its outcome remains unknown", meta: { agent, friendId: target.friendId, error: error.message } });
+                    }
                 }
             }
+            if (retry)
+                schedule(exports.NOTICE_RETRY_MS);
         }
         catch (error) {
             (0, runtime_1.emitNervesEvent)({ level: "error", component: "senses", event: "senses.shepherd_notice_error", message: "preparing the Shepherd owner notice failed", meta: { agent, error: error.message } });
+            schedule(exports.NOTICE_RETRY_MS);
+        }
+    }
+    function flush() {
+        if (flushing)
+            return flushing;
+        flushing = runFlush().finally(() => { flushing = null; });
+        return flushing;
+    }
+    try {
+        const existing = (0, notice_outbox_1.readNoticeOutbox)(options.agentRoot);
+        let recovered = false;
+        for (const record of (0, returns_1.readReturns)(options.agentRoot)) {
+            if (record.noticeEligible === true && noticeWanted(policy, record) && !(0, notice_outbox_1.knownNotice)(options.agentRoot, (0, notice_outbox_1.noticeRecordId)(record), existing)) {
+                void persistIntent(record);
+                recovered = true;
+            }
         }
+        if (recovered || existing.some(entry => Object.keys(entry.deliveries).length === 0 || Object.values(entry.deliveries).some(value => value.state === "pending")))
+            schedule(exports.NOTICE_RETRY_MS);
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({ level: "error", component: "senses", event: "senses.shepherd_notice_error", message: "could not read waiting Shepherd owner notices", meta: { agent, error: error.message } });
+        schedule(exports.NOTICE_RETRY_MS);
     }
     return {
         notify(record) {
-            if (!noticeWanted(policy, record))
-                return;
-            waiting.push(record);
-            cancel ??= options.schedule(() => { void flush(); }, exports.NOTICE_COALESCE_MS);
+            if (stopped || !noticeWanted(policy, record))
+                return Promise.resolve();
+            const write = persistIntent(record);
+            schedule(exports.NOTICE_COALESCE_MS);
+            return write;
         },
         flush,
         stop() {
+            stopped = true;
             cancel?.();
             cancel = null;
         },

package/dist/senses/shepherd/sense.js

@@ -58,6 +58,7 @@ const judge_1 = require("./judge");
 const redact_1 = require("./redact");
 const owner_notice_1 = require("./owner-notice");
 const returns_1 = require("./returns");
+const guidance_1 = require("./guidance");
 /**
  * Ouro Shepherd: every time a coding agent in a terminal hands control back, a cheap judge decides
  * whether it should have. A premature return is answered in the terminal, visibly, as
@@ -108,7 +109,7 @@ function escalationContent(record, human) {
     const who = `${record.agent ? field(record.agent) : "A coding agent"}${record.cwd ? ` in ${field(path.basename(record.cwd))}` : ""}`;
     const what = record.kind === "loop_guard"
         ? `Shepherd answered it ${exports.STREAK_MAX} times in a row (or ${exports.HOURLY_MAX} in an hour) and stopped`
-        : record.kind === "gate" ? `it needs ${human}` : "it says the work is done";
+        : record.kind === "gate" ? `it needs ${human}` : record.kind === "waiting" ? "it is waiting on an outside dependency, not delivered done" : "it says the work is done";
     return [
         record.kind === "working" ? "[Shepherd update]" : "[Shepherd return]",
         record.kind === "working"
@@ -226,7 +227,10 @@ 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);
-            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 });
+            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 });
             // 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");
@@ -243,7 +247,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 (state.streak >= exports.STREAK_MAX || state.answers.length >= exports.HOURLY_MAX) {
+                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) {
                     Object.assign(record, { kind: "loop_guard", reason: `loop guard: ${verdict.reason}` });
                     state.tripped = true;
                 }
@@ -255,29 +262,52 @@ async function startShepherdSenseApp(options) {
                     record.reason = `the screen changed while judging, 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 });
-                    state.streak += 1;
-                    state.answers.push(now());
-                    await host.signal(event.sessionId, field(`answered for ${human}: ${verdict.reason}`, 120));
+                    // No awaited host reads between this final check and initiating the send.
+                    const latest = guidanceFor(target);
+                    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 });
+                        state.streak += 1;
+                        state.answers.push(now());
+                        await host.signal(event.sessionId, field(`answered for ${human}: ${verdict.reason}`, 120));
+                    }
                 }
             }
-            if (record.kind === "gate" || record.kind === "done" || record.kind === "loop_guard") {
+            if (record.kind === "gate" || record.kind === "done" || record.kind === "waiting" || record.kind === "loop_guard") {
                 escalate(escalationContent(record, human));
                 requestWake(event.transitionId);
-                await host.signal(event.sessionId, field(`${record.kind === "gate" ? `needs ${human}` : record.kind === "done" ? "done" : "stopped answering"}: ${verdict.reason}`, 120));
+                await host.signal(event.sessionId, field(`${record.kind === "gate" ? `needs ${human}` : record.kind === "done" ? "done" : record.kind === "waiting" ? "waiting on an outside dependency" : "stopped answering"}: ${verdict.reason}`, 120));
             }
         }
         catch (error) {
             Object.assign(record, { kind: record.reason ? record.kind : "error", reason: `${record.reason ? `${record.reason}; then ` : ""}${error.message}` });
         }
         finally {
+            record.noticeEligible = notice;
             log(record);
-            if (notice)
-                notifyOwner(record);
+            if (notice) {
+                try {
+                    await notifyOwner(record);
+                }
+                catch (error) {
+                    (0, runtime_1.emitNervesEvent)({ level: "error", component: "senses", event: "senses.shepherd_notice_error", message: "owner notice custody failed; the eligible return remains logged for recovery", meta: { agent, error: error.message } });
+                }
+            }
+        }
+    }
+    function guidanceFor(target) {
+        try {
+            return (0, guidance_1.applicableGuidance)((0, guidance_1.readGuidance)(agentRoot), target);
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_guidance_error", message: "could not load Shepherd guidance; automatic replies fail closed", meta: { agent, session: target.session, error: (0, redact_1.redactSecrets)(error.message) } });
+            throw error;
         }
     }
     function log(record) {