@nicknisi/pi-relay 0.3.0 → 0.3.1

package/README.md

@@ -51,7 +51,7 @@ main moved; rebase before you push.
 
 - **A mailbox outlives the process.** The address is a hash of the working directory and pi's session id, so a session resumed with `pi -c` answers to the same address. Mail sent to a closed session waits on disk and is read when it resumes — the common case when you're opening and closing terminals all day.
 - **The queue is inspectable.** Diagnosing delivery is `ls`, not instrumenting a transport.
-- **Consumption is the receipt.** The receiver deletes the exact full-message-id letter as it reads it, so the sender learns _delivered_ vs _queued_. A durable core claim remains queued until it is acknowledged; moving it into a claim does not produce a false receipt.
+- **Delivery is the receipt.** The receiver detaches its inbox into a durable claim and deletes each exact full-message-id letter only after the session has accepted it — a failed delivery is requeued for retry, and a crash mid-delivery leaves the letter recoverable on the next start (redeliveries are deduped by message id, seeded from the transcript). The sender therefore learns _delivered_ vs _queued_ honestly: a claimed-but-unacknowledged letter still reads _queued_, never a false receipt.
 
 ## Semantics
 

package/dist/index.js

@@ -18,7 +18,7 @@ import { getAgentDir } from '@earendil-works/pi-coding-agent';
 import { Box, getKeybindings, Text } from '@earendil-works/pi-tui';
 import { Type } from 'typebox';
 import { formatAudit, formatDelivery, formatListing, formatPendingAsk, refusalAmbiguous, refusalUnknown, shortAddr, } from './format.js';
