@nicknisi/pi-relay 0.3.0 → 0.3.2

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,9 +18,15 @@ 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';
+import { claimAlias, deriveAddr, ensureRoot, resolveRelayRoot, isValidAliasName, listAliases, listRecords, presenceOf, readAlias, readRecord, sweep, writeRecord, } from './registry.js';
+/** What to tell the caller when there is no session record to work with. */
+function describeUninitialized(startupError, root) {
+    return startupError
+        ? `Relay failed to start: ${startupError} (relay root: ${root})`
+        : 'Relay is not initialized (no session_start yet).';
+}
 function toolResult(text, details = {}) {
     return { content: [{ type: 'text', text }], details };
 }
@@ -93,16 +99,38 @@ function collectResumableSessionIds() {
     return ids;
 }
 export default function relay(pi) {
-    const root = process.env.PI_RELAY_DIR ?? path.join(getAgentDir(), 'relay');
+    // Resolve before any relay I/O: pi's home is commonly a dotfiles symlink,
+    // and the traversal hardening (rightly) refuses user-controlled ancestor
+    // symlinks on every operation. See resolveRelayRoot.
+    const root = resolveRelayRoot(process.env.PI_RELAY_DIR ?? path.join(getAgentDir(), 'relay'));
     const policy = new OutboundPolicy();
     let self;
+    // Why registration failed, if it did. Without this a startup failure is
+    // indistinguishable from "session_start hasn't fired yet", and the whole
+    // extension goes quietly inert -- which is exactly how a symlinked pi home
+    // disabled relay machine-wide for a day and a half before anyone noticed.
+    let startupError;
+    const uninitializedText = () => describeUninitialized(startupError, root);
     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 +150,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 +220,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 +230,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;
@@ -346,6 +426,7 @@ export default function relay(pi) {
     }
     pi.on('session_start', (_event, ctx) => {
         try {
+            startupError = undefined;
             ensureRoot(root);
             const sessionId = ctx.sessionManager.getSessionId();
             const cwd = ctx.sessionManager.getCwd() ?? ctx.cwd;
@@ -363,6 +444,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);
@@ -373,8 +477,11 @@ export default function relay(pi) {
             const initialDrain = setTimeout(checkInbox, 1200);
             initialDrain.unref();
         }
-        catch {
-            // registration failure never breaks the session
+        catch (error) {
+            // A failure here must never break the session -- but it must not be
+            // invisible either. Record it so every tool can say what actually
+            // happened instead of implying session_start simply hasn't run.
+            startupError = error instanceof Error ? error.message : String(error);
         }
     });
     pi.on('agent_start', () => writeSelf({ status: 'working' }));
@@ -427,7 +534,7 @@ export default function relay(pi) {
         }),
         async execute(_toolCallId, params, signal, _onUpdate, ctx) {
             if (!self)
-                return toolResult('Relay is not initialized (no session_start yet).');
+                return toolResult(uninitializedText());
             switch (params.action) {
                 case 'list':
                     return toolResult(formatListing(listRecords(root), self.addr, (r) => presenceOf(r)));
@@ -660,7 +767,7 @@ export default function relay(pi) {
             if (sub === 'log') {
                 const limit = Math.max(1, Math.min(500, Number(rest[0] ?? 50)));
                 const entries = self ? readAudit(root, limit) : [];
-                const text = self ? formatAudit(entries) : 'Relay is not initialized (no session_start yet).';
+                const text = self ? formatAudit(entries) : uninitializedText();
                 if (!self || !ctx.hasUI) {
                     pi.sendMessage({ customType: AUDIT_TYPE, content: text, display: true, details: { kind: 'relay-audit' } });
                     return;
@@ -670,9 +777,7 @@ export default function relay(pi) {
             }
             if (!self || !ctx.hasUI) {
                 // Plain-text fallback (print/rpc mode): the entry renderer never runs there.
-                const text = self
-                    ? formatListing(listRecords(root), self.addr, (r) => presenceOf(r))
-                    : 'Relay is not initialized (no session_start yet).';
+                const text = self ? formatListing(listRecords(root), self.addr, (r) => presenceOf(r)) : uninitializedText();
                 pi.sendMessage({
                     customType: LIST_TYPE,
                     content: text,

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/registry.d.ts

@@ -30,6 +30,25 @@ export declare const HEARTBEAT_STALE_MS = 45000;
 /** A mailbox holding undelivered mail is kept this long after last contact. */
 export declare const SWEEP_MAIL_KEEP_MS: number;
 export declare function deriveAddr(cwd: string, sessionId: string): string;
+/**
+ * Pin the relay root to its real location, once, before any relay I/O.
+ *
+ * The traversal hardening refuses *user-controlled* ancestor symlinks, because
+ * a user-writable symlink can be swapped between the check and the use. That
+ * is the right rule for every operation after startup — but it also rejects a
+ * legitimate, stable arrangement: a dotfiles setup where `~/.pi` is a symlink
+ * into a managed repo. Since pi keeps everything under `~/.pi`, that made the
+ * relay root unopenable and the whole extension silently inert.
+ *
+ * Resolving once at startup keeps the property that matters. Every later
+ * operation traverses only real directories, so there is no user symlink left
+ * in the path to swap; repointing `~/.pi` afterwards cannot redirect this
+ * process. It is a pin, not a bypass.
+ *
+ * The root may not exist yet on a first run, so resolve the deepest ancestor
+ * that does and re-apply the remainder.
+ */
+export declare function resolveRelayRoot(root: string): string;
 export declare function ensureRoot(root: string): void;
 export declare function recordPath(root: string, addr: string): string;
 export declare function inboxDir(root: string, addr: string): string;

package/dist/registry.js

@@ -15,6 +15,7 @@
  * - Listing has NO side effects: reading the directory never deletes.
  */
 import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { assertPathSegment, openRelayRoot, rethrowFilesystemError, RelayDirectoryHandle, RelayFilesystemError, } from './filesystem.js';
 export const HEARTBEAT_STALE_MS = 45_000;
@@ -23,6 +24,44 @@ export const SWEEP_MAIL_KEEP_MS = 30 * 24 * 60 * 60 * 1000;
 export function deriveAddr(cwd, sessionId) {
     return crypto.createHash('sha256').update(`${cwd}${sessionId}`).digest('hex').slice(0, 12);
 }
+/**
+ * Pin the relay root to its real location, once, before any relay I/O.
+ *
+ * The traversal hardening refuses *user-controlled* ancestor symlinks, because
+ * a user-writable symlink can be swapped between the check and the use. That
+ * is the right rule for every operation after startup — but it also rejects a
+ * legitimate, stable arrangement: a dotfiles setup where `~/.pi` is a symlink
+ * into a managed repo. Since pi keeps everything under `~/.pi`, that made the
+ * relay root unopenable and the whole extension silently inert.
+ *
+ * Resolving once at startup keeps the property that matters. Every later
+ * operation traverses only real directories, so there is no user symlink left
+ * in the path to swap; repointing `~/.pi` afterwards cannot redirect this
+ * process. It is a pin, not a bypass.
+ *
+ * The root may not exist yet on a first run, so resolve the deepest ancestor
+ * that does and re-apply the remainder.
+ */
+export function resolveRelayRoot(root) {
+    const absolute = path.resolve(root);
+    const tail = [];
+    let current = absolute;
+    for (;;) {
+        try {
+            return path.join(fs.realpathSync(current), ...tail);
+        }
+        catch (error) {
+            if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
+                throw error;
+            const parent = path.dirname(current);
+            // Filesystem root does not exist: nothing sane left to resolve against.
+            if (parent === current)
+                return absolute;
+            tail.unshift(path.basename(current));
+            current = parent;
+        }
+    }
+}
 export function ensureRoot(root) {
     const directory = openRelayRoot(root, true);
     directory.close();

package/dist/relay.test.js

@@ -8,9 +8,9 @@ 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';
+import { claimAlias, clearAlias, deriveAddr, ensureRoot, resolveRelayRoot, isValidAliasName, listAliases, listRecords, presenceOf, readAlias, readRecord, sweep, writeAlias, writeRecord, } from './registry.js';
 const require = createRequire(import.meta.url);
 const dirs = [];
 function tmpRoot() {
@@ -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';
@@ -587,3 +615,35 @@ describe('format', () => {
         expect(refusalAmbiguous('al', ['"alpha" (aaaa11)', '"alpine" (bbbb22)'])).toContain('ambiguous');
     });
 });
+describe('relay root resolution', () => {
+    // pi's home is commonly a dotfiles symlink (`~/.pi -> ~/Developer/dotfiles/home/.pi`).
+    // The traversal hardening refuses user-controlled ancestor symlinks, so an
+    // unresolved root made every relay operation throw -- and because
+    // session_start swallowed it, relay went silently inert machine-wide.
+    // Note the rest of this suite calls fs.realpathSync.native() on its temp
+    // dirs, which is exactly why that path was never covered.
+    it('resolves a user-symlinked ancestor so the hardened root can be opened', () => {
+        const real = tmpRoot();
+        const link = path.join(tmpRoot(), 'link');
+        fs.symlinkSync(real, link, 'dir');
+        const root = path.join(link, 'relay');
+        // The hardening rejects the symlinked path itself -- deliberately.
+        expect(() => ensureRoot(root)).toThrow(/symlink/i);
+        // Resolving first yields the same directory by its real path, which opens.
+        const resolved = resolveRelayRoot(root);
+        expect(resolved).toBe(path.join(real, 'relay'));
+        expect(() => ensureRoot(resolved)).not.toThrow();
+    });
+    it('resolves a root whose directories do not exist yet', () => {
+        const real = tmpRoot();
+        const link = path.join(tmpRoot(), 'link');
+        fs.symlinkSync(real, link, 'dir');
+        // First run: nothing under the root exists, so the deepest existing
+        // ancestor is resolved and the missing tail re-applied.
+        expect(resolveRelayRoot(path.join(link, 'a', 'b', 'relay'))).toBe(path.join(real, 'a', 'b', 'relay'));
+    });
+    it('leaves an already-real path unchanged', () => {
+        const real = tmpRoot();
+        expect(resolveRelayRoot(path.join(real, 'relay'))).toBe(path.join(real, 'relay'));
+    });
+});

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,
@@ -51,6 +55,7 @@ import {
   claimAlias,
   deriveAddr,
   ensureRoot,
+  resolveRelayRoot,
   isValidAliasName,
   listAliases,
   listRecords,
@@ -65,6 +70,13 @@ import {
 
 type AskOutcome = { replied: true; body: string; from: string } | { replied: false; reason: string };
 
+/** What to tell the caller when there is no session record to work with. */
+function describeUninitialized(startupError: string | undefined, root: string): string {
+  return startupError
+    ? `Relay failed to start: ${startupError} (relay root: ${root})`
+    : 'Relay is not initialized (no session_start yet).';
+}
+
 function toolResult(text: string, details: Record<string, unknown> = {}) {
   return { content: [{ type: 'text' as const, text }], details };
 }
@@ -162,17 +174,38 @@ function collectResumableSessionIds(): Set<string> {
 }
 
 export default function relay(pi: ExtensionAPI) {
-  const root = process.env.PI_RELAY_DIR ?? path.join(getAgentDir(), 'relay');
+  // Resolve before any relay I/O: pi's home is commonly a dotfiles symlink,
+  // and the traversal hardening (rightly) refuses user-controlled ancestor
+  // symlinks on every operation. See resolveRelayRoot.
+  const root = resolveRelayRoot(process.env.PI_RELAY_DIR ?? path.join(getAgentDir(), 'relay'));
   const policy = new OutboundPolicy();
 
   let self: SessionRecord | undefined;
+  // Why registration failed, if it did. Without this a startup failure is
+  // indistinguishable from "session_start hasn't fired yet", and the whole
+  // extension goes quietly inert -- which is exactly how a symlinked pi home
+  // disabled relay machine-wide for a day and a half before anyone noticed.
+  let startupError: string | undefined;
+  const uninitializedText = (): string => describeUninitialized(startupError, root);
   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 +225,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 +294,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 +304,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 } {
@@ -415,6 +495,7 @@ export default function relay(pi: ExtensionAPI) {
 
   pi.on('session_start', (_event, ctx: ExtensionContext) => {
     try {
+      startupError = undefined;
       ensureRoot(root);
       const sessionId = ctx.sessionManager.getSessionId();
       const cwd = ctx.sessionManager.getCwd() ?? ctx.cwd;
@@ -432,6 +513,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);
@@ -441,8 +542,11 @@ export default function relay(pi: ExtensionAPI) {
       // processing"); by the time this fires, steer/triggerTurn work.
       const initialDrain = setTimeout(checkInbox, 1200);
       initialDrain.unref();
-    } catch {
-      // registration failure never breaks the session
+    } catch (error) {
+      // A failure here must never break the session -- but it must not be
+      // invisible either. Record it so every tool can say what actually
+      // happened instead of implying session_start simply hasn't run.
+      startupError = error instanceof Error ? error.message : String(error);
     }
   });
 
@@ -505,7 +609,7 @@ export default function relay(pi: ExtensionAPI) {
     }),
 
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-      if (!self) return toolResult('Relay is not initialized (no session_start yet).');
+      if (!self) return toolResult(uninitializedText());
 
       switch (params.action) {
         case 'list':
@@ -740,7 +844,7 @@ export default function relay(pi: ExtensionAPI) {
       if (sub === 'log') {
         const limit = Math.max(1, Math.min(500, Number(rest[0] ?? 50)));
         const entries = self ? readAudit(root, limit) : [];
-        const text = self ? formatAudit(entries) : 'Relay is not initialized (no session_start yet).';
+        const text = self ? formatAudit(entries) : uninitializedText();
         if (!self || !ctx.hasUI) {
           pi.sendMessage({ customType: AUDIT_TYPE, content: text, display: true, details: { kind: 'relay-audit' } });
           return;
@@ -750,9 +854,7 @@ export default function relay(pi: ExtensionAPI) {
       }
       if (!self || !ctx.hasUI) {
         // Plain-text fallback (print/rpc mode): the entry renderer never runs there.
-        const text = self
-          ? formatListing(listRecords(root), self.addr, (r) => presenceOf(r))
-          : 'Relay is not initialized (no session_start yet).';
+        const text = self ? formatListing(listRecords(root), self.addr, (r) => presenceOf(r)) : uninitializedText();
         pi.sendMessage({
           customType: LIST_TYPE,
           content: text,

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.2",
   "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",

package/registry.ts

@@ -16,6 +16,7 @@
  */
 
 import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {
   assertPathSegment,
@@ -47,6 +48,42 @@ export function deriveAddr(cwd: string, sessionId: string): string {
   return crypto.createHash('sha256').update(`${cwd}${sessionId}`).digest('hex').slice(0, 12);
 }
 
+/**
+ * Pin the relay root to its real location, once, before any relay I/O.
+ *
+ * The traversal hardening refuses *user-controlled* ancestor symlinks, because
+ * a user-writable symlink can be swapped between the check and the use. That
+ * is the right rule for every operation after startup — but it also rejects a
+ * legitimate, stable arrangement: a dotfiles setup where `~/.pi` is a symlink
+ * into a managed repo. Since pi keeps everything under `~/.pi`, that made the
+ * relay root unopenable and the whole extension silently inert.
+ *
+ * Resolving once at startup keeps the property that matters. Every later
+ * operation traverses only real directories, so there is no user symlink left
+ * in the path to swap; repointing `~/.pi` afterwards cannot redirect this
+ * process. It is a pin, not a bypass.
+ *
+ * The root may not exist yet on a first run, so resolve the deepest ancestor
+ * that does and re-apply the remainder.
+ */
+export function resolveRelayRoot(root: string): string {
+  const absolute = path.resolve(root);
+  const tail: string[] = [];
+  let current = absolute;
+  for (;;) {
+    try {
+      return path.join(fs.realpathSync(current), ...tail);
+    } catch (error) {
+      if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) throw error;
+      const parent = path.dirname(current);
+      // Filesystem root does not exist: nothing sane left to resolve against.
+      if (parent === current) return absolute;
+      tail.unshift(path.basename(current));
+      current = parent;
+    }
+  }
+}
+
 export function ensureRoot(root: string): void {
   const directory = openRelayRoot(root, true)!;
   directory.close();