@ouro.bot/cli 0.1.0-alpha.876 → 0.1.0-alpha.878

package/dist/heart/failure-reports.js

@@ -0,0 +1,335 @@
+"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.CLOSED_REPORT_RETENTION_MS = exports.REPORTS_PER_ORIGIN_DAY = exports.REPORTS_PER_ORIGIN_HOUR = exports.REPORTS_PER_DAY = exports.REPORTS_PER_HOUR = void 0;
+exports.reportsDir = reportsDir;
+exports.errorClass = errorClass;
+exports.failureFingerprint = failureFingerprint;
+exports.readFailureReport = readFailureReport;
+exports.listFailureReports = listFailureReports;
+exports.reportBody = reportBody;
+exports.pruneClosedReports = pruneClosedReports;
+exports.fileFailureReport = fileFailureReport;
+exports.resolveFailureReport = resolveFailureReport;
+exports.fixLiveNoticeText = fixLiveNoticeText;
+exports.confirmResolvedReports = confirmResolvedReports;
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const semver = __importStar(require("semver"));
+const a2a_client_1 = require("@ouro.bot/friends/a2a-client");
+const escalation_grants_1 = require("../a2a/escalation-grants");
+const outbox_store_1 = require("../a2a/outbox-store");
+const resolution_proof_1 = require("../a2a/resolution-proof");
+const replay_harness_1 = require("../a2a/replay-harness");
+const runtime_1 = require("../nerves/runtime");
+const file_lock_1 = require("./file-lock");
+exports.REPORTS_PER_HOUR = 5;
+exports.REPORTS_PER_DAY = 20;
+exports.REPORTS_PER_ORIGIN_HOUR = 3;
+exports.REPORTS_PER_ORIGIN_DAY = 10;
+exports.CLOSED_REPORT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+const FIELD_MAX_CHARS = 2_000;
+const HOUR_MS = 60 * 60 * 1000;
+const DAY_MS = 24 * HOUR_MS;
+const REPORT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
+function reportsDir(agentRoot) {
+    return path.join(agentRoot, "state", "reports");
+}
+function reportFile(agentRoot, id) {
+    return path.join(reportsDir(agentRoot), `${id}.json`);
+}
+function cap(value) {
+    return value.trim().slice(0, FIELD_MAX_CHARS);
+}
+/** The same failure reads the same: numbers, ids and paths are blanked so a retry with a new request id folds in. */
+function errorClass(error) {
+    return error.toLowerCase()
+        .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gu, "<id>")
+        .replace(/(?:\/[\w.@-]+){2,}/gu, "<path>")
+        .replace(/\d+/gu, "<n>")
+        .replace(/\s+/gu, " ").trim().slice(0, 80);
+}
+function failureFingerprint(failedTool, error) {
+    return (0, node_crypto_1.createHash)("sha256").update(`${(failedTool ?? "").trim().toLowerCase()}\0${errorClass(error)}`).digest("hex").slice(0, 16);
+}
+function readFailureReport(agentRoot, id) {
+    if (!REPORT_ID.test(id))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(reportFile(agentRoot, id), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function writeReport(agentRoot, record) {
+    fs.mkdirSync(reportsDir(agentRoot), { recursive: true });
+    const file = reportFile(agentRoot, record.id);
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, file);
+}
+function listFailureReports(agentRoot) {
+    let names;
+    try {
+        names = fs.readdirSync(reportsDir(agentRoot));
+    }
+    catch {
+        return [];
+    }
+    return names.filter((name) => name.endsWith(".json")).flatMap((name) => {
+        const record = readFailureReport(agentRoot, name.slice(0, -5));
+        return record ? [record] : [];
+    });
+}
+function reportBody(record) {
+    const { origin } = record;
+    return [
+        `Failure report ${record.shortId} (${record.severity})${origin.ownerOrigin ? "" : " - UNTRUSTED ORIGIN: not the owner's session"}`,
+        origin.ownerOrigin ? `Ari asked: ${record.ariWords}` : `A session with ${origin.friendName ?? "an unknown friend"} (${origin.trustLevel ?? "unknown trust"}) reported: ${record.ariWords}`,
+        `I tried: ${record.tried}`,
+        `${record.failedTool ? `${record.failedTool} failed` : "I gave up"}: ${record.error}`,
+        `Conversation: ${origin.channel ?? "unknown"}/${origin.key ?? "unknown"}`,
+        `Origin: friend ${origin.friendId ?? "unknown"}, trust ${origin.trustLevel ?? "unknown"}, owner ${origin.ownerOrigin ? "yes" : "no"}`,
+    ].join("\n");
+}
+/** The origin friend, read from the friend store: only an active family friend on the owner profile is the owner. */
+async function resolveOrigin(store, origin) {
+    const friend = origin.friendId ? await store.get(origin.friendId) : null;
+    const ownerOrigin = Boolean(friend && friend.admissionState === "active" && friend.trustLevel === "family" && friend.capabilityProfileId === "sanctuary-owner");
+    return { ...origin, friendName: friend ? friend.name : null, trustLevel: friend ? String(friend.trustLevel) : null, ownerOrigin };
+}
+/** Closed reports are history; they go after a month so the directory does not grow without bound. */
+function pruneClosedReports(agentRoot, now = Date.now()) {
+    let pruned = 0;
+    for (const record of listFailureReports(agentRoot)) {
+        if (record.status === "closed" && record.closedAt && now - Date.parse(record.closedAt) > exports.CLOSED_REPORT_RETENTION_MS) {
+            fs.rmSync(reportFile(agentRoot, record.id), { force: true });
+            pruned += 1;
+        }
+    }
+    return pruned;
+}
+function lockDir(agentRoot) {
+    return path.join(reportsDir(agentRoot), ".locks");
+}
+function overBudget(created, now, perHour, perDay) {
+    return created.filter((at) => now - at < HOUR_MS).length >= perHour || created.filter((at) => now - at < DAY_MS).length >= perDay;
+}
+async function fileFailureReport(agentRoot, store, input, now = Date.now()) {
+    const ariWords = cap(input.ariWords);
+    const tried = cap(input.tried);
+    const error = cap(input.error);
+    if (!ariWords || !tried || !error)
+        return { ok: false, reason: "invalid", detail: "ari_words, tried and error are all required" };
+    const failedTool = input.failedTool?.trim() ? input.failedTool.trim().slice(0, 120) : null;
+    const fingerprint = failureFingerprint(failedTool ?? undefined, error);
+    const origin = await resolveOrigin(store, input.origin);
+    const replay = origin.friendId !== null && (0, replay_harness_1.isReplayWindowOpen)(agentRoot, origin.friendId, now);
+    // A replay identity speaks only inside its window; once the window closes it must not reach a real outbox.
+    if (!replay && origin.friendId !== null && (0, replay_harness_1.isReplayIdentity)(agentRoot, origin.friendId))
+        return { ok: false, reason: "invalid", detail: "a replay identity can file only while its replay window is open" };
+    // One lock around read, rate check and write, so two processes cannot both pass the budget or file the same failure twice.
+    return (0, file_lock_1.withFileLock)(lockDir(agentRoot), "file", async () => {
+        pruneClosedReports(agentRoot, now);
+        const existing = listFailureReports(agentRoot);
+        // A replay conversation never folds: each gate run must leave a fresh report to read back.
+        const open = replay ? undefined : existing.find((record) => !record.replay && record.fingerprint === fingerprint && record.status !== "closed");
+        if (open) {
+            const folded = await foldRepeat(agentRoot, open.id, { error, failedTool, origin }, now);
+            if (folded)
+                return folded;
+        }
+        const holders = (await (0, escalation_grants_1.escalationHolders)(agentRoot, store)).filter((holder) => replay ? (0, replay_harness_1.isReplayWindowOpen)(agentRoot, holder.id, now) : !(0, replay_harness_1.isReplayIdentity)(agentRoot, holder.id));
+        if (holders.length === 0)
+            return { ok: false, reason: "no_escalation_peer", detail: replay ? "no replay escalation peer" : "no friend holds the escalation grant" };
+        const sameKind = existing.filter((record) => record.replay === replay);
+        if (overBudget(sameKind.map((record) => Date.parse(record.createdAt)), now, exports.REPORTS_PER_HOUR, exports.REPORTS_PER_DAY)) {
+            return { ok: false, reason: "rate_limited", detail: `at most ${exports.REPORTS_PER_HOUR} new reports an hour and ${exports.REPORTS_PER_DAY} a day` };
+        }
+        if (overBudget(sameKind.filter((record) => record.origin.friendId === origin.friendId).map((record) => Date.parse(record.createdAt)), now, exports.REPORTS_PER_ORIGIN_HOUR, exports.REPORTS_PER_ORIGIN_DAY)) {
+            return { ok: false, reason: "rate_limited", detail: `at most ${exports.REPORTS_PER_ORIGIN_HOUR} new reports an hour and ${exports.REPORTS_PER_ORIGIN_DAY} a day from one origin` };
+        }
+        const id = (0, node_crypto_1.randomUUID)();
+        const record = {
+            id, shortId: id.slice(0, 8), fingerprint, createdAt: new Date(now).toISOString(), lastSeenAt: new Date(now).toISOString(), occurrences: 1,
+            severity: input.severity, ariWords, tried, error, failedTool, origin, replay,
+            recipients: holders.map((holder) => holder.id), outboxEntries: {}, status: "open",
+        };
+        const outbox = new outbox_store_1.FileOutboxStore(agentRoot);
+        for (const holder of holders) {
+            record.outboxEntries[holder.id] = outbox.append(holder.id, {
+                kind: "failure_report",
+                body: reportBody(record),
+                meta: {
+                    reportId: id, shortId: record.shortId, severity: record.severity, failedTool, fingerprint, ariWords: record.ariWords, conversation: { channel: origin.channel, key: origin.key },
+                    origin: { friendId: origin.friendId, friendName: origin.friendName, trustLevel: origin.trustLevel, ownerOrigin: origin.ownerOrigin },
+                },
+            }, now).id;
+        }
+        writeReport(agentRoot, record);
+        (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.failure_report_filed", message: "filed a failure report", meta: { reportId: id, severity: record.severity, recipients: holders.length, replay, ownerOrigin: origin.ownerOrigin } });
+        return { ok: true, id, shortId: record.shortId, duplicate: false, recipients: holders.length };
+    });
+}
+/** Counts a repeat on the open report (re-read under the report's own lock) and tells the recipients, at most once a day per report. */
+async function foldRepeat(agentRoot, id, repeat, now) {
+    return (0, file_lock_1.withFileLock)(lockDir(agentRoot), `report-${id}`, () => {
+        const fresh = readFailureReport(agentRoot, id);
+        if (!fresh || fresh.status === "closed")
+            return null;
+        const occurrences = fresh.occurrences + 1;
+        const notify = fresh.lastRepeatNoticeAt === undefined || now - Date.parse(fresh.lastRepeatNoticeAt) >= DAY_MS;
+        if (notify) {
+            const outbox = new outbox_store_1.FileOutboxStore(agentRoot);
+            for (const recipient of fresh.recipients) {
+                outbox.append(recipient, {
+                    kind: "report_repeat",
+                    body: `Failure report ${fresh.shortId} happened again (${occurrences} times so far)${repeat.origin.ownerOrigin ? "" : " - UNTRUSTED ORIGIN: not the owner's session"}. ${repeat.failedTool ? `${repeat.failedTool} failed` : "I gave up"}: ${repeat.error}`,
+                    meta: { reportId: fresh.id, shortId: fresh.shortId, occurrences, status: fresh.status, origin: { friendId: repeat.origin.friendId, friendName: repeat.origin.friendName, trustLevel: repeat.origin.trustLevel, ownerOrigin: repeat.origin.ownerOrigin } },
+                }, now);
+            }
+        }
+        writeReport(agentRoot, { ...fresh, occurrences, lastSeenAt: new Date(now).toISOString(), ...(notify ? { lastRepeatNoticeAt: new Date(now).toISOString() } : {}) });
+        (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.failure_report_folded", message: "folded a repeat failure into an open report", meta: { reportId: fresh.id, occurrences, notified: notify } });
+        return { ok: true, id: fresh.id, shortId: fresh.shortId, duplicate: true, recipients: fresh.recipients.length };
+    });
+}
+/** Records the fix a recipient says is live from `version`; the owner is told only once the running version reaches it. */
+async function resolveFailureReport(agentRoot, input, now = Date.now()) {
+    if (!readFailureReport(agentRoot, input.id))
+        return { ok: false, reason: "unknown_report" };
+    return (0, file_lock_1.withFileLock)(lockDir(agentRoot), `report-${input.id}`, () => resolveLocked(agentRoot, input, now));
+}
+function resolveLocked(agentRoot, input, now) {
+    const record = readFailureReport(agentRoot, input.id);
+    /* v8 ignore next -- only a report pruned between the check above and taking its lock can be missing here @preserve */
+    if (!record)
+        return { ok: false, reason: "unknown_report" };
+    if (!record.recipients.includes(input.byFriendId))
+        return { ok: false, reason: "not_recipient" };
+    if (record.status === "closed")
+        return { ok: false, reason: "already_closed" };
+    const version = semver.valid(input.version);
+    if (!version || version !== input.version)
+        return { ok: false, reason: "bad_version" };
+    const note = cap(input.note);
+    if (!note)
+        return { ok: false, reason: "bad_note" };
+    writeReport(agentRoot, { ...record, status: "resolved", resolution: { version, note, by: input.byFriendId, at: new Date(now).toISOString(), resolvedAt: input.resolvedAt, signedNote: input.note, proof: input.proof } });
+    (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.failure_report_resolved", message: "an escalation peer resolved a failure report", meta: { reportId: record.id, version } });
+    return { ok: true, id: record.id, status: "resolved" };
+}
+function fixLiveNoticeText(record) {
+    const resolution = record.resolution;
+    if (!record.origin.ownerOrigin) {
+        return `The fix for something I couldn't do earlier for ${record.origin.friendName ?? "a connected friend"} (report ${record.shortId}) is live now, in version ${resolution.version}. ${resolution.note}`;
+    }
+    return `The fix for what I couldn't do for you earlier (report ${record.shortId}) is live now, in version ${resolution.version}. ${resolution.note}\n\nYou asked: ${record.ariWords}`;
+}
+// Reports are rate limited and pruned, so this set stays small.
+const warnedSkips = new Set();
+/** The owner hears "fixed" only if the escalation holder signed it and still holds escalation; a file the Butler's own uid can write proves nothing. */
+async function resolutionIsSigned(agentRoot, deps, record) {
+    const resolution = record.resolution;
+    const skip = (reason) => {
+        // The confirm tick runs every few minutes, so each report warns once per process, not once per tick.
+        const key = `${record.id}:${reason}`;
+        if (warnedSkips.has(key))
+            return false;
+        warnedSkips.add(key);
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.failure_report_resolution_unverified", message: "skipped a resolved report that the holder's signature does not vouch for", meta: { reportId: record.id, by: resolution.by, reason } });
+        return false;
+    };
+    // A report that was ever closed already told the owner; a resolved status on it is a forgery or a replay.
+    if (record.closedAt !== undefined)
+        return skip("report was closed before");
+    // The owner is told exactly what was signed: the stored note must be the signed note, and the version its canonical form.
+    if (typeof resolution.signedNote !== "string" || resolution.note !== cap(resolution.signedNote))
+        return skip("note is not the signed note");
+    if (semver.valid(resolution.version) !== resolution.version)
+        return skip("version is not canonical");
+    const friend = deps.friends ? await deps.friends.get(resolution.by) : null;
+    if (!friend || !(0, escalation_grants_1.holdsEscalation)(agentRoot, friend))
+        return skip("holder no longer holds escalation");
+    // The key comes from the root-owned grant. The friend record is writable by the Butler's own uid and is never consulted for it.
+    const checked = (0, resolution_proof_1.verifyResolution)({
+        sodium: await (0, a2a_client_1.ready)(),
+        claim: { reportId: record.id, version: resolution.version, note: resolution.signedNote, resolvedAt: resolution.resolvedAt ?? "" },
+        proof: resolution.proof,
+        holderDid: (0, escalation_grants_1.pinnedHolderDid)(agentRoot, resolution.by),
+    });
+    return checked.ok;
+}
+/** Tells the owner about each resolved report whose fix has reached the running version, then closes it. */
+async function confirmResolvedReports(agentRoot, deps, now = Date.now()) {
+    const result = { closed: [], waiting: [], failed: [] };
+    for (const listed of listFailureReports(agentRoot)) {
+        if (listed.status !== "resolved" || !listed.resolution)
+            continue;
+        if (!semver.valid(deps.runningVersion) || !semver.gte(deps.runningVersion, listed.resolution.version)) {
+            result.waiting.push(listed.id);
+            continue;
+        }
+        try {
+            // The report is read again under its lock: a resolution or repeat may have landed since the listing.
+            const outcome = await (0, file_lock_1.withFileLock)(lockDir(agentRoot), `report-${listed.id}`, async () => {
+                const record = readFailureReport(agentRoot, listed.id);
+                if (!record || record.status !== "resolved" || !record.resolution)
+                    return "skipped";
+                if (!semver.gte(deps.runningVersion, record.resolution.version))
+                    return "waiting";
+                if (!(await resolutionIsSigned(agentRoot, deps, record)))
+                    return "skipped";
+                if (!record.replay)
+                    await deps.notifyOwner({ noticeId: `failure-fixed:${record.id}`, text: fixLiveNoticeText(record) });
+                writeReport(agentRoot, { ...record, status: "closed", closedAt: new Date(now).toISOString() });
+                (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.failure_report_closed", message: "closed a failure report after its fix went live", meta: { reportId: record.id, version: record.resolution.version } });
+                return "closed";
+            });
+            if (outcome === "closed")
+                result.closed.push(listed.id);
+            else if (outcome === "waiting")
+                result.waiting.push(listed.id);
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.failure_report_notice_failed", message: "could not tell the owner a fix is live; will retry", meta: { reportId: listed.id, error: error instanceof Error ? error.message : String(error) } });
+            result.failed.push(listed.id);
+        }
+    }
+    pruneClosedReports(agentRoot, now);
+    return result;
+}

package/dist/heart/file-lock.js

@@ -0,0 +1,109 @@
+"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.withFileLock = withFileLock;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const runtime_1 = require("../nerves/runtime");
+const DEFAULT_STALE_MS = 120_000;
+const DEFAULT_WAIT_MS = 45_000;
+const DEFAULT_POLL_MS = 25;
+/**
+ * Breaks a stale lock by renaming it to a name only this caller knows, then removing that. Two waiters both seeing the
+ * same stale lock cannot both break it: only one rename succeeds, and the loser never touches a lock a third process
+ * has since taken under the original name.
+ */
+function breakStaleLock(lock) {
+    const broken = `${lock}.broken-${process.pid}-${Math.random().toString(36).slice(2)}`;
+    try {
+        fs.renameSync(lock, broken);
+    }
+    catch {
+        /* v8 ignore next -- the loser of a break race finds the lock already renamed away, and simply retries @preserve */
+        return false;
+    }
+    removeLock(broken);
+    return true;
+}
+/** The lock directory is always empty, so removing it never recurses; another process may already have broken it as stale. */
+function removeLock(lock) {
+    try {
+        fs.rmdirSync(lock);
+    }
+    catch {
+        /* v8 ignore next -- a lock broken as stale by another process is already gone @preserve */
+        return;
+    }
+}
+/**
+ * Runs `fn` while holding a named lock in `dir`. The lock is a directory, because creating one is atomic across
+ * processes, which matters here: the Butler's senses (Telegram, A2A, the private runtime) are separate processes that
+ * share one bundle on disk.
+ */
+async function withFileLock(dir, name, fn, options = {}) {
+    const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+    const waitMs = options.waitMs ?? DEFAULT_WAIT_MS;
+    const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
+    fs.mkdirSync(dir, { recursive: true });
+    const lock = path.join(dir, `${name}.lock`);
+    const deadline = Date.now() + waitMs;
+    for (;;) {
+        try {
+            fs.mkdirSync(lock);
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            /* v8 ignore next -- a holder releasing between the failed mkdir and this stat reads as an old lock, which is then simply retried @preserve */
+            const heldSince = fs.statSync(lock, { throwIfNoEntry: false })?.mtimeMs ?? 0;
+            if (Date.now() - heldSince > staleMs) {
+                /* v8 ignore next -- only the waiter whose rename won reports the break @preserve */
+                if (breakStaleLock(lock))
+                    (0, runtime_1.emitNervesEvent)({ level: "warn", component: "heart", event: "heart.file_lock_broken", message: "broke a lock whose holder never released it", meta: { name, heldMs: Date.now() - heldSince } });
+                continue;
+            }
+            if (Date.now() >= deadline)
+                throw new Error(`timed out waiting for the ${name} lock`);
+            await new Promise((resolve) => setTimeout(resolve, pollMs));
+        }
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        removeLock(lock);
+    }
+}

package/dist/repertoire/guardrails.js

@@ -63,6 +63,10 @@ const PROTECTED_PATH_SEGMENTS = [
     ".ouro-cli/vault-unlock/",
     ".ouro-cli/vault-unlock-dpapi/",
     "state/policy/",
+    // What the Butler tells its escalation peers, and who may hear it: only the harness writes these, never the model.
+    "state/a2a/escalation-grants.json",
+    "state/outbox/",
+    "state/reports/",
 ];
 const PROTECTED_FILENAMES = ["agent.json", "tool-profiles.json"];
 /** The agent's psyche folder ships only from the repository (a pull request and the replay gate), so no tool writes into it. */

package/dist/repertoire/tools-awaiting.js

@@ -43,6 +43,7 @@ exports.cancelStaleAwait = cancelStaleAwait;
 exports.isBrokenBindingReason = isBrokenBindingReason;
 exports.failBrokenAwait = failBrokenAwait;
 exports.inspectRelationshipFollowUp = inspectRelationshipFollowUp;
+exports.inspectPeerAwait = inspectPeerAwait;
 exports.hasActiveRelationshipFollowUp = hasActiveRelationshipFollowUp;
 exports.hasActiveExternalEventAwait = hasActiveExternalEventAwait;
 exports.inspectExternalEventAwait = inspectExternalEventAwait;
@@ -180,6 +181,8 @@ function failedAskOwner(agentName, name, error) {
 /** At most this many ask_owner closures per requester in a rolling day, so one requester cannot make the Butler pester the owner. */
 const ASK_OWNER_DAILY_LIMIT = 3;
 const ASK_OWNER_WINDOW_MS = 24 * 60 * 60 * 1000;
+/** Across every requester who is not the owner, so many requesters together cannot flood the owner either. */
+const ASK_OWNER_NON_OWNER_DAILY_LIMIT = 6;
 function askLedgerPath(agentRoot) {
     return path.join(awaitingDir(agentRoot), ".asks.jsonl");
 }
@@ -230,7 +233,8 @@ function recentAskCount(agentRoot, filer, now) {
     return raw.split("\n").filter((line) => {
         try {
             const entry = JSON.parse(line);
-            return (entry.filer ?? null) === filer && typeof entry.at === "string" && now - Date.parse(entry.at) < ASK_OWNER_WINDOW_MS;
+            const who = filer === undefined ? entry.owner === false : (entry.filer ?? null) === filer;
+            return who && typeof entry.at === "string" && now - Date.parse(entry.at) < ASK_OWNER_WINDOW_MS;
         }
         catch {
             return false;
@@ -274,6 +278,9 @@ async function askOwnerTool(name, observation, question, choices, existing, agen
         if (!filer.isOwner && recentAskCount(agentRoot, filerId, Date.now()) >= ASK_OWNER_DAILY_LIMIT) {
             return JSON.stringify({ error: `ask_owner limit reached: this requester has already had my owner asked ${ASK_OWNER_DAILY_LIMIT} times in the last day; do not retry ask_owner, resolve with verdict 'no' with an observation and keep polling` });
         }
+        if (!filer.isOwner && recentAskCount(agentRoot, undefined, Date.now()) >= ASK_OWNER_NON_OWNER_DAILY_LIMIT) {
+            return JSON.stringify({ error: `ask_owner limit reached: my owner has already been asked ${ASK_OWNER_NON_OWNER_DAILY_LIMIT} times today on behalf of other requesters; do not retry ask_owner, resolve with verdict 'no' with an observation and keep polling` });
+        }
         const isA2A = existing.filed_from === "a2a";
         const noticeId = `await:${name}:asked_owner:${String(existing.created_at)}`;
         const question = formatOwnerQuestion(parsed.question, parsed.choices);
@@ -318,7 +325,7 @@ async function askOwnerTool(name, observation, question, choices, existing, agen
         /* v8 ignore next -- defensive: archiveAwait only fails on the file-disappears-mid-call race already covered by v8 ignore inside archiveAwait @preserve */
         if (!archive.ok)
             return JSON.stringify({ error: archive.error });
-        recordAsk(agentRoot, { filer: filerId, name, at: askedAt, question: parsed.question });
+        recordAsk(agentRoot, { filer: filerId, owner: filer.isOwner, name, at: askedAt, question: parsed.question });
         if (!tellsFriend || delivered(friendNotice))
             fulfillAwaitObligation(agentRoot, archive.file);
         (0, runtime_1.emitNervesEvent)({
@@ -643,6 +650,25 @@ function inspectRelationshipFollowUp(agentRoot, input) {
     }
     return { active: true };
 }
+/**
+ * The binding of an await filed in a plain A2A conversation: it has no request id and no obligation, only the peer's friend
+ * id and conversation key as provenance. It is live while it is still pending, was filed by that peer in that conversation,
+ * and has not outlived its max age.
+ */
+function inspectPeerAwait(agentRoot, input) {
+    const awaiting = readAwaitDefinition(agentRoot, input.awaitName);
+    if (!awaiting)
+        throw new Error(`Await ${input.awaitName} could not be verified`);
+    const matches = awaiting.status === "pending" && !awaiting.request_id && !awaiting.obligation_id
+        && awaiting.filed_for_friend_id === input.friendId && awaiting.filed_from === "a2a" && awaiting.filed_from_key === input.key;
+    if (!matches)
+        return { active: false, reason: "request obligation binding no longer matches" };
+    const maxAge = (0, cadence_1.parseCadenceToMs)(awaiting.max_age);
+    if (input.allowElapsed !== true && maxAge !== null && awaiting.created_at && (input.now ?? Date.now()) >= Date.parse(awaiting.created_at) + maxAge) {
+        return { active: false, reason: "request obligation await expired" };
+    }
+    return { active: true };
+}
 function hasActiveRelationshipFollowUp(agentRoot, input) {
     if (input.awaitName)
         return inspectRelationshipFollowUp(agentRoot, { ...input, awaitName: input.awaitName }).active;
@@ -770,6 +796,11 @@ exports.awaitingToolDefinitions = [
                 if (session?.channel === "external-event" && existing?.wake_at) {
                     binding = inspectExternalEventAwait(agentName, { recordPath: session.key, awaitName, wakeAt: existing.wake_at });
                 }
+                else if (session?.channel === "a2a" && ctx.awaitTick && !requestId && existing && !existing.request_id
+                    && existing.filed_for_friend_id === session.friendId && existing.filed_from === "a2a" && existing.filed_from_key === session.key) {
+                    // A plain peer await is resolved only by its own tick, never from a chat turn.
+                    binding = inspectPeerAwait(agentRoot, { friendId: session.friendId, key: session.key, awaitName });
+                }
                 else if (session && requestId) {
                     if (existing?.filed_for_friend_id !== session.friendId || existing.filed_from !== session.channel
                         || existing.filed_from_key !== session.key || existing.request_id !== requestId) {

package/dist/repertoire/tools-base.js

@@ -24,6 +24,7 @@ const tools_trip_1 = require("./tools-trip");
 const tools_a2a_1 = require("./tools-a2a");
 const tools_commerce_1 = require("./tools-commerce");
 const tools_awaiting_1 = require("./tools-awaiting");
+const tools_escalation_1 = require("./tools-escalation");
 const tools_obligations_1 = require("./tools-obligations");
 const tools_evolution_1 = require("./tools-evolution");
 const tools_runtime_1 = require("./tools-runtime");
@@ -75,6 +76,7 @@ exports.baseToolDefinitions = [
     ...tools_a2a_1.a2aToolDefinitions,
     ...tools_commerce_1.commerceToolDefinitions,
     ...tools_awaiting_1.awaitingToolDefinitions,
+    tools_escalation_1.reportFailureToolDefinition,
     ...tools_obligations_1.obligationToolDefinitions,
     ...tools_evolution_1.evolutionToolDefinitions,
     ...tools_orientation_1.orientationToolDefinitions,

package/dist/repertoire/tools-escalation.js

@@ -0,0 +1,84 @@
+"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.reportFailureToolDefinition = void 0;
+const path = __importStar(require("path"));
+const friends_1 = require("@ouro.bot/friends");
+const failure_reports_1 = require("../heart/failure-reports");
+const runtime_1 = require("../nerves/runtime");
+function text(value) {
+    return typeof value === "string" ? value : "";
+}
+/**
+ * Lets the agent hand a failure it cannot work around to the peers who fix it. The session comes from the runtime
+ * context, never from the model, so a report cannot be addressed to or attributed to anyone else.
+ */
+exports.reportFailureToolDefinition = {
+    tool: {
+        type: "function",
+        function: {
+            name: "report_failure",
+            description: "File a failure report for the engineers who fix you. Use it when a tool you need is missing, a tool errors in a way you cannot work around, or you are about to give up on what the owner asked. Then tell the owner you have filed it, with the short report id, in your own words. Do not ask the owner to do anything about it.",
+            parameters: {
+                type: "object",
+                properties: {
+                    ari_words: { type: "string", description: "What the owner asked for, verbatim from the conversation." },
+                    tried: { type: "string", description: "What you tried: tool names and arguments, summarized." },
+                    error: { type: "string", description: "The tool error, or the reason you gave up." },
+                    failed_tool: { type: "string", description: "The tool that failed or that you wished existed, if there is one." },
+                    severity: { type: "string", enum: ["low", "medium", "high"], description: "How much this blocks the owner." },
+                },
+                required: ["ari_words", "tried", "error"],
+                additionalProperties: false,
+            },
+        },
+    },
+    handler: async (args, ctx) => {
+        if (!ctx?.agentRoot)
+            return "report_failure is unavailable: no agent runtime.";
+        const severity = ["low", "medium", "high"].includes(args.severity) ? args.severity : "medium";
+        const store = new friends_1.FileFriendStore(path.join(ctx.agentRoot, "friends"));
+        const result = await (0, failure_reports_1.fileFailureReport)(ctx.agentRoot, store, {
+            ariWords: text(args.ari_words), tried: text(args.tried), error: text(args.error),
+            ...(text(args.failed_tool) ? { failedTool: text(args.failed_tool) } : {}),
+            severity,
+            origin: { friendId: ctx.currentSession?.friendId ?? null, channel: ctx.currentSession?.channel ?? null, key: ctx.currentSession?.key ?? null },
+        });
+        (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.report_failure", message: "failure report requested", meta: { ok: result.ok, ...(result.ok ? { duplicate: result.duplicate } : { reason: result.reason }) } });
+        if (!result.ok)
+            return `Not filed (${result.reason}): ${result.detail}`;
+        return JSON.stringify({ filed: true, reportId: result.id, shortId: result.shortId, duplicate: result.duplicate, recipients: result.recipients });
+    },
+};

package/dist/repertoire/tools.js

@@ -56,6 +56,7 @@ const SANCTUARY_RELATIONSHIP_BASE_TOOLS = new Set([
     "query_cares",
     "care_manage",
     "await_condition",
+    "report_failure",
     "resolve_await",
     "cancel_await",
     "list_recent_attachments",