-import { appendAudit, awaitReceipt, clearAsk, drain, deposit, outgoingAskIds, pendingAsks, previewBody, readAudit, readOutgoingAsk, resolveAskByRef, trackIncomingAsk, trackOutgoingAsk, unreadCount, watchInbox, } from './mailbox.js';
+import { ackClaimedLetter, appendAudit, awaitReceipt, claimInbox, clearAsk, deposit, outgoingAskIds, pendingAsks, previewBody, readAudit, readClaimedLetter, readOutgoingAsk, recoverInboxClaims, requeueClaimedLetter, resolveAskByRef, trackIncomingAsk, trackOutgoingAsk, unreadCount, watchInbox, } from './mailbox.js';
 import { OutboundPolicy, inboundAccepts } from './policy.js';
 import { claimAlias, deriveAddr, ensureRoot, isValidAliasName, listAliases, listRecords, presenceOf, readAlias, readRecord, sweep, writeRecord, } from './registry.js';
 function toolResult(text, details = {}) {
@@ -99,10 +99,23 @@ export default function relay(pi) {
     let unwatch;
     let heartbeat;
     const askWaiters = new Map();
-    // Backoff while the session can't accept mail: a re-deposited letter
+    // Backoff while the session can't accept mail: a requeued letter
     // re-fires the watcher, and without this a failing sendMessage would spin
-    // drain→fail→re-deposit at watch speed.
+    // claim→fail→requeue at watch speed.
     let lastDeliveryFailureAt = 0;
+    // Letter ids this session has already accepted. Claims make redelivery
+    // possible (a crash between delivery and ack, or an ack failure after a
+    // successful send); without dedupe the model would see the body twice.
+    // Seeded from the transcript on session_start so recovery after a crash
+    // doesn't redeliver what the previous process already handed to the agent.
+    const deliveredIds = new Set();
+    const DELIVERED_IDS_CAP = 512;
+    const noteDelivered = (id) => {
+        deliveredIds.delete(id); // refresh recency
+        deliveredIds.add(id);
+        if (deliveredIds.size > DELIVERED_IDS_CAP)
+            deliveredIds.delete(deliveredIds.values().next().value);
+    };
     // Presence watch: addr → last observed presence. A poller surfaces
     // transitions as a notification message (no full turn wake).
     const watched = new Map();
@@ -122,7 +135,13 @@ export default function relay(pi) {
     function deliver(letter) {
         // Audited after the delivery attempts below: a 'deliver' record means the
         // session actually accepted the letter; refusal records 'deliver-failed'
-        // (the caller re-deposits, so logging here would duplicate every retry).
+        // (the caller requeues, so logging here would duplicate every retry).
+        // Note pi.sendMessage is fire-and-forget: asynchronous failures are
+        // swallowed by the runtime (emitted as extension errors, never rethrown),
+        // so only synchronous refusals — a disposed/uninitialized runtime during
+        // reload or shutdown — reach these catches. That is exactly the case
+        // where the letter never enters the transcript: async rejections from the
+        // triggerTurn path happen after the message is already in context.
         const auditDelivery = (event) => appendAudit(root, {
             ts: Date.now(),
             event,
@@ -186,7 +205,7 @@ export default function relay(pi) {
                 }
                 catch {
                     // session is shutting down or otherwise undeliverable — the caller
-                    // re-deposits the letter so a future drain retries
+                    // requeues the letter so a future drain retries
                     auditDelivery('deliver-failed');
                     return false;
                 }
@@ -196,40 +215,86 @@ export default function relay(pi) {
     function checkInbox() {
         if (!self)
             return;
+        const me = self.addr;
         if (Date.now() - lastDeliveryFailureAt < 5000)
             return;
-        // Refuse mode: never drain. Letters stay on disk (receipts honestly read
+        // Refuse mode: never claim. Letters stay on disk (receipts honestly read
         // 'queued') instead of being silently consumed and dropped.
         if (!inboundAccepts())
             return;
-        let letters;
+        // Claim, not drain: the inbox is detached atomically and each letter is
+        // only acked (deleted) once the session has accepted it. A claimed but
+        // unacked letter still reads 'queued' to the sender's receipt, survives
+        // a crash (recoverInboxClaims on the next session_start), and can be
+        // requeued for retry — unlink-as-read could silently lose it while the
+        // sender's receipt reported "delivered".
+        let claim;
         try {
-            letters = drain(root, self.addr);
+            claim = claimInbox(root, me);
         }
         catch {
             return;
         }
-        for (const letter of letters) {
+        if (!claim)
+            return;
+        const { claimToken, fileTokens } = claim;
+        const ack = (fileToken) => {
+            try {
+                ackClaimedLetter(root, me, claimToken, fileToken);
+            }
+            catch {
+                // ack failure leaves the letter claimed; recovery requeues it and
+                // deliveredIds suppresses the duplicate
+            }
+        };
+        for (const fileToken of fileTokens) {
+            let letter = null;
+            try {
+                letter = readClaimedLetter(root, me, claimToken, fileToken);
+            }
+            catch {
+                // transient read failure — keep it claimed rather than discarding
+                continue;
+            }
+            if (!letter || deliveredIds.has(letter.id)) {
+                // corrupt letters are discarded like drain does; already-accepted
+                // letters are redeliveries (crash between delivery and ack)
+                ack(fileToken);
+                continue;
+            }
             let accepted = false;
             try {
                 accepted = deliver(letter);
             }
             catch {
-                // a malformed delivery never blocks the rest of the drain
+                // a malformed delivery never blocks the rest of the claim
+            }
+            if (accepted) {
+                noteDelivered(letter.id);
+                ack(fileToken);
             }
-            if (!accepted) {
+            else {
                 lastDeliveryFailureAt = Date.now();
-                // Not handed to the session — put the letter back so a future drain
-                // retries it; otherwise drain's unlink-as-read would silently lose it
-                // while the sender's receipt reported "delivered".
+                // Not handed to the session — atomically return it to the live inbox
+                // so the watch/poll retries it.
                 try {
-                    deposit(root, self.addr, letter);
+                    requeueClaimedLetter(root, me, claimToken, fileToken);
                 }
                 catch {
-                    // inbox dir unwritable; nothing more we can do
+                    // stays claimed; the next session_start recovers it
                 }
             }
         }
+        // claimInbox renamed the watched inbox dir away and created a fresh one,
+        // so the fs.watch is now on a detached directory. Re-arm on the live
+        // inbox (the 3s poll covers anything deposited in between).
+        try {
+            unwatch?.();
+            unwatch = watchInbox(root, me, checkInbox);
+        }
+        catch {
+            // watch failure is non-fatal; the old poll timer died with the old watch
+        }
     }
     function myFrom() {
         const s = self;
@@ -363,6 +428,29 @@ export default function relay(pi) {
             writeRecord(root, self);
             const resumable = collectResumableSessionIds();
             sweep(root, Date.now(), (id) => resumable.has(id));
+            // Seed redelivery dedupe from the transcript: a letter delivered by a
+            // previous process but never acked (crash between delivery and ack)
+            // will be recovered below and must not be handed to the model twice.
+            for (const entry of ctx.sessionManager.getEntries()) {
+                if (entry.type !== 'custom_message' || entry.customType !== DELIVERY_TYPE)
+                    continue;
+                const id = entry.details?.id;
+                if (typeof id === 'string')
+                    noteDelivered(id);
+            }
+            // Recover letters stranded in durable claims by a crash mid-delivery:
+            // return them to the live inbox so the normal watch/poll retries them.
+            // Runs before the watch is armed so requeues land in the watched inbox.
+            for (const stranded of recoverInboxClaims(root, self.addr)) {
+                for (const fileToken of stranded.fileTokens) {
+                    try {
+                        requeueClaimedLetter(root, self.addr, stranded.claimToken, fileToken);
+                    }
+                    catch {
+                        // stays claimed; the next session_start retries recovery
+                    }
+                }
+            }
             unwatch?.();
             unwatch = watchInbox(root, self.addr, checkInbox);
             heartbeat = setInterval(() => writeSelf({}), 15_000);

package/dist/mailbox.d.ts

@@ -4,11 +4,13 @@
  * Guarantees (each pinned by a test):
  * - A reader never sees half a letter: writers rename into place; readers
  *   only look at `*.json`.
- * - Nothing is delivered twice: a letter is unlinked as it is read, BEFORE
- *   the caller handles it.
+ * - A letter is deleted only once consumed: drain unlinks as it reads, and
+ *   the durable claim flow deletes only on explicit ack — a crashed or
+ *   failed delivery leaves the letter recoverable (recoverInboxClaims) or
+ *   requeueable.
  * - A corrupt letter is discarded on read, so it cannot poison every drain.
  * - Consumption is the receipt: the sender learns "delivered" only when the
- *   letter actually disappeared from the target's inbox.
+ *   letter actually disappeared from the target's inbox and durable claims.
  * - Every deposit and every delivery appends one append-only audit line —
  *   drain-as-receipt must not destroy evidence. The log never holds a full
  *   body, only a short preview.
@@ -32,8 +34,12 @@ export declare function deposit(root: string, toAddr: string, letter: Letter): v
 /**
  * Take every letter in the inbox, oldest first. Each letter is unlinked as
  * it is read — before parsing — so it can never be delivered twice. The
- * tradeoff: a drained letter that is never delivered would be lost, so the
- * caller must re-deposit any letter it fails to deliver (checkInbox does).
+ * tradeoff: a drained letter that is never delivered is lost, so callers
+ * that can fail delivery should prefer the durable claim flow (claimInbox →
+ * readClaimedLetter → ackClaimedLetter/requeueClaimedLetter), which only
+ * deletes a letter once it has actually been handed off. The pi entry point
+ * (index.ts checkInbox) uses claims; drain remains for core consumers that
+ * handle drained letters synchronously.
  */
 export declare function drain(root: string, addr: string): Letter[];
 export declare function unreadCount(root: string, addr: string): number;

package/dist/mailbox.js

@@ -4,11 +4,13 @@
  * Guarantees (each pinned by a test):
  * - A reader never sees half a letter: writers rename into place; readers
  *   only look at `*.json`.
- * - Nothing is delivered twice: a letter is unlinked as it is read, BEFORE
- *   the caller handles it.
+ * - A letter is deleted only once consumed: drain unlinks as it reads, and
+ *   the durable claim flow deletes only on explicit ack — a crashed or
+ *   failed delivery leaves the letter recoverable (recoverInboxClaims) or
+ *   requeueable.
  * - A corrupt letter is discarded on read, so it cannot poison every drain.
  * - Consumption is the receipt: the sender learns "delivered" only when the
- *   letter actually disappeared from the target's inbox.
+ *   letter actually disappeared from the target's inbox and durable claims.
  * - Every deposit and every delivery appends one append-only audit line —
  *   drain-as-receipt must not destroy evidence. The log never holds a full
  *   body, only a short preview.
@@ -80,8 +82,12 @@ export function deposit(root, toAddr, letter) {
 /**
  * Take every letter in the inbox, oldest first. Each letter is unlinked as
  * it is read — before parsing — so it can never be delivered twice. The
- * tradeoff: a drained letter that is never delivered would be lost, so the
- * caller must re-deposit any letter it fails to deliver (checkInbox does).
+ * tradeoff: a drained letter that is never delivered is lost, so callers
+ * that can fail delivery should prefer the durable claim flow (claimInbox →
+ * readClaimedLetter → ackClaimedLetter/requeueClaimedLetter), which only
+ * deletes a letter once it has actually been handed off. The pi entry point
+ * (index.ts checkInbox) uses claims; drain remains for core consumers that
+ * handle drained letters synchronously.
  */
 export function drain(root, addr) {
     assertPathSegment(addr, 'relay address');

package/dist/relay.test.js

@@ -8,7 +8,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { afterEach, describe, expect, it } from 'vitest';
 import { BOUNDARY_PREAMBLE, formatAudit, formatDelivery, formatListing, refusalAmbiguous, refusalUnknown, } from './format.js';
-import { appendAudit, auditLogPath, awaitReceipt, claimInbox, clearAsk, deposit, drain, pendingAsks, previewBody, readAudit, readIncomingAsk, readOutgoingAsk, recoverInboxClaims, resolveAskByRef, trackIncomingAsk, trackOutgoingAsk, unreadCount, watchInbox, } from './mailbox.js';
+import { ackClaimedLetter, appendAudit, auditLogPath, awaitReceipt, claimInbox, clearAsk, deposit, drain, pendingAsks, previewBody, readAudit, readClaimedLetter, readIncomingAsk, readOutgoingAsk, recoverInboxClaims, requeueClaimedLetter, resolveAskByRef, trackIncomingAsk, trackOutgoingAsk, unreadCount, watchInbox, } from './mailbox.js';
 import { BACKLOG_CAP, OutboundPolicy, inboundAccepts } from './policy.js';
 import { claimAlias, clearAlias, deriveAddr, isValidAliasName, listAliases, listRecords, presenceOf, readAlias, readRecord, sweep, writeAlias, writeRecord, } from './registry.js';
 const require = createRequire(import.meta.url);
@@ -191,6 +191,34 @@ describe('mailbox', () => {
         deposit(root, addr, l2);
         expect(await awaitReceipt(root, addr, l2, 400)).toBe('queued');
     });
+    it("a letter reads 'queued' to the sender until actually delivered (claim → fail → requeue → ack)", async () => {
+        // The pi entry point's delivery flow: a claimed letter stays 'queued' to
+        // the sender, a failed delivery returns it to the inbox for retry, and
+        // the receipt flips to 'delivered' only after acceptance (ack). A crash
+        // mid-claim leaves the letter recoverable instead of silently lost.
+        const root = tmpRoot();
+        const addr = 'inbox0000004';
+        const l1 = letter({ id: 'rcpt-3', ts: Date.now() });
+        deposit(root, addr, l1);
+        const claim = claimInbox(root, addr);
+        expect(claim.fileTokens).toHaveLength(1);
+        // Claimed but not yet delivered: the sender must NOT see 'delivered'.
+        expect(await awaitReceipt(root, addr, l1, 400)).toBe('queued');
+        expect(readClaimedLetter(root, addr, claim.claimToken, claim.fileTokens[0])?.id).toBe(l1.id);
+        // Delivery failure: requeue returns the letter to the live inbox, and a
+        // later claim picks it up again.
+        expect(requeueClaimedLetter(root, addr, claim.claimToken, claim.fileTokens[0])).toBe(true);
+        expect(unreadCount(root, addr)).toBe(1);
+        expect(recoverInboxClaims(root, addr)).toEqual([]);
+        const retry = claimInbox(root, addr);
+        expect(retry.fileTokens).toEqual(claim.fileTokens);
+        // Crash after delivery but before ack: the letter is recoverable.
+        expect(recoverInboxClaims(root, addr)).toEqual([retry]);
+        // Acceptance: only the ack deletes the letter and flips the receipt.
+        expect(ackClaimedLetter(root, addr, retry.claimToken, retry.fileTokens[0])).toBe(true);
+        expect(recoverInboxClaims(root, addr)).toEqual([]);
+        expect(await awaitReceipt(root, addr, l1, 400)).toBe('delivered');
+    });
     it('watch fires on deposit (poll fallback covers missed events)', async () => {
         const root = tmpRoot();
         const addr = 'inbox0000004';

package/index.ts

@@ -29,16 +29,20 @@ import {
   shortAddr,
 } from './format.js';
 import {
+  ackClaimedLetter,
   appendAudit,
   awaitReceipt,
+  claimInbox,
   clearAsk,
-  drain,
   deposit,
   outgoingAskIds,
   pendingAsks,
   previewBody,
   readAudit,
+  readClaimedLetter,
   readOutgoingAsk,
+  recoverInboxClaims,
+  requeueClaimedLetter,
   resolveAskByRef,
   trackIncomingAsk,
   trackOutgoingAsk,
@@ -169,10 +173,22 @@ export default function relay(pi: ExtensionAPI) {
   let unwatch: (() => void) | undefined;
   let heartbeat: ReturnType<typeof setInterval> | undefined;
   const askWaiters = new Map<string, (outcome: AskOutcome) => void>();
-  // Backoff while the session can't accept mail: a re-deposited letter
+  // Backoff while the session can't accept mail: a requeued letter
   // re-fires the watcher, and without this a failing sendMessage would spin
-  // drain→fail→re-deposit at watch speed.
+  // claim→fail→requeue at watch speed.
   let lastDeliveryFailureAt = 0;
+  // Letter ids this session has already accepted. Claims make redelivery
+  // possible (a crash between delivery and ack, or an ack failure after a
+  // successful send); without dedupe the model would see the body twice.
+  // Seeded from the transcript on session_start so recovery after a crash
+  // doesn't redeliver what the previous process already handed to the agent.
+  const deliveredIds = new Set<string>();
+  const DELIVERED_IDS_CAP = 512;
+  const noteDelivered = (id: string): void => {
+    deliveredIds.delete(id); // refresh recency
+    deliveredIds.add(id);
+    if (deliveredIds.size > DELIVERED_IDS_CAP) deliveredIds.delete(deliveredIds.values().next().value!);
+  };
   // Presence watch: addr → last observed presence. A poller surfaces
   // transitions as a notification message (no full turn wake).
   const watched = new Map<string, Presence>();
@@ -192,7 +208,13 @@ export default function relay(pi: ExtensionAPI) {
   function deliver(letter: Letter): boolean {
     // Audited after the delivery attempts below: a 'deliver' record means the
     // session actually accepted the letter; refusal records 'deliver-failed'
-    // (the caller re-deposits, so logging here would duplicate every retry).
+    // (the caller requeues, so logging here would duplicate every retry).
+    // Note pi.sendMessage is fire-and-forget: asynchronous failures are
+    // swallowed by the runtime (emitted as extension errors, never rethrown),
+    // so only synchronous refusals — a disposed/uninitialized runtime during
+    // reload or shutdown — reach these catches. That is exactly the case
+    // where the letter never enters the transcript: async rejections from the
+    // triggerTurn path happen after the message is already in context.
     const auditDelivery = (event: 'deliver' | 'deliver-failed') =>
       appendAudit(root, {
         ts: Date.now(),
@@ -255,7 +277,7 @@ export default function relay(pi: ExtensionAPI) {
           return true;
         } catch {
           // session is shutting down or otherwise undeliverable — the caller
-          // re-deposits the letter so a future drain retries
+          // requeues the letter so a future drain retries
           auditDelivery('deliver-failed');
           return false;
         }
@@ -265,35 +287,76 @@ export default function relay(pi: ExtensionAPI) {
 
   function checkInbox(): void {
     if (!self) return;
+    const me = self.addr;
     if (Date.now() - lastDeliveryFailureAt < 5000) return;
-    // Refuse mode: never drain. Letters stay on disk (receipts honestly read
+    // Refuse mode: never claim. Letters stay on disk (receipts honestly read
     // 'queued') instead of being silently consumed and dropped.
     if (!inboundAccepts()) return;
-    let letters: Letter[];
+    // Claim, not drain: the inbox is detached atomically and each letter is
+    // only acked (deleted) once the session has accepted it. A claimed but
+    // unacked letter still reads 'queued' to the sender's receipt, survives
+    // a crash (recoverInboxClaims on the next session_start), and can be
+    // requeued for retry — unlink-as-read could silently lose it while the
+    // sender's receipt reported "delivered".
+    let claim: ReturnType<typeof claimInbox>;
     try {
-      letters = drain(root, self.addr);
+      claim = claimInbox(root, me);
     } catch {
       return;
     }
-    for (const letter of letters) {
+    if (!claim) return;
+    const { claimToken, fileTokens } = claim;
+    const ack = (fileToken: string) => {
+      try {
+        ackClaimedLetter(root, me, claimToken, fileToken);
+      } catch {
+        // ack failure leaves the letter claimed; recovery requeues it and
+        // deliveredIds suppresses the duplicate
+      }
+    };
+    for (const fileToken of fileTokens) {
+      let letter: Letter | null = null;
+      try {
+        letter = readClaimedLetter(root, me, claimToken, fileToken);
+      } catch {
+        // transient read failure — keep it claimed rather than discarding
+        continue;
+      }
+      if (!letter || deliveredIds.has(letter.id)) {
+        // corrupt letters are discarded like drain does; already-accepted
+        // letters are redeliveries (crash between delivery and ack)
+        ack(fileToken);
+        continue;
+      }
       let accepted = false;
       try {
         accepted = deliver(letter);
       } catch {
-        // a malformed delivery never blocks the rest of the drain
+        // a malformed delivery never blocks the rest of the claim
       }
-      if (!accepted) {
+      if (accepted) {
+        noteDelivered(letter.id);
+        ack(fileToken);
+      } else {
         lastDeliveryFailureAt = Date.now();
-        // Not handed to the session — put the letter back so a future drain
-        // retries it; otherwise drain's unlink-as-read would silently lose it
-        // while the sender's receipt reported "delivered".
+        // Not handed to the session — atomically return it to the live inbox
+        // so the watch/poll retries it.
         try {
-          deposit(root, self.addr, letter);
+          requeueClaimedLetter(root, me, claimToken, fileToken);
         } catch {
-          // inbox dir unwritable; nothing more we can do
+          // stays claimed; the next session_start recovers it
         }
       }
     }
+    // claimInbox renamed the watched inbox dir away and created a fresh one,
+    // so the fs.watch is now on a detached directory. Re-arm on the live
+    // inbox (the 3s poll covers anything deposited in between).
+    try {
+      unwatch?.();
+      unwatch = watchInbox(root, me, checkInbox);
+    } catch {
+      // watch failure is non-fatal; the old poll timer died with the old watch
+    }
   }
 
   function myFrom(): { addr: string; name: string; cwd: string } {
@@ -432,6 +495,26 @@ export default function relay(pi: ExtensionAPI) {
       writeRecord(root, self);
       const resumable = collectResumableSessionIds();
       sweep(root, Date.now(), (id) => resumable.has(id));
+      // Seed redelivery dedupe from the transcript: a letter delivered by a
+      // previous process but never acked (crash between delivery and ack)
+      // will be recovered below and must not be handed to the model twice.
+      for (const entry of ctx.sessionManager.getEntries()) {
+        if (entry.type !== 'custom_message' || entry.customType !== DELIVERY_TYPE) continue;
+        const id = (entry.details as { id?: unknown } | undefined)?.id;
+        if (typeof id === 'string') noteDelivered(id);
+      }
+      // Recover letters stranded in durable claims by a crash mid-delivery:
+      // return them to the live inbox so the normal watch/poll retries them.
+      // Runs before the watch is armed so requeues land in the watched inbox.
+      for (const stranded of recoverInboxClaims(root, self.addr)) {
+        for (const fileToken of stranded.fileTokens) {
+          try {
+            requeueClaimedLetter(root, self.addr, stranded.claimToken, fileToken);
+          } catch {
+            // stays claimed; the next session_start retries recovery
+          }
+        }
+      }
       unwatch?.();
       unwatch = watchInbox(root, self.addr, checkInbox);
       heartbeat = setInterval(() => writeSelf({}), 15_000);

package/mailbox.ts

@@ -4,11 +4,13 @@
  * Guarantees (each pinned by a test):
  * - A reader never sees half a letter: writers rename into place; readers
  *   only look at `*.json`.
- * - Nothing is delivered twice: a letter is unlinked as it is read, BEFORE
- *   the caller handles it.
+ * - A letter is deleted only once consumed: drain unlinks as it reads, and
+ *   the durable claim flow deletes only on explicit ack — a crashed or
+ *   failed delivery leaves the letter recoverable (recoverInboxClaims) or
+ *   requeueable.
  * - A corrupt letter is discarded on read, so it cannot poison every drain.
  * - Consumption is the receipt: the sender learns "delivered" only when the
- *   letter actually disappeared from the target's inbox.
+ *   letter actually disappeared from the target's inbox and durable claims.
  * - Every deposit and every delivery appends one append-only audit line —
  *   drain-as-receipt must not destroy evidence. The log never holds a full
  *   body, only a short preview.
@@ -103,8 +105,12 @@ export function deposit(root: string, toAddr: string, letter: Letter): void {
 /**
  * Take every letter in the inbox, oldest first. Each letter is unlinked as
  * it is read — before parsing — so it can never be delivered twice. The
- * tradeoff: a drained letter that is never delivered would be lost, so the
- * caller must re-deposit any letter it fails to deliver (checkInbox does).
+ * tradeoff: a drained letter that is never delivered is lost, so callers
+ * that can fail delivery should prefer the durable claim flow (claimInbox →
+ * readClaimedLetter → ackClaimedLetter/requeueClaimedLetter), which only
+ * deletes a letter once it has actually been handed off. The pi entry point
+ * (index.ts checkInbox) uses claims; drain remains for core consumers that
+ * handle drained letters synchronously.
  */
 export function drain(root: string, addr: string): Letter[] {
   assertPathSegment(addr, 'relay address');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nicknisi/pi-relay",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Brokerless session-to-session messaging for pi — a file mailbox that outlives the process, with ask/reply coordination. Formerly @nicknisi/pi-intercom.",
   "keywords": [
     "pi",