@ouro.bot/cli 0.1.0-alpha.99 → 0.1.0-alpha.991

package/dist/a2a/replay-harness.js

@@ -0,0 +1,188 @@
+"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.REPLAY_WINDOW_MAX_MS = void 0;
+exports.replayWindowPath = replayWindowPath;
+exports.replaySinkPath = replaySinkPath;
+exports.replayIdentitiesPath = replayIdentitiesPath;
+exports.isReplayIdentity = isReplayIdentity;
+exports.isReplayWindowOpen = isReplayWindowOpen;
+exports.isAnyReplayWindowOpen = isAnyReplayWindowOpen;
+exports.appendReplayNotice = appendReplayNotice;
+exports.replayNoticeRecorded = replayNoticeRecorded;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("path"));
+const runtime_1 = require("../nerves/runtime");
+/**
+ * The replay gate drives the Butler over its real A2A path to check its behaviour after an upgrade. Every delegated
+ * command and every A2A-filed await would otherwise post to the owner's Telegram chat. While the host's gate holds a
+ * replay window open for a peer, those notices are appended to a local sink instead.
+ *
+ * The window narrows where a notice goes, never whether a command is authorized: the grant, family trust, sole owner
+ * and notify-before-run checks are unchanged, and "notify" means "the sink write succeeded". The window file lives
+ * under the bundle's state directory, is written by the host's gate and cleared when its run ends, and every entry
+ * expires on its own (and is ignored if it claims to last longer than the cap).
+ */
+exports.REPLAY_WINDOW_MAX_MS = 2 * 60 * 60 * 1000;
+function replayDir(agentRoot) {
+    return path.join(agentRoot, "state", "replay");
+}
+function replayWindowPath(agentRoot) {
+    return path.join(replayDir(agentRoot), "window.json");
+}
+function replaySinkPath(agentRoot) {
+    return path.join(replayDir(agentRoot), "notices.ndjson");
+}
+/** Permanent registry of replay identities, written by the host's provisioning and never cleared. */
+function replayIdentitiesPath(agentRoot) {
+    return path.join(replayDir(agentRoot), "identities.json");
+}
+function listsFriend(file, friendId) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        // A missing file lists nobody; a file that exists but cannot be read or parsed fails closed.
+        return error.code !== "ENOENT";
+    }
+    const friends = parsed?.friends;
+    return !!friends && typeof friends === "object" && Object.hasOwn(friends, friendId);
+}
+/**
+ * True when `friendId` is a replay identity: listed in the permanent registry, or holding any window entry (open or
+ * expired). Unlike the window check this needs no trusted-owner proof, because the marker only ever restricts: forging
+ * an entry can block a friend from writing owner policy, never grant anything. Owner policy writes refuse these identities.
+ */
+function isReplayIdentity(agentRoot, friendId) {
+    return listsFriend(replayIdentitiesPath(agentRoot), friendId) || listsFriend(replayWindowPath(agentRoot), friendId);
+}
+/** A root-controlled directory: a real directory (no symlink), owned by the trusted uid, writable by neither group nor other. */
+function isTrustedDirectory(target, trustedUid) {
+    try {
+        const stat = fs.lstatSync(target);
+        return stat.isDirectory() && !stat.isSymbolicLink() && stat.uid === trustedUid && (stat.mode & 0o022) === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Reads the window file only if the file actually opened is trusted. The path is opened once with O_NOFOLLOW, then the
+ * descriptor itself is checked (regular file, trusted owner, not group- or other-writable) and read, so a rename loop on
+ * the Butler's own state directory cannot swap a different file in between the check and the read. Any error is "no window".
+ */
+function readTrustedWindow(file, trustedUid) {
+    let fd;
+    try {
+        fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile() || stat.uid !== trustedUid || (stat.mode & 0o022) !== 0)
+            return undefined;
+        return JSON.parse(fs.readFileSync(fd, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+/**
+ * True only when the window file lists `friendId` with an expiry that is in the future and within the cap. Any unreadable or malformed file means "closed".
+ * The state directory is the Butler's own, so it could swap in a directory and window of its own making: only a replay
+ * directory and window file that root owns, and nobody else can write, count; anything else fails toward Telegram.
+ */
+const windowEntryOpen = (entry, now) => {
+    const expiresAt = typeof entry?.expiresAt === "string"
+        ? Date.parse(entry.expiresAt)
+        : Number.NaN;
+    return Number.isFinite(expiresAt) && expiresAt > now && expiresAt <= now + exports.REPLAY_WINDOW_MAX_MS;
+};
+function isReplayWindowOpen(agentRoot, friendId, now = Date.now(), trustedUid = 0) {
+    if (!isTrustedDirectory(replayDir(agentRoot), trustedUid))
+        return false;
+    const parsed = readTrustedWindow(replayWindowPath(agentRoot), trustedUid);
+    const friends = parsed?.friends;
+    if (!friends || typeof friends !== "object")
+        return false;
+    return windowEntryOpen(friends[friendId], now);
+}
+/** True while any friend's replay window is open: the gate is running, and background work should stay out of its way. Same trust rules as `isReplayWindowOpen`. */
+function isAnyReplayWindowOpen(agentRoot, now = Date.now(), trustedUid = 0) {
+    if (!isTrustedDirectory(replayDir(agentRoot), trustedUid))
+        return false;
+    const parsed = readTrustedWindow(replayWindowPath(agentRoot), trustedUid);
+    const friends = parsed?.friends;
+    if (!friends || typeof friends !== "object")
+        return false;
+    return Object.values(friends).some((entry) => windowEntryOpen(entry, now));
+}
+/** Appends one notice to the sink, once per notice id and friend (a retry after a crash adds nothing); throws when it cannot be written, so the caller refuses exactly as a failed Telegram send does. */
+function appendReplayNotice(agentRoot, notice, now = Date.now()) {
+    if (replayNoticeRecorded(agentRoot, notice.noticeId, notice.friendId))
+        return;
+    fs.mkdirSync(replayDir(agentRoot), { recursive: true });
+    const line = JSON.stringify({ at: new Date(now).toISOString(), ...notice });
+    fs.appendFileSync(replaySinkPath(agentRoot), `${line}\n`, { mode: 0o600 });
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.a2a_replay_notice_sunk",
+        message: "wrote an owner notice to the replay sink instead of Telegram",
+        meta: { noticeId: notice.noticeId, friendId: notice.friendId },
+    });
+}
+/** True when the sink holds a notice with this id for this friend (a missing sink is "no"). The sink is Butler-writable: callers must also require a trusted window. */
+function replayNoticeRecorded(agentRoot, noticeId, friendId) {
+    let raw;
+    try {
+        raw = fs.readFileSync(replaySinkPath(agentRoot), "utf8");
+    }
+    catch {
+        return false;
+    }
+    return raw.split("\n").some((line) => {
+        if (!line)
+            return false;
+        try {
+            const entry = JSON.parse(line);
+            return entry.noticeId === noticeId && entry.friendId === friendId;
+        }
+        catch {
+            return false;
+        }
+    });
+}

package/dist/a2a/resolution-proof.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signResolution = signResolution;
+exports.friendDid = friendDid;
+exports.verifyResolution = verifyResolution;
+const a2a_client_1 = require("@ouro.bot/friends/a2a-client");
+const friends_1 = require("@ouro.bot/friends");
+const runtime_1 = require("../nerves/runtime");
+/**
+ * The proof that an escalation holder, and nobody who can write the Butler's files, said a failure report is fixed.
+ * The holder signs `{reportId, version, note, resolvedAt}` with its DID key (canonical JSON, detached Ed25519), and
+ * the Butler keeps the signature next to the resolution. The holder's private key never leaves the holder's machine,
+ * so a forged report file cannot carry a valid one.
+ */
+const PURPOSE = "ouro.report-resolve.v1";
+function envelopeOf(claim) {
+    return { purpose: PURPOSE, reportId: claim.reportId, version: claim.version, note: claim.note, resolvedAt: claim.resolvedAt };
+}
+function signResolution(input) {
+    const { claim } = input;
+    return (0, a2a_client_1.signEnvelope)({
+        sodium: input.sodium,
+        envelope: envelopeOf(claim),
+        signerEd25519Priv: input.identity.ed25519Priv,
+        signerDid: input.identity.did,
+        signerKeyId: input.identity.keyId,
+    });
+}
+/** The DID a friend record names. Used only by the operator command that pins it into the grant; never to verify a resolution. */
+function friendDid(friend) {
+    return (0, friends_1.resolveAgentIdentity)(friend.agentMeta).did ?? null;
+}
+function verifyResolution(input) {
+    const fail = (reason) => {
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.a2a_resolution_proof_rejected", message: "rejected a report resolution without a valid holder signature", meta: { reportId: input.claim.reportId, reason } });
+        return { ok: false, reason };
+    };
+    const proof = input.proof;
+    if (!proof || typeof proof !== "object" || Array.isArray(proof))
+        return fail("no_proof");
+    if (!input.holderDid)
+        return fail("no_holder_did");
+    const parsed = (0, a2a_client_1.parseDidKey)(input.holderDid);
+    if (!parsed || proof.signerDid !== input.holderDid)
+        return fail("wrong_signer");
+    const valid = (0, a2a_client_1.verifyEnvelopeSignature)({
+        sodium: input.sodium,
+        envelope: envelopeOf(input.claim),
+        proof: proof,
+        signerEd25519Pub: parsed.ed25519Pub,
+    });
+    return valid ? { ok: true } : fail("bad_signature");
+}

package/dist/a2a/sealed-chat.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMPTY_CHAT_REPLY = void 0;
+exports.sealChatMessage = sealChatMessage;
+exports.openChatMessage = openChatMessage;
+/**
+ * Sealed agent-to-agent chat over A2A (friends `message` kind).
+ *
+ * Both directions use the same primitive: the text is signed by the sender and
+ * sealed to the recipient inside ONE friends DataPart, so a message is confidential
+ * and tamper-evident over any transport (tailnet, LAN, relay). The network is a
+ * pipe, not the lock.
+ *
+ * - `sealChatMessage` builds the single-DataPart A2A message for a recipient whose
+ *   Ed25519 key the sender already trusts (a pinned DID, or a did:key card).
+ * - `openChatMessage` opens one through the SAME `receiveShare` pipeline every
+ *   friends kind uses (unseal, sender binding, pinned-key signature, replay guard,
+ *   trust floor), pinned to the sender the opener expects. There is no second,
+ *   hand-rolled verification path.
+ */
+const a2a_client_1 = require("@ouro.bot/friends/a2a-client");
+const friends_1 = require("@ouro.bot/friends");
+const runtime_1 = require("../nerves/runtime");
+/** What an agent replies when its turn produced no text; sealed like any reply. */
+exports.EMPTY_CHAT_REPLY = "(no reply)";
+/** Seal `text` from `from` to the recipient as a single friends DataPart. Returns
+ * the harness-shaped A2A message; callers add role/messageId/contextId. */
+function sealChatMessage(input) {
+    const text = input.text.trim() === "" ? exports.EMPTY_CHAT_REPLY : input.text.slice(0, friends_1.MAX_MESSAGE_TEXT_CHARS);
+    const prepared = (0, friends_1.prepareMessage)({
+        fromAgentId: input.from.did,
+        text,
+        ...(input.conversationId !== undefined ? { conversationId: input.conversationId } : {}),
+        ...(input.onBehalfOf ? { onBehalfOf: input.onBehalfOf } : {}),
+    });
+    /* v8 ignore next -- the text is normalized above and the sender DID comes from a real identity @preserve */
+    if (!prepared.ok)
+        throw new Error(`cannot prepare chat message: ${prepared.status}`);
+    const sealed = (0, a2a_client_1.sealEnvelope)({
+        sodium: input.sodium,
+        envelope: prepared.envelope,
+        friendsKind: "message",
+        fromIdentity: input.from,
+        recipientDid: input.recipientDid,
+        recipientX25519Pub: (0, a2a_client_1.keyAgreementFromDidKey)({ sodium: input.sodium, ed25519Pub: input.recipientEd25519Pub }),
+    });
+    const wrapped = (0, a2a_client_1.wrapInDataPart)({ sealedEnvelope: sealed, recipientDid: input.recipientDid });
+    (0, runtime_1.emitNervesEvent)({
+        component: "channels",
+        event: "channel.a2a_chat_sealed",
+        message: "sealed an A2A chat message",
+        meta: { recipientDid: input.recipientDid, chars: text.length },
+    });
+    return { parts: wrapped.parts };
+}
+class MemorySeenLedger {
+    seen = new Set();
+    isSeen(nonce) { return this.seen.has(nonce); }
+    markSeen(nonce) { this.seen.add(nonce); }
+}
+/** A `message` receipt imports nothing, so the stores must never be reached. */
+function unreachableStore(name) {
+    return new Proxy({}, { get() { throw new Error(`sealed chat must not touch the ${name}`); } });
+}
+/** Open a sealed chat message from an expected sender through `receiveShare`. */
+async function openChatMessage(input) {
+    const pinStore = new a2a_client_1.MemoryPinStore();
+    (0, a2a_client_1.pinOnFirstContact)({ pinStore, fromAgentId: input.senderDid, did: input.senderDid, ed25519Pub: input.senderEd25519Pub });
+    const result = await (0, a2a_client_1.receiveShare)({
+        sodium: input.sodium,
+        store: unreachableStore("friend store"),
+        missionStore: unreachableStore("mission store"),
+        pinStore,
+        // Only the pre-pinned sender can verify: any other signer resolves to nothing.
+        didResolution: {
+            async resolveAndPin({ fromAgentId }) {
+                const pinned = pinStore.get(fromAgentId);
+                return pinned ? { ed25519Pub: pinned.ed25519Pub } : null;
+            },
+        },
+        seen: input.seen ?? new MemorySeenLedger(),
+        a2aMessage: input.message,
+        recipientDid: input.self.did,
+        recipientIdentity: { x25519Priv: input.self.x25519Priv, x25519Pub: input.self.x25519Pub },
+        // The opener chose this sender; the signature, not this level, is the gate.
+        trustOfSource: "family",
+        options: { rejectUnboundEnvelopes: true, ...(input.now !== undefined ? { now: input.now } : {}) },
+    });
+    if (result.state === "rejected") {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "channels",
+            event: "channel.a2a_chat_open_rejected",
+            message: "refused a sealed A2A chat message",
+            meta: { senderDid: input.senderDid, reason: result.reason },
+        });
+        return { ok: false, reason: result.reason };
+    }
+    /* v8 ignore next -- any other kind reaches a store, and these stores throw: only a message can complete here @preserve */
+    if (result.friendsKind !== "message" || !result.message)
+        return { ok: false, reason: "not_a_message" };
+    (0, runtime_1.emitNervesEvent)({
+        component: "channels",
+        event: "channel.a2a_chat_opened",
+        message: "opened a verified A2A chat message",
+        meta: { senderDid: input.senderDid, chars: result.message.text.length },
+    });
+    return {
+        ok: true,
+        text: result.message.text,
+        ...(result.message.conversationId !== undefined ? { conversationId: result.message.conversationId } : {}),
+        issuedAt: result.message.issuedAt,
+    };
+}

package/dist/a2a/seen-ledger.js

@@ -0,0 +1,214 @@
+"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.FileA2ASeenLedger = exports.SEEN_PRUNE_INTERVAL_MS = exports.SEEN_RETENTION_MS = exports.MAX_FUTURE_SKEW_MS = exports.MAX_ENVELOPE_AGE_MS = void 0;
+exports.bindingWindowsWithinRetention = bindingWindowsWithinRetention;
+exports.openPrivateSeenLedger = openPrivateSeenLedger;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const runtime_1 = require("../nerves/runtime");
+/**
+ * How long friends accepts an envelope after its `issuedAt`: 7 days (`DEFAULT_MAX_AGE_MS` in friends
+ * `envelope-binding`, which its public exports do not include). A sealed message older than this is refused anyway.
+ */
+exports.MAX_ENVELOPE_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+exports.MAX_FUTURE_SKEW_MS = 2 * 60 * 1000;
+exports.SEEN_RETENTION_MS = exports.MAX_ENVELOPE_AGE_MS + exports.MAX_FUTURE_SKEW_MS;
+/** While the agent runs, expired entries are dropped when a new one is marked, at most this often. */
+exports.SEEN_PRUNE_INTERVAL_MS = 60 * 60 * 1000;
+/**
+ * Keep configured age windows inside what the seen ledger remembers. An envelope accepted later than the ledger keeps
+ * its entry could be replayed, so any age window above 7 days, or a future skew above 2 minutes, is clamped to that
+ * limit with a warning.
+ */
+function bindingWindowsWithinRetention(options) {
+    const clamped = { ...options };
+    const changed = [];
+    for (const [field, limit] of [["maxAgeMs", exports.MAX_ENVELOPE_AGE_MS], ["delegatedMaxAgeMs", exports.MAX_ENVELOPE_AGE_MS], ["maxFutureSkewMs", exports.MAX_FUTURE_SKEW_MS]]) {
+        const value = clamped[field];
+        if (value !== undefined && value > limit) {
+            clamped[field] = limit;
+            changed.push(field);
+        }
+    }
+    if (changed.length > 0) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "channels",
+            event: "channel.a2a_binding_window_clamped",
+            message: "A2A message age limits were set longer than the replay ledger keeps entries (7 days, plus 2 minutes of clock skew), so they were shortened to those limits",
+            meta: { fields: changed },
+        });
+    }
+    return clamped;
+}
+function nonceFileName(nonce) {
+    return `${(0, node_crypto_1.createHash)("sha256").update(nonce).digest("hex")}.json`;
+}
+class FileA2ASeenLedger {
+    dir;
+    /** Each seen key with when it was marked (NaN: undated, kept) and the file that holds it. */
+    cache = new Map();
+    now;
+    lastPrunedAt;
+    constructor(agentRoot, options = {}) {
+        this.dir = path.join(agentRoot, "state", "a2a", "seen");
+        this.now = options.now ?? Date.now;
+        fs.mkdirSync(this.dir, { recursive: true });
+        this.lastPrunedAt = this.now();
+        this.loadExisting();
+        this.prune(this.lastPrunedAt);
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_seen_ledger_init",
+            message: "initialized durable A2A seen ledger",
+            meta: { dir: this.dir, seen: this.cache.size },
+        });
+    }
+    get size() {
+        return this.cache.size;
+    }
+    isSeen(nonce) {
+        if (!nonce)
+            return false;
+        const seen = this.cache.has(nonce);
+        if (seen) {
+            // A nonce we already processed is arriving again — for a seal nonce this is
+            // a replay. Loud security signal.
+            (0, runtime_1.emitNervesEvent)({
+                component: "channels",
+                event: "channel.a2a_replay_rejected",
+                message: "A2A replay rejected (nonce already seen)",
+                meta: { nonceHash: nonceFileName(nonce).slice(0, 16) },
+            });
+        }
+        return seen;
+    }
+    /** Whether a nonce was already processed, without the replay security event `isSeen` raises. The relay inbox uses
+     * it after a failed turn to learn whether friends verified the message before the turn threw. */
+    has(nonce) {
+        return !!nonce && this.cache.has(nonce);
+    }
+    markSeen(nonce) {
+        // An empty-string nonce is never a matchable key — stay inert.
+        if (!nonce)
+            return;
+        if (this.cache.has(nonce))
+            return;
+        const now = this.now();
+        const file = path.join(this.dir, nonceFileName(nonce));
+        fs.writeFileSync(file, `${JSON.stringify({ nonce, markedAt: new Date(now).toISOString() }, null, 2)}\n`, "utf-8");
+        this.cache.set(nonce, { markedAt: now, file });
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_seen_marked",
+            message: "marked A2A seal nonce as seen (first sight)",
+            meta: { nonceHash: nonceFileName(nonce).slice(0, 16) },
+        });
+        // A long-running agent drops expired entries as it goes, not only when it starts.
+        if (now - this.lastPrunedAt >= exports.SEEN_PRUNE_INTERVAL_MS) {
+            this.lastPrunedAt = now;
+            this.prune(now);
+        }
+    }
+    /** Drop entries marked longer ago than `SEEN_RETENTION_MS`: they can never match an acceptable envelope again. An
+     * undated entry is kept. */
+    prune(now) {
+        let pruned = 0;
+        for (const [nonce, entry] of this.cache) {
+            if (!(now - entry.markedAt > exports.SEEN_RETENTION_MS))
+                continue;
+            /* v8 ignore start -- a file that vanished or cannot be removed is simply left; the next prune drops it from disk at restart @preserve */
+            try {
+                fs.unlinkSync(entry.file);
+            }
+            catch {
+                // left on disk; it is expired, so dropping it from memory is still safe
+            }
+            /* v8 ignore stop @preserve */
+            this.cache.delete(nonce);
+            pruned += 1;
+        }
+        if (pruned > 0) {
+            (0, runtime_1.emitNervesEvent)({ component: "channels", event: "channel.a2a_seen_pruned", message: "pruned A2A seen entries past the freshness window", meta: { dir: this.dir, pruned } });
+        }
+    }
+    /** Reload every persisted nonce from disk into the in-memory set (the restart
+     * replay defense). Corrupt/unreadable artifacts are skipped so one bad file can
+     * never reopen the replay window for the rest. */
+    loadExisting() {
+        let entries;
+        try {
+            entries = fs.readdirSync(this.dir);
+        }
+        catch {
+            /* v8 ignore next -- the constructor mkdirSync's the dir before this runs; unreadable dir is unreachable in practice @preserve */
+            return;
+        }
+        for (const name of entries) {
+            if (!name.endsWith(".json"))
+                continue;
+            const file = path.join(this.dir, name);
+            let record;
+            try {
+                record = JSON.parse(fs.readFileSync(file, "utf-8"));
+            }
+            catch {
+                continue;
+            }
+            if (typeof record.nonce === "string" && record.nonce.length > 0) {
+                const markedAt = typeof record.markedAt === "string" ? Date.parse(record.markedAt) : Number.NaN;
+                this.cache.set(record.nonce, { markedAt, file });
+            }
+        }
+    }
+}
+exports.FileA2ASeenLedger = FileA2ASeenLedger;
+/**
+ * A seen ledger under `root` that only this user can reach (the CLI keeps one for replies). `root` is created 0700 and
+ * refused when it is a symlink, not a folder, owned by someone else, or open to group or other, since anyone who can
+ * delete entries can replay an old reply.
+ */
+function openPrivateSeenLedger(root) {
+    fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+    const stat = fs.lstatSync(root);
+    /* v8 ignore next -- process.getuid exists on every POSIX platform the CLI runs on @preserve */
+    const uid = typeof process.getuid === "function" ? process.getuid() : stat.uid;
+    if (!stat.isDirectory() || stat.uid !== uid || (stat.mode & 0o077) !== 0) {
+        throw new Error(`refusing the A2A reply ledger at ${root}: it must be a folder owned by you with mode 0700`);
+    }
+    return new FileA2ASeenLedger(root);
+}