@ouro.bot/cli 0.1.0-alpha.987 → 0.1.0-alpha.989

package/changelog.json

@@ -1,6 +1,22 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.989",
+      "changes": [
+        "Agents now use friends 0.1.0-alpha.17. Every signed message is bound to its recipient, kind, a message id and its time, and a message without that binding is refused, so an old message cannot be replayed or resealed to another agent. A message counts as received only once its signature checks out, so a delivery that fails before that can be sent again.",
+        "Mission results get the same binding and replay checks as other messages, keyed on the whole sealed message rather than its nonce. A delegated command's id comes from the sender's DID, its signed message id and its signed time, and the refusal a sender gets for a rejected message now says what happened and what to do next.",
+        "Compatibility: an agent on this release refuses messages from agents whose harness uses friends 0.1.0-alpha.14 or older (they are unbound), and `ouro a2a` refuses their replies, saying the call may already have run. Upgrade every agent that talks to this one.",
+        "Key rotation follows friends' signed successor statement: the old key and the new key both sign it, and an accepted rotation moves the peer's friend record (with its trust) and its pins to the new DID before the message is judged, so the first message from the new DID is accepted. Delegated-command grants do not move: the operator grants again for the new DID. The old DID is kept as a retired pin that verifies nothing. If the record cannot move (another record already holds the new DID), the agent refuses the peer's messages, retries the move on each one, and sends the owner one notice with the command that fixes it. The friends wire has no carrier for successor statements yet, so a DID seen for the first time is still a first contact.",
+        "The seen-message ledger drops entries older than the 7-day freshness window when the agent starts and, while it runs, at most once an hour as new entries arrive. Message age limits can never be set longer than the ledger keeps entries. The CLI checks replies against a durable ledger, and `ouro friend link` says when a link was refused instead of reporting it as linked."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.988",
+      "changes": [
+        "The work-protocol contract test gives the same result on every machine: it no longer compares against a sibling ouro-work-substrate clone when one happens to exist."
+      ]
+    },
     {
       "version": "0.1.0-alpha.987",
       "changes": [

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

@@ -1,5 +1,5 @@
 {
-  "runtimeVersion": "0.1.0-alpha.987",
+  "runtimeVersion": "0.1.0-alpha.989",
   "bundleSchemaVersion": 3,
   "lastUpdated": "2026-09-03T00:00:00.000Z"
 }

package/deploy/unraid/sanctuary.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <Container version="2">
   <Name>ouro-butler</Name>
-  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.987</Repository>
+  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.989</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

package/dist/a2a/client.js

@@ -4,6 +4,7 @@ exports.A2ARpcError = void 0;
 exports.cardDid = cardDid;
 exports.endpointForCard = endpointForCard;
 exports.fetchA2AAgentCard = fetchA2AAgentCard;
+exports.replyRefusedError = replyRefusedError;
 exports.postJsonRpc = postJsonRpc;
 exports.sendA2AMessage = sendA2AMessage;
 exports.postA2AMessageEnvelope = postA2AMessageEnvelope;
@@ -51,6 +52,13 @@ async function fetchA2AAgentCard(cardUrl, fetchImpl = fetch) {
     });
     return parsed;
 }
+/**
+ * The error for a reply this side refused to open. The request was already delivered, so the peer may have acted on it
+ * (an older peer replies unbound, which is refused): say so, so the caller does not resend a command and run it twice.
+ */
+function replyRefusedError(what, reason) {
+    return new Error(`A2A ${what} reply rejected: ${reason}; the call may already have run on the peer`);
+}
 /** A JSON-RPC error answer from the peer. `data` carries the peer's structured detail (for a refused delegated command: reason, nothingRan, retry, next). */
 class A2ARpcError extends Error {
     code;
@@ -242,9 +250,9 @@ async function sendSealedA2AChat(input) {
     const replyMessage = task?.status?.message;
     if (!replyMessage)
         throw new Error("A2A chat returned no reply message");
-    const opened = await (0, sealed_chat_1.openChatMessage)({ sodium, self: input.identity, message: replyMessage, senderDid: peerDid, senderEd25519Pub: parsed.ed25519Pub });
+    const opened = await (0, sealed_chat_1.openChatMessage)({ sodium, self: input.identity, message: replyMessage, senderDid: peerDid, senderEd25519Pub: parsed.ed25519Pub, ...(input.seen ? { seen: input.seen } : {}) });
     if (!opened.ok)
-        throw new Error(`A2A chat reply rejected: ${opened.reason}`);
+        throw replyRefusedError("chat", opened.reason);
     (0, runtime_1.emitNervesEvent)({ component: "channels", event: "channel.a2a_chat_send_end", message: "received sealed A2A chat reply", meta: { endpointUrl, peerDid, taskId: task.id } });
     return { text: opened.text, conversationId, taskId: task.id, peerDid, peerName: card.name };
 }

package/dist/a2a/did-resolution.js

@@ -2,49 +2,193 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.makeDidResolution = makeDidResolution;
 const a2a_client_1 = require("@ouro.bot/friends/a2a-client");
+const node_crypto_1 = require("node:crypto");
 const runtime_1 = require("../nerves/runtime");
+/** Why a record could not move, in words an owner can read. A reason a later friends adds fails the type check. */
+const MOVE_FAILURE_WORDS = {
+    rotation_not_accepted: "this agent's saved keys do not show the change cleanly",
+    rotation_chain_invalid: "its chain of key changes loops or is too long",
+    record_not_found: "its friend record was not found under any of its earlier keys",
+    successor_already_linked: "another friend record already holds the new key",
+};
+/** At most this many earlier DIDs are followed back from a rotated pin (friends' `MAX_ROTATION_HOPS`). */
+const MAX_PREDECESSOR_HOPS = 16;
+function refused(fromAgentId, reason, message) {
+    (0, runtime_1.emitNervesEvent)({ component: "channels", event: "channel.a2a_did_resolve_refused", message, meta: { fromAgentId, reason } });
+    return null;
+}
 /**
- * Build the friends `DidResolution` for did:key peers. `resolveAndPin` is the
- * verify-and-pin core the inbound bridge consumes:
- *   parse the did:key → derive the presented Ed25519 key →
- *     first contact (no pin under `fromAgentId`) → TOFU `pinOnFirstContact`
- *     already pinned → `evaluateRotation` against the pin:
- *       unchanged  → pin-hit, return the pinned key
- *       accepted   → (re-pinned by evaluateRotation) return the NEW key
- *       rejected   → loud security event, return null
- *
- * The pin is keyed by the STABLE `fromAgentId` (NOT the did:key string), so a
- * rotation is "same `fromAgentId`, new (did, key)". An unparseable or empty DID is
- * refused (null) and never matchable. The crypto is the friends primitives' — this
- * only sequences them.
+ * Build the friends `DidResolution` for did:key peers. `resolveAndPin` is the verify-and-pin core the inbound bridge
+ * consumes. friends calls it with the SIGNED sender DID as both `fromAgentId` and `did`, so pins are keyed by DID:
+ *   unparseable or empty DID, or a retired pin  → refused (null)
+ *   pinned                                       → the pinned key (a did:key's key cannot change under the same DID)
+ *   not pinned, with a successor statement       → `evaluateRotation` from the old DID (at the OLD record's trust);
+ *                                                  accepted: `applyAcceptedRotation` moves the record, then the new key
+ *                                                  rejected: refused, never a silent first contact
+ *   not pinned, no statement                     → first contact (TOFU `pinOnFirstContact`)
+ * The receive paths call `settleSender` first, so by the time `resolveAndPin` runs a rotation is already applied.
  */
 function makeDidResolution(input) {
-    const { sodium, rotationProofFor } = input;
+    const { sodium, store, successorFor } = input;
+    const toldOwner = new Set();
+    /** Tell the owner, once per rotation, that the record could not follow and how to fix it. */
+    function tellOwner(oldDid, newDid, record, holder, reason) {
+        const notify = input.notifyOwner;
+        const key = `${oldDid}>${newDid}`;
+        if (!notify || toldOwner.has(key))
+            return;
+        toldOwner.add(key);
+        const agent = input.agentName ?? "<agent>";
+        const [cause, command] = holder
+            ? [
+                `Its new key is already linked to another friend record, ${holder.name} (${holder.id}). If that is the same peer, merge the two records`,
+                `ouro friend merge --agent ${agent} --into ${record.id} ${holder.id} --apply`,
+            ]
+            : [
+                `The record could not move because ${MOVE_FAILURE_WORDS[reason]}. Link the record to the new key`,
+                `ouro friend link ${agent} --friend ${record.id} --provider a2a-agent --external-id ${newDid}`,
+            ];
+        // The command sits on its own line with nothing after it, so it can be copied as is.
+        const notice = {
+            noticeId: `a2a-rotation-unmoved:${(0, node_crypto_1.createHash)("sha256").update(key).digest("hex").slice(0, 32)}`,
+            text: [
+                `${record.name} changed its A2A key to ${newDid}, but its friend record could not move to the new key, so this agent refuses its messages until this is fixed.`,
+                `${cause}. Run:`,
+                command,
+                `${record.name}'s next message then moves the record.`,
+            ].join("\n\n"),
+        };
+        notify(notice).catch((error) => {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "channels",
+                event: "channel.a2a_rotation_notice_failed",
+                message: "could not tell the owner that a rotated peer's record did not move",
+                meta: { oldDid, newDid, error: error instanceof Error ? error.message : String(error) },
+            });
+        });
+    }
+    /** Move the peer's record along the rotation chain to `newDid`. On failure, warn and tell the owner. */
+    async function moveRecord(friends, pinStore, oldDid, newDid, record) {
+        const moved = await (0, a2a_client_1.applyAcceptedRotation)({ store: friends, pinStore, oldDid, newDid });
+        if (moved.ok)
+            return true;
+        // The pins moved but the friend record did not follow (another record already holds the new DID, or the chain is
+        // broken). Refuse rather than run the message under a record that does not carry the old trust.
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "channels",
+            event: "channel.a2a_rotation_record_not_moved",
+            message: "A2A key rotation verified but the friend record could not follow; refusing the message",
+            meta: { oldDid, newDid, reason: moved.reason },
+        });
+        tellOwner(oldDid, newDid, record, await friends.findByExternalId("a2a-agent", newDid), moved.reason);
+        return false;
+    }
+    /** Judge a successor statement for an unpinned DID and, when accepted, move the record. */
+    async function rotateIn(pinStore, did, ed25519Pub, statement) {
+        // A rotation is judged at the trust of the peer the OLD DID belongs to: the new DID itself is still unknown.
+        const oldRecord = store ? await store.findByExternalId("a2a-agent", statement.oldDid) : null;
+        const oldTrust = oldRecord?.trustLevel ?? "stranger";
+        const decision = (0, a2a_client_1.evaluateRotation)({
+            sodium,
+            pinStore,
+            fromAgentId: statement.oldDid,
+            trustOfSource: oldTrust,
+            newDid: did,
+            newEd25519Pub: ed25519Pub,
+            rotationProof: statement.rotationProof,
+            successorProof: statement.successorProof,
+            issuedAt: statement.issuedAt,
+        });
+        if (decision.decision !== "accepted") {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "channels",
+                event: "channel.a2a_rotation_rejected",
+                message: "A2A key rotation rejected",
+                /* v8 ignore next -- the new DID has no pin, so evaluateRotation cannot call it unchanged @preserve */
+                meta: { oldDid: statement.oldDid, newDid: did, trustOfSource: oldTrust, reason: decision.decision === "rejected" ? decision.reason : decision.decision },
+            });
+            return false;
+        }
+        // Accepted means the old record is family or friend, which was read from `store`, so both are present.
+        if (!(await moveRecord(store, pinStore, statement.oldDid, did, oldRecord)))
+            return false;
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_rotation_accepted",
+            message: "A2A signed key rotation accepted",
+            meta: { oldDid: statement.oldDid, newDid: did, trustOfSource: oldTrust },
+        });
+        return true;
+    }
+    /**
+     * A pin that a rotation moved to `did`: if the peer's record still sits at an earlier DID on the chain, the move
+     * failed earlier, so retry it. Returns false while the record still cannot follow.
+     */
+    async function finishMove(pinStore, did) {
+        if (!store || typeof pinStore.predecessorOf !== "function")
+            return true;
+        const chain = [];
+        for (let prev = pinStore.predecessorOf(did); prev !== undefined && chain.length < MAX_PREDECESSOR_HOPS; prev = pinStore.predecessorOf(prev)) {
+            chain.unshift(prev);
+        }
+        for (const earlier of chain) {
+            const record = await store.findByExternalId("a2a-agent", earlier);
+            if (!record)
+                continue;
+            (0, runtime_1.emitNervesEvent)({
+                component: "channels",
+                event: "channel.a2a_rotation_record_retry",
+                message: "a rotated peer's friend record is still at its old DID; retrying the move",
+                meta: { oldDid: earlier, newDid: did },
+            });
+            if (!(await moveRecord(store, pinStore, chain[0], did, record)))
+                return false;
+            (0, runtime_1.emitNervesEvent)({
+                component: "channels",
+                event: "channel.a2a_rotation_record_moved",
+                message: "moved a rotated peer's friend record to its new DID",
+                meta: { oldDid: earlier, newDid: did },
+            });
+            return true;
+        }
+        return true;
+    }
     return {
+        async settleSender({ did, pinStore }) {
+            const parsed = (0, a2a_client_1.parseDidKey)(did);
+            // An unusable DID is refused by `resolveAndPin` itself.
+            if (!parsed)
+                return true;
+            const pinned = pinStore.get(did);
+            if (pinned)
+                return pinned.rotatedAt !== undefined && pinned.retiredBy === undefined ? finishMove(pinStore, did) : true;
+            const statement = successorFor?.(did, parsed.ed25519Pub);
+            return statement ? rotateIn(pinStore, did, parsed.ed25519Pub, statement) : true;
+        },
         async resolveAndPin(args) {
-            const { fromAgentId, did, pinStore, trustOfSource } = args;
-            // Empty DID is never a matchable key.
-            if (!did) {
-                (0, runtime_1.emitNervesEvent)({
-                    component: "channels",
-                    event: "channel.a2a_did_resolve_refused",
-                    message: "A2A DID resolve refused (empty DID)",
-                    meta: { fromAgentId, reason: "empty_did" },
-                });
-                return null;
-            }
+            const { fromAgentId, did, pinStore } = args;
+            if (!did)
+                return refused(fromAgentId, "empty_did", "A2A DID resolve refused (empty DID)");
             const parsed = (0, a2a_client_1.parseDidKey)(did);
-            if (!parsed) {
-                (0, runtime_1.emitNervesEvent)({
-                    component: "channels",
-                    event: "channel.a2a_did_resolve_refused",
-                    message: "A2A DID resolve refused (unparseable did:key)",
-                    meta: { fromAgentId, reason: "parse_failed" },
-                });
-                return null;
-            }
+            if (!parsed)
+                return refused(fromAgentId, "parse_failed", "A2A DID resolve refused (unparseable did:key)");
             const pinned = pinStore.get(fromAgentId);
-            if (!pinned) {
+            // A retired pin is a tombstone: the old key must never verify again (friends requires hosts to enforce this).
+            if (pinned?.retiredBy !== undefined)
+                return refused(fromAgentId, "retired_pin", "A2A DID resolve refused (the DID was rotated away)");
+            if (pinned) {
+                const decision = (0, a2a_client_1.evaluateRotation)({ sodium, pinStore, fromAgentId, trustOfSource: args.trustOfSource, newDid: did, newEd25519Pub: parsed.ed25519Pub });
+                if (decision.decision === "unchanged")
+                    return { ed25519Pub: parsed.ed25519Pub };
+                // A did:key encodes its key, so a differing pin means the pin was filed under another DID (or edited by hand).
+                /* v8 ignore next -- evaluateRotation only returns "accepted" with a proof, and none is passed here @preserve */
+                return refused(fromAgentId, decision.decision === "rejected" ? decision.reason : "key_changed", "A2A DID resolve refused (pinned key differs)");
+            }
+            const statement = successorFor?.(did, parsed.ed25519Pub);
+            if (!statement) {
                 // First contact (TOFU): accept + pin the (did, key) under fromAgentId.
                 (0, a2a_client_1.pinOnFirstContact)({ pinStore, fromAgentId, did, ed25519Pub: parsed.ed25519Pub });
                 (0, runtime_1.emitNervesEvent)({
@@ -55,39 +199,7 @@ function makeDidResolution(input) {
                 });
                 return { ed25519Pub: parsed.ed25519Pub };
             }
-            // Already pinned: evaluate the presented key against the pin.
-            const rotationProof = rotationProofFor?.(fromAgentId, did, parsed.ed25519Pub);
-            const decision = (0, a2a_client_1.evaluateRotation)({
-                sodium,
-                pinStore,
-                fromAgentId,
-                trustOfSource,
-                newDid: did,
-                newEd25519Pub: parsed.ed25519Pub,
-                rotationProof,
-            });
-            if (decision.decision === "unchanged") {
-                // Same key — pin-hit. (FileA2APinStore.get already emitted a2a_pin_hit.)
-                return { ed25519Pub: parsed.ed25519Pub };
-            }
-            if (decision.decision === "accepted") {
-                // evaluateRotation already re-pinned to the new key under fromAgentId.
-                (0, runtime_1.emitNervesEvent)({
-                    component: "channels",
-                    event: "channel.a2a_rotation_accepted",
-                    message: "A2A signed key rotation accepted",
-                    meta: { fromAgentId, newDid: did, trustOfSource },
-                });
-                return { ed25519Pub: parsed.ed25519Pub };
-            }
-            // Rejected — loud security signal (carries the reason).
-            (0, runtime_1.emitNervesEvent)({
-                component: "channels",
-                event: "channel.a2a_rotation_rejected",
-                message: "A2A key rotation rejected",
-                meta: { fromAgentId, newDid: did, trustOfSource, reason: decision.reason },
-            });
-            return null;
+            return (await rotateIn(pinStore, did, parsed.ed25519Pub, statement)) ? { ed25519Pub: parsed.ed25519Pub } : null;
         },
     };
 }

package/dist/a2a/inbound-share.js

@@ -4,6 +4,7 @@ exports.receiveInboundShare = receiveInboundShare;
 const a2a_client_1 = require("@ouro.bot/friends/a2a-client");
 const friends_1 = require("@ouro.bot/friends");
 const runtime_1 = require("../nerves/runtime");
+const seen_ledger_1 = require("./seen-ledger");
 /** Whether the inbound message carries a friends data part (kind:"data"). */
 function hasDataPart(message) {
     return Array.isArray(message.parts) && message.parts.some((p) => p && p.kind === "data");
@@ -20,11 +21,17 @@ function hasDataPart(message) {
  *      verify the signature; the real auth gate is the `DidVerifier` inside
  *      `receiveShare`, so a forged-high-trust claim here is harmless — the forge is
  *      rejected by the verifier regardless of the trust we read.)
- *   3. `findFriendByDid(store, verifiedDid)` — read trust off that record; an
+ *   3. `settleSender(verifiedDid)` — apply a signed rotation to that DID, or finish
+ *      one whose record did not follow, BEFORE trust is read, so the first message
+ *      after a rotation is judged against the moved record. A rejected rotation, or
+ *      a record that still cannot follow ⇒ `resolve_failed`, nothing consumed. (A
+ *      successor statement carries its own two signatures, so applying it before
+ *      this message's signature is checked gives a forger nothing.)
+ *   4. `findFriendByDid(store, verifiedDid)` — read trust off that record; an
  *      unknown DID ⇒ `stranger` (never a default-up).
- *   4. `receiveShare({ ..., trustOfSource })` — re-unseal (deterministic) + resolve
+ *   5. `receiveShare({ ..., trustOfSource })` — re-unseal (deterministic) + resolve
  *      & pin + run `DidVerifier` (forge fails HERE) + replay-dedup + import.
- *   5. Map the result. `completed` ⇒ run the turn at `verifiedDid`/`trust`.
+ *   6. Map the result. `completed` ⇒ run the turn at `verifiedDid`/`trust`.
  */
 async function receiveInboundShare(message, deps) {
     const friendsMessage = message;
@@ -64,6 +71,15 @@ async function receiveInboundShare(message, deps) {
         return { outcome: "rejected", reason: opened.error };
     }
     const verifiedDid = opened.fromAgentId;
+    if (!(await deps.didResolution.settleSender({ did: verifiedDid, pinStore: deps.pinStore }))) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_inbound_rejected",
+            message: "rejected inbound A2A share (the sender's key rotation could not be applied)",
+            meta: { reason: "resolve_failed", verifiedDid },
+        });
+        return { outcome: "rejected", reason: "resolve_failed" };
+    }
     // Read trust from the friend store BY the verified DID — never defaulted, never
     // from the envelope. Unknown (or empty) DID ⇒ stranger. `findFriendByDid` itself
     // refuses a falsy did (never matches a did-less record), so this is safe to call
@@ -81,6 +97,9 @@ async function receiveInboundShare(message, deps) {
         recipientDid: deps.identity.did,
         recipientIdentity,
         trustOfSource: trust,
+        // Every sender on friends alpha.15 or later binds its envelopes to recipient, kind, id and time; an unbound
+        // envelope can be replayed or re-sealed to another recipient, so it is refused.
+        options: { ...(0, seen_ledger_1.bindingWindowsWithinRetention)(deps.bindingOptions), rejectUnboundEnvelopes: true },
     });
     if (result.state === "completed") {
         (0, runtime_1.emitNervesEvent)({
@@ -96,6 +115,8 @@ async function receiveInboundShare(message, deps) {
             friendsKind: result.friendsKind,
             status: result.status,
             ...(result.message ? { message: result.message } : {}),
+            // Unbound envelopes are refused above, so a completed receipt always carries its signed binding id.
+            bindingId: result.bindingId,
             /* v8 ignore next -- a completed receipt implies a trusted friend record: an unknown DID reads as stranger and is refused @preserve */
             ...(record ? { friend: record } : {}),
         };

package/dist/a2a/mission-result-wire.js

@@ -2,10 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.wrapMissionResultDataPart = wrapMissionResultDataPart;
 exports.isMissionResultDataPart = isMissionResultDataPart;
+exports.sealedBlobKey = sealedBlobKey;
 exports.receiveInboundMissionResult = receiveInboundMissionResult;
 const a2a_client_1 = require("@ouro.bot/friends/a2a-client");
 const friends_1 = require("@ouro.bot/friends");
 const runtime_1 = require("../nerves/runtime");
+const seen_ledger_1 = require("./seen-ledger");
 /**
  * THE HARNESS-OWNED RESULT WIRE.
  *
@@ -33,7 +35,7 @@ const runtime_1 = require("../nerves/runtime");
  *   3. hand `importMissionResult` a REAL `DidVerifier` bound to the pinned key, so
  *      `verifier.verify(fromAgentId, proof)` runs the Ed25519 signature check against
  *      the pinned key — NOT the no-op `tofuVerifier` the importer defaults to.
- * Replay is deduped on the seal nonce (durable `SeenLedger`), matching the share path.
+ * Replay is deduped on a hash of the whole sealed blob (durable `SeenLedger`), matching the share path.
  */
 const OURO_RESULT_KIND = "mission_result";
 /** Wrap a sealed result envelope into the harness-owned `mission_result` DataPart. */
@@ -73,24 +75,52 @@ function unwrapMissionResultDataPart(message) {
         return null;
     return { sealed: { v: data.v, sealed: data.sealed }, recipientDid: data.recipientDid };
 }
+/** The ledger key for one sealed blob: a hash over its ephemeral key, nonce and ciphertext. Same form as friends'
+ * `receiveShare` key, so a blob accepted on either path is a replay on the other. */
+function sealedBlobKey(sodium, blob) {
+    const digest = sodium.crypto_generichash(24, `${blob.ePk}|${blob.n}|${blob.ct}`, null);
+    return `blob:${sodium.to_base64(digest, sodium.base64_variants.URLSAFE_NO_PADDING)}`;
+}
+/** Results being processed, per seen ledger: a parallel duplicate is refused as `in_flight` (retryable) without
+ * touching the durable ledger, matching friends' `receiveShare`. */
+const IN_FLIGHT = new WeakMap();
+function inFlightFor(seen) {
+    let set = IN_FLIGHT.get(seen);
+    if (!set) {
+        set = new Set();
+        IN_FLIGHT.set(seen, set);
+    }
+    return set;
+}
+function rejectResult(reason, message, meta = {}) {
+    (0, runtime_1.emitNervesEvent)({ component: "channels", event: "channel.a2a_result_rejected", message, meta: { reason, ...meta } });
+    return { outcome: "rejected", reason };
+}
 /**
  * Route an inbound `mission_result` DataPart to `importMissionResult`, AUTHENTICATING
  * the sender exactly like `receiveShare` does for every other inbound kind.
  *
  * Ordering (mirrors the share bridge's trust trap + authentication gate):
  *   1. recognize + unwrap the harness `mission_result` carrier (else `not-a-result`).
- *   2. replay dedup on the seal nonce (durable `SeenLedger`) — before any state change.
+ *   2. replay dedup on a hash of the whole sealed blob, then the in-flight claim on
+ *      that hash. The bare seal nonce is never consulted.
  *   3. `openSealedEnvelope` → AEAD-decrypt only (unseal/recipient failures → reject).
- *   4. binding check — reject unless `opened.signerDid === opened.fromAgentId` (and
+ *   4. sender binding — reject unless `opened.signerDid === opened.fromAgentId` (and
  *      non-empty): the advisory `signerDid` (outer, unsigned) must match the claimed
  *      sender. A divergence is a forged/spoofed bundle (`sender_binding_mismatch`).
- *   5. `resolveAndPin` the sender DID (TOFU pin / signed-rotation) → the pinned key
- *      (unresolvable/failed-binding/failed-rotation → `resolve_failed`).
- *   6. build a `DidVerifier` bound to THIS envelope + the pinned key, mark the nonce
- *      seen, then call `importMissionResult({ envelope, fromAgentId: <signed DID>,
- *      trustOfSource }, { verifier })`. The verifier runs the REAL signature check
- *      against the pinned key — a result signed with a key that is not the pinned key
- *      for the claimed DID is rejected (`untrusted_source`). Every authorization gate
+ *   5. a retired sender pin → `retired_pin`.
+ *   6. the signed envelope binding (`checkEnvelopeBinding`: this recipient, this kind,
+ *      a fresh issue time, an unseen `mid:` message id), then claim the blob hash and
+ *      the `mid:` key in flight (released on every exit).
+ *   7. `settleSender` — apply a signed rotation to the sender DID, or finish one whose
+ *      record did not follow, BEFORE trust is read (refused → `resolve_failed`).
+ *   8. read trust by the sender DID, then `resolveAndPin` it (TOFU pin) → the pinned
+ *      key (unresolvable → `resolve_failed`).
+ *   9. build a `DidVerifier` bound to THIS envelope + the pinned key and call
+ *      `importMissionResult({ envelope, fromAgentId: <signed DID>, trustOfSource },
+ *      { verifier })`. The verifier runs the REAL signature check against the pinned
+ *      key and marks the claimed keys seen only when it passes; a result signed with
+ *      any other key is rejected (`untrusted_source`). Every authorization gate
  *      (no_mission / no_delegation / assignee_mismatch, fail-closed on a legacy
  *      assignee-less delegation) is still enforced by the importer.
  */
@@ -98,16 +128,17 @@ async function receiveInboundMissionResult(message, deps) {
     const payload = unwrapMissionResultDataPart(message);
     if (!payload)
         return { outcome: "not-a-result" };
-    // Replay dedup BEFORE any state change, keyed on the seal nonce (matches receiveShare).
-    if (deps.seen.isSeen(payload.sealed.sealed.n)) {
-        (0, runtime_1.emitNervesEvent)({
-            component: "channels",
-            event: "channel.a2a_result_rejected",
-            message: "rejected inbound mission_result (replayed seal nonce)",
-            meta: { reason: "replayed" },
-        });
-        return { outcome: "rejected", reason: "replayed" };
+    // Replay dedup BEFORE any state change, keyed only on a hash of the whole sealed blob. The sender picks the seal
+    // nonce, and friends' share path marks a bare nonce for any share whose signature verifies, so reading the bare nonce
+    // here would let a stranger's share or result burn a real result. A re-sealed copy of the same signed result is still
+    // refused by its `mid:` key, and re-importing a result changes nothing (the first result per request wins).
+    const blobKey = sealedBlobKey(deps.sodium, payload.sealed.sealed);
+    if (deps.seen.isSeen(blobKey)) {
+        return rejectResult("replayed", "rejected inbound mission_result (already received)");
     }
+    const inFlight = inFlightFor(deps.seen);
+    if (inFlight.has(blobKey))
+        return rejectResult("in_flight", "rejected inbound mission_result (the same result is being processed)");
     const recipientIdentity = { x25519Priv: deps.identity.x25519Priv, x25519Pub: deps.identity.x25519Pub };
     const opened = (0, a2a_client_1.openSealedEnvelope)({
         sodium: deps.sodium,
@@ -140,6 +171,34 @@ async function receiveInboundMissionResult(message, deps) {
         });
         return { outcome: "rejected", reason: "sender_binding_mismatch" };
     }
+    // A retired pin is a tombstone: the old DID's key verifies nothing (matches receiveShare).
+    if (deps.pinStore.get(senderDid)?.retiredBy !== undefined) {
+        return rejectResult("retired_pin", "rejected inbound mission_result (the sender's DID was rotated away)", { verifiedDid: senderDid });
+    }
+    // The signed binding: this recipient, this kind, a fresh issue time and an unseen message id.
+    const binding = (0, a2a_client_1.checkEnvelopeBinding)(opened, { ...(0, seen_ledger_1.bindingWindowsWithinRetention)(deps.bindingOptions), rejectUnboundEnvelopes: true, recipientDid: deps.identity.did, seen: deps.seen });
+    if (!binding.ok)
+        return rejectResult(binding.reason, "rejected inbound mission_result (signed binding)", { verifiedDid: senderDid });
+    /* v8 ignore next -- an unbound envelope is refused above, so a passing binding always carries its seen key @preserve */
+    const claimed = binding.seenKey ? [blobKey, binding.seenKey] : [blobKey];
+    /* v8 ignore next -- the same binding id under a different seal nonce needs a hand-built seal (sealEnvelope mints a fresh id) @preserve */
+    if (claimed.some((key) => inFlight.has(key)))
+        return rejectResult("in_flight", "rejected inbound mission_result (the same result is being processed)");
+    for (const key of claimed)
+        inFlight.add(key);
+    try {
+        return await processClaimedResult(opened, senderDid, claimed, deps);
+    }
+    finally {
+        for (const key of claimed)
+            inFlight.delete(key);
+    }
+}
+async function processClaimedResult(opened, senderDid, claimed, deps) {
+    // Settle a rotation to this DID first, so the first result after it is judged against the moved record.
+    if (!(await deps.didResolution.settleSender({ did: senderDid, pinStore: deps.pinStore }))) {
+        return rejectResult("resolve_failed", "rejected inbound mission_result (the sender's key rotation could not be applied)", { verifiedDid: senderDid });
+    }
     // Read trust from the friend store BY the verified DID — never defaulted, never from
     // the envelope. Unknown (or empty) DID ⇒ stranger.
     const record = await (0, friends_1.findFriendByDid)(deps.store, senderDid);
@@ -164,14 +223,24 @@ async function receiveInboundMissionResult(message, deps) {
     // single authentication gate (the importer would otherwise default to the no-op TOFU
     // verifier). `verify` confirms the agentId===did binding AND the Ed25519 signature
     // over the envelope against the pinned key.
-    const verifier = new a2a_client_1.DidVerifier({
+    const didVerifier = new a2a_client_1.DidVerifier({
         sodium: deps.sodium,
         pinnedEd25519Pub: resolved.ed25519Pub,
         pinnedDid: senderDid,
         envelope: opened.envelope,
     });
-    // Mark seen now (idempotent imports + the replay guard above keep this safe).
-    deps.seen.markSeen(payload.sealed.sealed.n);
+    // The result is consumed the moment its signature verifies (and not before), so a failure before that leaves it
+    // redeliverable. The keys are the whole-blob hash and the sender-scoped `mid:` id, so no other sender's message,
+    // share or result, can burn this one by reusing its seal nonce.
+    const verifier = {
+        verify(fromAgentId, proof) {
+            const ok = didVerifier.verify(fromAgentId, proof);
+            if (ok)
+                for (const key of claimed)
+                    deps.seen.markSeen(key);
+            return ok;
+        },
+    };
     const result = await (0, friends_1.importMissionResult)(deps.missionStore, {
         envelope: opened.envelope,
         fromAgentId: senderDid,

package/dist/a2a/outbox-client.js

@@ -40,9 +40,9 @@ async function callOutboxMethod(input) {
     const reply = rpc.result;
     if (!reply || !Array.isArray(reply.parts))
         throw new Error("A2A outbox call returned no reply message");
-    const opened = await (0, sealed_chat_1.openChatMessage)({ sodium, self: input.identity, message: reply, senderDid: peerDid, senderEd25519Pub: parsed.ed25519Pub });
+    const opened = await (0, sealed_chat_1.openChatMessage)({ sodium, self: input.identity, message: reply, senderDid: peerDid, senderEd25519Pub: parsed.ed25519Pub, ...(input.seen ? { seen: input.seen } : {}) });
     if (!opened.ok)
-        throw new Error(`A2A outbox reply rejected: ${opened.reason}`);
+        throw (0, client_1.replyRefusedError)("outbox", opened.reason);
     let result;
     try {
         result = JSON.parse(opened.text);

package/dist/a2a/pin-store.js

@@ -42,6 +42,14 @@ const runtime_1 = require("../nerves/runtime");
 function pinFileName(fromAgentId) {
     return `${(0, node_crypto_1.createHash)("sha256").update(fromAgentId).digest("hex")}.json`;
 }
+function pinnedFromStored(stored, ed25519Pub) {
+    return {
+        did: stored.did,
+        ed25519Pub,
+        ...(typeof stored.rotatedAt === "string" ? { rotatedAt: stored.rotatedAt } : {}),
+        ...(typeof stored.retiredBy === "string" ? { retiredBy: stored.retiredBy } : {}),
+    };
+}
 class FileA2APinStore {
     dir;
     cache = new Map();
@@ -79,15 +87,7 @@ class FileA2APinStore {
         if (!fromAgentId)
             return;
         const existed = this.cache.has(fromAgentId);
-        // Faithfully persist the pinned identity's DID (which may differ from
-        // fromAgentId after a rotation), not fromAgentId itself.
-        const stored = {
-            fromAgentId,
-            did: pinned.did,
-            pinnedKey: (0, a2a_client_1.base58btcEncode)(pinned.ed25519Pub),
-        };
-        fs.writeFileSync(path.join(this.dir, pinFileName(fromAgentId)), `${JSON.stringify(stored, null, 2)}\n`, "utf-8");
-        this.cache.set(fromAgentId, { did: pinned.did, ed25519Pub: pinned.ed25519Pub });
+        this.write(fromAgentId, pinned);
         (0, runtime_1.emitNervesEvent)({
             component: "channels",
             event: "channel.a2a_pin_set",
@@ -95,6 +95,41 @@ class FileA2APinStore {
             meta: { fromAgentId, did: pinned.did, rotated: existed },
         });
     }
+    /** Keep a tombstone under `fromAgentId`: the old DID and key, marked retired in favour of `retiredBy`. friends
+     * calls this after it moves the pin to the successor DID; `receiveShare` then refuses the old DID as `retired_pin`. */
+    retire(fromAgentId, retiredBy, rotatedAt) {
+        const pinned = this.cache.get(fromAgentId);
+        if (!fromAgentId || !pinned)
+            return;
+        this.write(fromAgentId, { ...pinned, retiredBy, rotatedAt });
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "channels",
+            event: "channel.a2a_pin_retired",
+            message: "retired an A2A pin after a verified rotation",
+            meta: { fromAgentId, retiredBy, rotatedAt },
+        });
+    }
+    /** The DID whose retired pin names `did` as its successor, if any (a rotation chain followed backwards). */
+    predecessorOf(did) {
+        for (const [fromAgentId, pinned] of this.cache) {
+            if (pinned.retiredBy === did)
+                return fromAgentId;
+        }
+        return undefined;
+    }
+    /** Persist a pin (its DID, which may differ from fromAgentId, its key, and the rotation fields) and cache it. */
+    write(fromAgentId, pinned) {
+        const stored = {
+            fromAgentId,
+            did: pinned.did,
+            pinnedKey: (0, a2a_client_1.base58btcEncode)(pinned.ed25519Pub),
+            ...(pinned.rotatedAt !== undefined ? { rotatedAt: pinned.rotatedAt } : {}),
+            ...(pinned.retiredBy !== undefined ? { retiredBy: pinned.retiredBy } : {}),
+        };
+        fs.writeFileSync(path.join(this.dir, pinFileName(fromAgentId)), `${JSON.stringify(stored, null, 2)}\n`, "utf-8");
+        this.cache.set(fromAgentId, pinnedFromStored(stored, pinned.ed25519Pub));
+    }
     /** Reload every persisted pin from disk into the in-memory cache (the restart
      * replay). Corrupt/undecodable files are skipped so one bad file can never
      * wedge the store. */
@@ -125,7 +160,7 @@ class FileA2APinStore {
             const ed25519Pub = (0, a2a_client_1.base58btcDecode)(stored.pinnedKey);
             if (!ed25519Pub)
                 continue;
-            this.cache.set(key, { did: stored.did, ed25519Pub });
+            this.cache.set(key, pinnedFromStored(stored, ed25519Pub));
         }
     }
 }

package/dist/a2a/refusals.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.receiveRefusal = receiveRefusal;
+exports.receiveRefusalError = receiveRefusalError;
+const runtime_1 = require("../nerves/runtime");
+const UPGRADE = "Upgrade the sending agent's harness (ouro) and send again.";
+const RESEND = "Send it again as a new message.";
+const REFUSALS = {
+    malformed_message: { message: "the message is not a sealed A2A data part", next: UPGRADE, retry: false },
+    malformed_plaintext: { message: "the sealed message did not open to a valid envelope", next: UPGRADE, retry: false },
+    unseal_failed: { message: "the message could not be opened with this agent's key", next: "Fetch this agent's card again (its key may have changed) and resend.", retry: false },
+    recipient_mismatch: { message: "the message was sealed to a different agent", next: "Check the recipient's DID and resend.", retry: false },
+    signed_recipient_mismatch: { message: "the signed envelope names a different recipient", next: "Check the recipient's DID and resend.", retry: false },
+    signed_kind_mismatch: { message: "the signed envelope's kind does not match how it was sealed", next: UPGRADE, retry: false },
+    sender_binding_mismatch: { message: "the claimed sender does not match the signer", next: "Send from the identity the message claims.", retry: false },
+    malformed_binding: { message: "the envelope's signed binding is malformed", next: UPGRADE, retry: false },
+    unbound_envelope: { message: "the envelope has no signed binding (the sender runs an older harness)", next: UPGRADE, retry: false },
+    unbound_delegation: { message: "the delegated command has no signed binding (the sender runs an older harness)", next: UPGRADE, retry: false },
+    stale_envelope: { message: "the envelope is more than 7 days old or dated in the future", next: `Check the sender's clock. ${RESEND}`, retry: false },
+    stale_delegation: { message: "the delegated command is more than 10 minutes old", next: `Check the sender's clock. ${RESEND}`, retry: false },
+    replayed: { message: "this message was already received", next: `Nothing to do if it was delivered; otherwise ${RESEND.toLowerCase()}`, retry: false },
+    in_flight: { message: "the same message is being handled right now", next: "Retry in a moment.", retry: true },
+    resolve_failed: { message: "the sender's DID could not be resolved or pinned (it is not a did:key, its pinned key differs, or a key rotation was refused)", next: "Send from the identity this agent knows you by, or ask the operator to re-link you.", retry: false },
+    retired_pin: { message: "the sender's DID was rotated to a successor and no longer verifies", next: "Send from the successor identity.", retry: false },
+    bad_signature: { message: "the signature does not verify against the sender's pinned key", next: "Send from the key this agent pinned for you, or ask the operator to re-link you.", retry: false },
+    untrusted_source: { message: "this agent does not trust the sender enough for this kind of message", next: "Ask the operator to connect you as a friend.", retry: false },
+    import_failed: { message: "the message verified but could not be stored", next: RESEND, retry: false },
+    // Mission results (the harness result wire).
+    no_mission: { message: "this agent has no mission with that key", next: "Check the mission key; the delegator may have dropped the mission.", retry: false },
+    no_delegation: { message: "this agent delegated no task with that request id", next: "Check the request id the delegation gave you.", retry: false },
+    assignee_mismatch: { message: "the task was delegated to a different agent", next: "Only the assignee can send this result.", retry: false },
+};
+const UNKNOWN = { message: "the message was refused", next: "Check the agent's logs.", retry: false };
+/** The wording for one refusal reason (an unknown reason gets a generic line). */
+function receiveRefusal(reason) {
+    return Object.hasOwn(REFUSALS, reason) ? REFUSALS[reason] : UNKNOWN;
+}
+/** The JSON-RPC error text and data for a refused inbound message: `A2A <what> rejected: <reason>. <message>. Next: <next>`. */
+function receiveRefusalError(what, reason) {
+    const refusal = receiveRefusal(reason);
+    (0, runtime_1.emitNervesEvent)({ component: "channels", event: "channel.a2a_receive_refused", message: "refused an inbound A2A message", meta: { what, reason, retry: refusal.retry } });
+    return { message: `A2A ${what} rejected: ${reason}. ${refusal.message}. Next: ${refusal.next}`, data: { reason, retry: refusal.retry, next: refusal.next } };
+}

package/dist/a2a/sealed-chat.js

@@ -78,12 +78,13 @@ async function openChatMessage(input) {
                 return pinned ? { ed25519Pub: pinned.ed25519Pub } : null;
             },
         },
-        seen: new MemorySeenLedger(),
+        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)({

package/dist/a2a/seen-ledger.js

@@ -33,21 +33,65 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FileA2ASeenLedger = void 0;
+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 a seen entry must be kept: friends accepts an envelope until 7 days after its `issuedAt`, and an `issuedAt`
+ * at most 2 minutes ahead of the clock, so an entry marked longer ago than both can never match an acceptable
+ * envelope again (`DEFAULT_MAX_AGE_MS` plus `DEFAULT_MAX_FUTURE_SKEW_MS` in friends `envelope-binding`).
+ */
+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;
-    cache = new Set();
-    constructor(agentRoot) {
+    /** 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",
@@ -80,14 +124,43 @@ class FileA2ASeenLedger {
             return;
         if (this.cache.has(nonce))
             return;
-        fs.writeFileSync(path.join(this.dir, nonceFileName(nonce)), `${JSON.stringify({ nonce, markedAt: new Date().toISOString() }, null, 2)}\n`, "utf-8");
-        this.cache.add(nonce);
+        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
@@ -104,17 +177,34 @@ class FileA2ASeenLedger {
         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(path.join(this.dir, name), "utf-8"));
+                record = JSON.parse(fs.readFileSync(file, "utf-8"));
             }
             catch {
                 continue;
             }
             if (typeof record.nonce === "string" && record.nonce.length > 0) {
-                this.cache.add(record.nonce);
+                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);
+}

package/dist/a2a/server.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ESCALATION_CONFIRM_INTERVAL_MS = void 0;
 exports.a2aChatRelationship = a2aChatRelationship;
+exports.commandIdFor = commandIdFor;
 exports.startA2AServer = startA2AServer;
 const http = __importStar(require("node:http"));
 const node_crypto_1 = require("node:crypto");
@@ -56,6 +57,7 @@ const mission_result_wire_1 = require("./mission-result-wire");
 const delegation_stores_1 = require("./delegation-stores");
 const task_store_1 = require("./task-store");
 const delegated_command_1 = require("./delegated-command");
+const refusals_1 = require("./refusals");
 const outbox_wire_1 = require("./outbox-wire");
 const failure_reports_1 = require("../heart/failure-reports");
 const MAX_A2A_REQUEST_BYTES = 128 * 1024;
@@ -206,6 +208,22 @@ function messageHasDataPart(message) {
         return false;
     return message.parts.some((part) => part && part.kind === "data");
 }
+/**
+ * A delegated command's id: a hash of the sender's DID, its signed message id and its signed issue time. A redelivery of
+ * the same message names the same command, while a sender reusing a message id on a new message (possible once the
+ * old one ages out of the seen ledger) gets a new command, so it can never ride an earlier command's owner notice or
+ * effect record. A message without a binding (unbound, so refused upstream) falls back to a random id.
+ */
+function commandIdFor(chat) {
+    /* v8 ignore next -- unbound envelopes are refused before a delegated command is admitted @preserve */
+    if (!chat.bindingId)
+        return (0, node_crypto_1.randomUUID)();
+    return (0, node_crypto_1.createHash)("sha256").update(JSON.stringify([chat.did, chat.bindingId, chat.issuedAt ?? ""])).digest("hex").slice(0, 32);
+}
+function refusalResponse(id, what, reason) {
+    const refusal = (0, refusals_1.receiveRefusalError)(what, reason);
+    return errorResponse(id, rejectionErrorCode(reason), refusal.message, refusal.data);
+}
 /** Map a friends `receiveShare` rejection reason → a JSON-RPC error code.
  * Malformed-shape reasons map to invalid-params (-32602); auth/trust/replay
  * rejections map to a dedicated A2A "rejected" code (-32003). */
@@ -386,15 +404,16 @@ async function startA2AServer(options) {
     let inboundShareDeps;
     if (options.identity) {
         const friendsDir = `${agentRoot}/friends`;
+        const friendStore = new friends_1.FileFriendStore(friendsDir);
         inboundShareDeps = {
             sodium: await (0, a2a_client_1.ready)(),
-            store: new friends_1.FileFriendStore(friendsDir),
+            store: friendStore,
             // The SAME canonical mission store the Slice-4 delegation tools use, so an
             // inbound `importCoordination` write lands where the read/prepare surface reads.
             missionStore: (0, delegation_stores_1.delegationStoresFor)(agentRoot).missionStore,
             pinStore: new pin_store_1.FileA2APinStore(agentRoot),
             seen: new seen_ledger_1.FileA2ASeenLedger(agentRoot),
-            didResolution: (0, did_resolution_1.makeDidResolution)({ sodium: await (0, a2a_client_1.ready)() }),
+            didResolution: (0, did_resolution_1.makeDidResolution)({ sodium: await (0, a2a_client_1.ready)(), store: friendStore, agentName: options.agentName, notifyOwner: options.notifyOwner }),
             identity: options.identity,
         };
     }
@@ -453,7 +472,7 @@ async function startA2AServer(options) {
                 }
                 const bridged = await (0, inbound_share_1.receiveInboundShare)({ ...outboxInbound, kind: outboxInbound.kind ?? "message" }, inboundShareDeps);
                 if (bridged.outcome === "rejected") {
-                    writeJson(res, 200, errorResponse(rpc.id, rejectionErrorCode(bridged.reason), `A2A outbox call rejected: ${bridged.reason}`));
+                    writeJson(res, 200, refusalResponse(rpc.id, "outbox call", bridged.reason));
                     return;
                 }
                 if (bridged.outcome !== "completed" || !bridged.message) {
@@ -507,7 +526,7 @@ async function startA2AServer(options) {
                         identity: inboundShareDeps.identity,
                     });
                     if (imported.outcome === "rejected") {
-                        writeJson(res, 200, errorResponse(rpc.id, rejectionErrorCode(imported.reason), `A2A result rejected: ${imported.reason}`));
+                        writeJson(res, 200, refusalResponse(rpc.id, "result", imported.reason));
                         return;
                     }
                     // imported (store-only, no turn): acknowledge with a minimal completed task.
@@ -535,7 +554,7 @@ async function startA2AServer(options) {
                 if (inbound && inboundShareDeps && messageHasDataPart(inbound)) {
                     const bridged = await (0, inbound_share_1.receiveInboundShare)(inbound, inboundShareDeps);
                     if (bridged.outcome === "rejected") {
-                        writeJson(res, 200, errorResponse(rpc.id, rejectionErrorCode(bridged.reason), `A2A share rejected: ${bridged.reason}`));
+                        writeJson(res, 200, refusalResponse(rpc.id, "share", bridged.reason));
                         return;
                     }
                     // A message with a data part always resolves to completed|rejected — the
@@ -550,7 +569,7 @@ async function startA2AServer(options) {
                             verifiedShareText = bridged.message.text;
                             /* v8 ignore next -- a completed chat always has a friend record: an unknown DID reads as stranger and the message is refused @preserve */
                             verifiedPeerName = bridged.friend?.name ?? bridged.verifiedDid;
-                            verifiedChat = { did: bridged.verifiedDid, friend: bridged.friend, ...(bridged.message.onBehalfOf ? { onBehalfOf: bridged.message.onBehalfOf } : {}) };
+                            verifiedChat = { did: bridged.verifiedDid, friend: bridged.friend, ...(bridged.message.onBehalfOf ? { onBehalfOf: bridged.message.onBehalfOf } : {}), bindingId: bridged.bindingId, issuedAt: bridged.message.issuedAt };
                         }
                         else {
                             verifiedShareText = `[a2a] received ${bridged.friendsKind} (${bridged.status}) from ${bridged.verifiedDid}`;
@@ -610,7 +629,7 @@ async function startA2AServer(options) {
                     /* v8 ignore next -- a completed chat always carries the sender's friend record (see the receipt above) @preserve */
                     if (!verifiedChat.friend)
                         throw new Error("verified chat has no friend record");
-                    const admission = await (0, delegated_command_1.admitDelegatedCommand)({ friend: verifiedChat.friend, did: verifiedChat.did, text, commandId: (0, node_crypto_1.randomUUID)(), store: inboundShareDeps.store, registry, options: options.delegation });
+                    const admission = await (0, delegated_command_1.admitDelegatedCommand)({ friend: verifiedChat.friend, did: verifiedChat.did, text, commandId: commandIdFor(verifiedChat), store: inboundShareDeps.store, registry, options: options.delegation });
                     if (!admission.ok) {
                         // The code and the "delegated command refused: <reason>" prefix stay: the replay gate and older CLIs match them.
                         // Only an active family peer is told why: anyone else gets no_grant whatever the real reason was (a broken trust file, a key mismatch), which stays in the local log and nerves.

package/dist/heart/daemon/cli-exec.js

@@ -6269,6 +6269,10 @@ async function executeFriendCommand(command, store, paths) {
             return `friend not found: ${command.friendId}`;
         if (result.status === "noop")
             return `identity already linked: ${command.provider}:${command.externalId}`;
+        // Anything but linked or merged changed nothing (for example conflict_requires_operator or retry_unsupported).
+        if (result.status !== "linked" && result.status !== "merged") {
+            return `not linked: ${command.provider}:${command.externalId} (${[result.status, result.message].filter(Boolean).join(": ")})`;
+        }
         const mergeMessage = result.status === "merged" ? " (merged orphan)" : "";
         return `linked ${command.provider}:${command.externalId} to ${command.friendId}${mergeMessage}`;
     }
@@ -6332,6 +6336,9 @@ async function executeA2AClientCommand(command, deps) {
     /* v8 ignore next -- production CLI keeps the client key under the home dir; tests pass an explicit file @preserve */
     const identityFile = command.identityFile ?? path.join(os.homedir(), ".ouro-cli", "a2a", "client-identity.json");
     const identity = await loadOrMintA2AIdentityFile({ filePath: identityFile });
+    // Replies are replay-checked against a durable ledger beside the identity file, so an old reply cannot be served again.
+    const { openPrivateSeenLedger } = await Promise.resolve().then(() => __importStar(require("../../a2a/seen-ledger")));
+    const replySeen = () => openPrivateSeenLedger(path.join(path.dirname(identityFile), "reply-ledger"));
     if (command.kind === "a2a.identity") {
         const message = command.json ? JSON.stringify({ did: identity.did, identityFile }) : `did: ${identity.did}\nidentity file: ${identityFile}`;
         deps.writeStdout(message);
@@ -6349,7 +6356,7 @@ async function executeA2AClientCommand(command, deps) {
                     return { method: "report/resolve", params: { id: claim.reportId, version: claim.version, note: claim.note, resolvedAt: claim.resolvedAt, proof: signResolution({ sodium: await ready(), identity, claim }) } };
                 })();
         const result = await callOutboxMethod({
-            cardUrl: command.to, ...call, identity,
+            cardUrl: command.to, ...call, identity, seen: replySeen(),
             /* v8 ignore next -- production CLI uses global fetch; tests inject fetch for a hermetic peer @preserve */
             ...(deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {}),
         });
@@ -6366,6 +6373,7 @@ async function executeA2AClientCommand(command, deps) {
             ...(command.conversationId ? { conversationId: command.conversationId } : {}),
             ...(command.delegated ? { onBehalfOf: "principal" } : {}),
             identity,
+            seen: replySeen(),
             /* v8 ignore next -- production CLI uses global fetch; tests inject fetch for a hermetic peer @preserve */
             ...(deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {}),
         });

package/dist/senses/a2a-entry.js

@@ -112,6 +112,7 @@ Promise.all([
             },
         } : {}),
         ...escalationOptionsFor(agentName, (notice) => sendOwnerNoticeViaTelegram(agentName, notice)),
+        notifyOwner: (notice) => sendOwnerNoticeViaTelegram(agentName, notice),
         ...(argValue("--host") ? { host: argValue("--host") } : {}),
         ...(Number.isInteger(port) ? { port } : {}),
         ...(argValue("--base-url") ? { baseUrl: argValue("--base-url") } : {}),

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.987",
+  "version": "0.1.0-alpha.989",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@ouro.bot/cli",
-      "version": "0.1.0-alpha.987",
+      "version": "0.1.0-alpha.989",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.78.0",
         "@azure/identity": "^4.13.0",
@@ -18,7 +18,7 @@
         "@microsoft/teams.common": "2.0.11",
         "@microsoft/teams.dev": "2.0.11",
         "@microsoft/teams.graph": "2.0.11",
-        "@ouro.bot/friends": "0.1.0-alpha.14",
+        "@ouro.bot/friends": "0.1.0-alpha.17",
         "@types/react": "^17.0.91",
         "@types/ws": "^8.18.1",
         "ajv": "^8.20.0",
@@ -1398,9 +1398,9 @@
       }
     },
     "node_modules/@ouro.bot/friends": {
-      "version": "0.1.0-alpha.14",
-      "resolved": "https://registry.npmjs.org/@ouro.bot/friends/-/friends-0.1.0-alpha.14.tgz",
-      "integrity": "sha512-ikb633DfL8Mz4jgNJtIoMZ9F3hqYngc9o8VzVb9dSlMdwp15bvlVXUvnF/uWqQ7gzmX0GeTx54LQn8AtYFOmsg==",
+      "version": "0.1.0-alpha.17",
+      "resolved": "https://registry.npmjs.org/@ouro.bot/friends/-/friends-0.1.0-alpha.17.tgz",
+      "integrity": "sha512-hpThUpNVP7StvleA9ue3dNytIDVPuNzmw+lnrlV40hKn3rF79VMUV6X3cH0kjG0EDp4Jpj3hlfxFKEmSu/oaiw==",
       "license": "Apache-2.0",
       "dependencies": {
         "libsodium-wrappers": "0.8.4"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.987",
+  "version": "0.1.0-alpha.989",
   "engines": {
     "node": ">=22"
   },
@@ -68,7 +68,7 @@
     "@microsoft/teams.common": "2.0.11",
     "@microsoft/teams.dev": "2.0.11",
     "@microsoft/teams.graph": "2.0.11",
-    "@ouro.bot/friends": "0.1.0-alpha.14",
+    "@ouro.bot/friends": "0.1.0-alpha.17",
     "@types/react": "^17.0.91",
     "@types/ws": "^8.18.1",
     "ajv": "^8.20.0",