@nicknisi/pi-relay 0.2.0 → 0.3.0

package/dist/registry.js

@@ -15,8 +15,8 @@
  * - 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;
 /** A mailbox holding undelivered mail is kept this long after last contact. */
 export const SWEEP_MAIL_KEEP_MS = 30 * 24 * 60 * 60 * 1000;
@@ -24,73 +24,124 @@ export function deriveAddr(cwd, sessionId) {
     return crypto.createHash('sha256').update(`${cwd}${sessionId}`).digest('hex').slice(0, 12);
 }
 export function ensureRoot(root) {
-    fs.mkdirSync(root, { recursive: true, mode: 0o700 });
-    try {
-        fs.chmodSync(root, 0o700);
-    }
-    catch {
-        // best-effort on filesystems that support modes
-    }
+    const directory = openRelayRoot(root, true);
+    directory.close();
 }
 export function recordPath(root, addr) {
+    assertPathSegment(addr, 'relay address');
     return path.join(root, `${addr}.json`);
 }
 export function inboxDir(root, addr) {
+    assertPathSegment(addr, 'relay address');
     return path.join(root, `${addr}.inbox`);
 }
 export function asksDir(root, addr) {
+    assertPathSegment(addr, 'relay address');
     return path.join(root, `${addr}.asks`);
 }
 export function aliasesDir(root) {
     return path.join(root, 'aliases');
 }
 export function aliasPath(root, name) {
+    assertPathSegment(name, 'relay alias');
     return path.join(aliasesDir(root), `${name}.json`);
 }
 export function writeAlias(root, alias) {
-    const file = aliasPath(root, alias.name);
-    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
-    const tmp = `${file}.${process.pid}.tmp`;
-    fs.writeFileSync(tmp, JSON.stringify(alias, null, 2), { mode: 0o600 });
-    fs.renameSync(tmp, file);
+    if (!isValidAliasName(alias.name))
+        throw new TypeError(`Invalid relay alias: ${alias.name}`);
+    const relay = openRelayRoot(root, true);
+    try {
+        const aliases = relay.openDirectory('aliases', true);
+        try {
+            aliases.writeFileAtomic(`${alias.name}.json`, JSON.stringify(alias, null, 2));
+        }
+        finally {
+            aliases.close();
+        }
+    }
+    finally {
+        relay.close();
+    }
 }
 /** Alias names: lowercase alnum start, then alnum/_/-, 1-32 chars. */
 export function isValidAliasName(name) {
     return /^[a-z0-9][a-z0-9_-]{0,31}$/.test(name);
 }
+function readAliasFromDirectory(directory, name) {
+    const raw = directory.readFile(`${name}.json`);
+    if (raw === null)
+        return null;
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.name === 'string' && typeof parsed.addr === 'string')
+        return parsed;
+    return null;
+}
 export function readAlias(root, name) {
     // The name can come from LLM-controlled tool input — never let it reach
     // the filesystem unvalidated (e.g. '@../../../../tmp/x').
     if (!isValidAliasName(name))
         return null;
+    const relay = openRelayRoot(root);
+    if (relay === null)
+        return null;
     try {
-        const parsed = JSON.parse(fs.readFileSync(aliasPath(root, name), 'utf8'));
-        if (parsed && typeof parsed.name === 'string' && typeof parsed.addr === 'string') {
-            return parsed;
+        const aliases = relay.openDirectory('aliases');
+        if (aliases === null)
+            return null;
+        try {
+            return readAliasFromDirectory(aliases, name);
+        }
+        catch (error) {
+            rethrowFilesystemError(error);
+            return null;
+        }
+        finally {
+            aliases.close();
         }
-        return null;
     }
-    catch {
-        return null;
+    finally {
+        relay.close();
     }
 }
 export function listAliases(root) {
-    let entries;
+    const relay = openRelayRoot(root);
+    if (relay === null)
+        return [];
     try {
-        entries = fs.readdirSync(aliasesDir(root), { withFileTypes: true });
+        const aliases = relay.openDirectory('aliases');
+        if (aliases === null)
+            return [];
+        try {
+            const out = [];
+            for (const entry of aliases.readDirectory()) {
+                if (!entry.name.endsWith('.json'))
+                    continue;
+                if (entry.isSymbolicLink())
+                    throw new RelayFilesystemError(`Refusing symlinked relay alias: ${entry.name}`);
+                if (!entry.isFile())
+                    continue;
+                try {
+                    const alias = readAliasFromDirectory(aliases, entry.name.slice(0, -'.json'.length));
+                    if (alias)
+                        out.push(alias);
+                }
+                catch (error) {
+                    rethrowFilesystemError(error);
+                }
+            }
+            return out.sort((a, b) => a.claimedAt - b.claimedAt);
+        }
+        finally {
+            aliases.close();
+        }
     }
-    catch {
+    catch (error) {
+        rethrowFilesystemError(error);
         return [];
     }
-    const out = [];
-    for (const entry of entries) {
-        if (!entry.isFile() || !entry.name.endsWith('.json'))
-            continue;
-        const alias = readAlias(root, entry.name.slice(0, -'.json'.length));
-        if (alias)
-            out.push(alias);
+    finally {
+        relay.close();
     }
-    return out.sort((a, b) => a.claimedAt - b.claimedAt);
 }
 /** Last-claim-wins: overwrites any prior owner. */
 export function claimAlias(root, name, addr, sessionId) {
@@ -99,50 +150,96 @@ export function claimAlias(root, name, addr, sessionId) {
     return alias;
 }
 export function clearAlias(root, name) {
+    if (!isValidAliasName(name))
+        return;
+    const relay = openRelayRoot(root);
+    if (relay === null)
+        return;
     try {
-        fs.unlinkSync(aliasPath(root, name));
+        const aliases = relay.openDirectory('aliases');
+        if (aliases === null)
+            return;
+        try {
+            aliases.unlinkFile(`${name}.json`);
+        }
+        catch (error) {
+            rethrowFilesystemError(error);
+            // deletion remains best-effort for ordinary I/O failures
+        }
+        finally {
+            aliases.close();
+        }
     }
-    catch {
-        // already gone
+    finally {
+        relay.close();
     }
 }
 export function writeRecord(root, record) {
-    ensureRoot(root);
-    const file = recordPath(root, record.addr);
-    const tmp = `${file}.${process.pid}.tmp`;
-    fs.writeFileSync(tmp, JSON.stringify(record, null, 2), { mode: 0o600 });
-    fs.renameSync(tmp, file);
+    const relay = openRelayRoot(root, true);
+    try {
+        relay.writeFileAtomic(`${record.addr}.json`, JSON.stringify(record, null, 2));
+    }
+    finally {
+        relay.close();
+    }
+}
+function readRecordFromDirectory(directory, addr) {
+    const raw = directory.readFile(`${addr}.json`);
+    if (raw === null)
+        return null;
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.addr === 'string' && typeof parsed.pid === 'number')
+        return parsed;
+    return null;
 }
 export function readRecord(root, addr) {
-    try {
-        const parsed = JSON.parse(fs.readFileSync(recordPath(root, addr), 'utf8'));
-        if (parsed && typeof parsed.addr === 'string' && typeof parsed.pid === 'number') {
-            return parsed;
-        }
+    assertPathSegment(addr, 'relay address');
+    const relay = openRelayRoot(root);
+    if (relay === null)
         return null;
+    try {
+        return readRecordFromDirectory(relay, addr);
     }
-    catch {
+    catch (error) {
+        rethrowFilesystemError(error);
         return null;
     }
+    finally {
+        relay.close();
+    }
 }
 /** Read-only listing, oldest first. Never mutates anything. */
 export function listRecords(root) {
-    let entries;
+    const relay = openRelayRoot(root);
+    if (relay === null)
+        return [];
     try {
-        entries = fs.readdirSync(root, { withFileTypes: true });
+        const out = [];
+        for (const entry of relay.readDirectory()) {
+            if (!entry.name.endsWith('.json'))
+                continue;
+            if (entry.isSymbolicLink())
+                throw new RelayFilesystemError(`Refusing symlinked relay record: ${entry.name}`);
+            if (!entry.isFile())
+                continue;
+            try {
+                const record = readRecordFromDirectory(relay, entry.name.slice(0, -'.json'.length));
+                if (record)
+                    out.push(record);
+            }
+            catch (error) {
+                rethrowFilesystemError(error);
+            }
+        }
+        return out.sort((a, b) => a.startedAt - b.startedAt);
     }
-    catch {
+    catch (error) {
+        rethrowFilesystemError(error);
         return [];
     }
-    const out = [];
-    for (const entry of entries) {
-        if (!entry.isFile() || !entry.name.endsWith('.json'))
-            continue;
-        const record = readRecord(root, entry.name.slice(0, -'.json'.length));
-        if (record)
-            out.push(record);
+    finally {
+        relay.close();
     }
-    return out.sort((a, b) => a.startedAt - b.startedAt);
 }
 function pidAlive(pid) {
     if (!Number.isInteger(pid) || pid <= 0)
@@ -163,22 +260,97 @@ export function presenceOf(record, now = Date.now()) {
         return 'offline';
     return now - record.lastSeenAt < HEARTBEAT_STALE_MS ? 'live' : 'stalled';
 }
-function dirHasJson(dir) {
+function dirHasJson(root, name) {
+    const relay = openRelayRoot(root);
+    if (relay === null)
+        return false;
     try {
-        return fs.readdirSync(dir).some((f) => f.endsWith('.json'));
+        const directory = relay.openDirectory(name);
+        if (directory === null)
+            return false;
+        try {
+            return directory.readDirectory().some((entry) => {
+                if (!entry.name.endsWith('.json'))
+                    return false;
+                if (entry.isSymbolicLink())
+                    throw new RelayFilesystemError(`Refusing symlinked relay entry: ${entry.name}`);
+                return entry.isFile();
+            });
+        }
+        finally {
+            directory.close();
+        }
     }
-    catch {
+    catch (error) {
+        rethrowFilesystemError(error);
         return false;
     }
+    finally {
+        relay.close();
+    }
 }
-function rmrf(target) {
+function claimsHaveJson(root, addr) {
+    const relay = openRelayRoot(root);
+    if (relay === null)
+        return false;
     try {
-        fs.rmSync(target, { recursive: true, force: true });
+        const claims = relay.openDirectory(`${addr}.claims`);
+        if (claims === null)
+            return false;
+        try {
+            for (const entry of claims.readDirectory()) {
+                if (entry.isSymbolicLink())
+                    throw new RelayFilesystemError(`Refusing symlinked relay claim: ${entry.name}`);
+                if (!entry.isDirectory())
+                    continue;
+                const claim = claims.openDirectory(entry.name);
+                if (claim === null)
+                    continue;
+                try {
+                    if (claim.readDirectory().some((file) => {
+                        if (!file.name.endsWith('.json'))
+                            return false;
+                        if (file.isSymbolicLink()) {
+                            throw new RelayFilesystemError(`Refusing symlinked claimed letter: ${file.name}`);
+                        }
+                        return file.isFile();
+                    })) {
+                        return true;
+                    }
+                }
+                finally {
+                    claim.close();
+                }
+            }
+            return false;
+        }
+        finally {
+            claims.close();
+        }
     }
-    catch {
-        // sweep is best-effort
+    finally {
+        relay.close();
     }
 }
+function removeClaims(directory, addr) {
+    const claimsName = `${addr}.claims`;
+    const claims = directory.openDirectory(claimsName);
+    if (claims === null)
+        return;
+    try {
+        for (const entry of claims.readDirectory()) {
+            if (entry.isSymbolicLink())
+                throw new RelayFilesystemError(`Refusing symlinked relay claim: ${entry.name}`);
+            if (!entry.isDirectory())
+                continue;
+            claims.removeDirectory(entry.name);
+        }
+    }
+    finally {
+        claims.close();
+    }
+    directory.removeDirectory(claimsName);
+}
 /**
  * Reclaim dead sessions' files. Rules (mail outranks tidiness):
  * - a running session is never touched;
@@ -196,19 +368,31 @@ export function sweep(root, now = Date.now(), sessionExists) {
     for (const record of listRecords(root)) {
         if (presenceOf(record, now) !== 'offline')
             continue;
-        const hasMail = dirHasJson(inboxDir(root, record.addr)) || dirHasJson(asksDir(root, record.addr));
+        const hasMail = dirHasJson(root, `${record.addr}.inbox`) ||
+            dirHasJson(root, `${record.addr}.asks`) ||
+            claimsHaveJson(root, record.addr);
         const expired = now - record.lastSeenAt >= SWEEP_MAIL_KEEP_MS;
         if (hasMail && !expired)
             continue;
         if (!expired && (sessionExists?.(record.sessionId) ?? true))
             continue;
-        rmrf(inboxDir(root, record.addr));
-        rmrf(asksDir(root, record.addr));
-        try {
-            fs.unlinkSync(recordPath(root, record.addr));
-        }
-        catch {
-            // already gone
+        const relay = openRelayRoot(root);
+        if (relay !== null) {
+            try {
+                relay.removeDirectory(`${record.addr}.inbox`);
+                relay.removeDirectory(`${record.addr}.asks`);
+                removeClaims(relay, record.addr);
+                try {
+                    relay.unlinkFile(`${record.addr}.json`);
+                }
+                catch (error) {
+                    rethrowFilesystemError(error);
+                    // deletion remains best-effort for ordinary I/O failures
+                }
+            }
+            finally {
+                relay.close();
+            }
         }
     }
     // Aliases are swept when the owning session dies: an alias whose record

package/dist/relay.test.js

@@ -3,16 +3,18 @@
  * specification: each case pins a guarantee from the design.
  */
 import * as fs from 'node:fs';
+import { createRequire, syncBuiltinESMExports } from 'node:module';
 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, clearAsk, deposit, drain, pendingAsks, previewBody, readAudit, readOutgoingAsk, resolveAskByRef, trackIncomingAsk, trackOutgoingAsk, unreadCount, watchInbox, } from './mailbox.js';
+import { appendAudit, auditLogPath, awaitReceipt, claimInbox, clearAsk, deposit, drain, pendingAsks, previewBody, readAudit, readIncomingAsk, readOutgoingAsk, recoverInboxClaims, 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);
 const dirs = [];
 function tmpRoot() {
-    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pi-relay-test-'));
+    const dir = fs.realpathSync.native(fs.mkdtempSync(path.join(os.tmpdir(), 'pi-relay-test-')));
     dirs.push(dir);
     return dir;
 }
@@ -20,6 +22,33 @@ afterEach(() => {
     while (dirs.length > 0)
         fs.rmSync(dirs.pop(), { recursive: true, force: true });
 });
+let swapSequence = 0;
+function swapWhenPinned(target, replacement, operation) {
+    const parked = `${target}.pinned-${++swapSequence}`;
+    const identity = fs.statSync(target);
+    const mutableFs = require('node:fs');
+    const originalFstatSync = mutableFs.fstatSync;
+    let swapped = false;
+    mutableFs.fstatSync = ((fd) => {
+        const stat = originalFstatSync(fd);
+        if (!swapped && stat.dev === identity.dev && stat.ino === identity.ino) {
+            fs.renameSync(target, parked);
+            fs.renameSync(replacement, target);
+            swapped = true;
+        }
+        return stat;
+    });
+    syncBuiltinESMExports();
+    try {
+        operation();
+    }
+    finally {
+        mutableFs.fstatSync = originalFstatSync;
+        syncBuiltinESMExports();
+    }
+    expect(swapped).toBe(true);
+    return parked;
+}
 function record(over = {}) {
     const now = Date.now();
     return {
@@ -58,6 +87,19 @@ describe('registry', () => {
         expect(presenceOf(record({ offline: true }))).toBe('offline');
         expect(presenceOf(record({ pid: 2_000_000_000 }))).toBe('offline'); // dead pid
     });
+    it('uses random exclusive temp files without overwriting a predictable temp', () => {
+        const root = tmpRoot();
+        const value = record();
+        const outside = path.join(root, 'outside');
+        const predictable = path.join(root, `${value.addr}.json.${process.pid}.tmp`);
+        fs.writeFileSync(outside, 'outside-sentinel');
+        fs.symlinkSync(outside, predictable, 'file');
+        writeRecord(root, value);
+        writeRecord(root, { ...value, name: 'updated' });
+        expect(fs.readFileSync(outside, 'utf8')).toBe('outside-sentinel');
+        expect(fs.lstatSync(predictable).isSymbolicLink()).toBe(true);
+        expect(readRecord(root, value.addr)?.name).toBe('updated');
+    });
     it('listing has no side effects and survives garbage files', () => {
         const root = tmpRoot();
         writeRecord(root, record());
@@ -104,6 +146,16 @@ describe('registry', () => {
         expect(listRecords(root)).toHaveLength(1);
         expect(unreadCount(root, record().addr)).toBe(1);
     });
+    it('treats a recoverable durable claim as undelivered mail', () => {
+        const root = tmpRoot();
+        const crashed = record({ offline: true, pid: 2_000_000_005 });
+        writeRecord(root, crashed);
+        deposit(root, crashed.addr, letter());
+        const claim = claimInbox(root, crashed.addr);
+        sweep(root, Date.now(), () => false);
+        expect(readRecord(root, crashed.addr)).not.toBeNull();
+        expect(recoverInboxClaims(root, crashed.addr)).toEqual([claim]);
+    });
 });
 describe('mailbox', () => {
     it('delivers oldest-first, exactly once, with no partial reads', () => {
@@ -179,6 +231,128 @@ describe('mailbox', () => {
         expect(drain(root, addr).map((l) => l.body)).toEqual(['while you were out']);
     });
 });
+describe('descriptor-relative filesystem safety', () => {
+    it('keeps record reads on a pinned root after the configured root is swapped', () => {
+        const root = tmpRoot();
+        const replacement = `${root}.replacement`;
+        fs.mkdirSync(replacement);
+        writeRecord(root, record({ name: 'pinned' }));
+        writeRecord(replacement, record({ name: 'attacker' }));
+        const result = { current: null };
+        const parked = swapWhenPinned(root, replacement, () => {
+            result.current = readRecord(root, record().addr);
+        });
+        expect(result.current?.name).toBe('pinned');
+        expect(JSON.parse(fs.readFileSync(path.join(root, `${record().addr}.json`), 'utf8')).name).toBe('attacker');
+        expect(JSON.parse(fs.readFileSync(path.join(parked, `${record().addr}.json`), 'utf8')).name).toBe('pinned');
+    });
+    it('deletes aliases through the pinned aliases descriptor after a child swap', () => {
+        const root = tmpRoot();
+        writeAlias(root, { name: 'ci', addr: 'aaaa1111bbbb', sessionId: 'pinned', claimedAt: 1 });
+        const aliases = path.join(root, 'aliases');
+        const replacement = path.join(root, 'aliases.replacement');
+        fs.mkdirSync(replacement);
+        fs.writeFileSync(path.join(replacement, 'ci.json'), '{"sessionId":"attacker"}');
+        const parked = swapWhenPinned(aliases, replacement, () => clearAlias(root, 'ci'));
+        expect(fs.existsSync(path.join(parked, 'ci.json'))).toBe(false);
+        expect(fs.readFileSync(path.join(aliases, 'ci.json'), 'utf8')).toContain('attacker');
+    });
+    it('appends audit records to the pinned root after a root swap', () => {
+        const root = tmpRoot();
+        const replacement = `${root}.replacement`;
+        fs.mkdirSync(replacement);
+        fs.writeFileSync(path.join(root, 'audit.log'), '');
+        fs.writeFileSync(path.join(replacement, 'audit.log'), 'attacker-sentinel\n');
+        const parked = swapWhenPinned(root, replacement, () => appendAudit(root, {
+            ts: 1,
+            event: 'deliver',
+            kind: 'message',
+            from: 'aaaa1111bbbb',
+            to: 'cccc2222dddd',
+            messageId: 'audit-race',
+            preview: 'safe',
+        }));
+        expect(fs.readFileSync(path.join(parked, 'audit.log'), 'utf8')).toContain('audit-race');
+        expect(fs.readFileSync(path.join(root, 'audit.log'), 'utf8')).toBe('attacker-sentinel\n');
+    });
+    it('deposits and drains through pinned inbox descriptors after child swaps', () => {
+        const depositRoot = tmpRoot();
+        const addr = 'race00000001';
+        const inbox = path.join(depositRoot, `${addr}.inbox`);
+        const replacement = `${inbox}.replacement`;
+        fs.mkdirSync(inbox);
+        fs.mkdirSync(replacement);
+        const deposited = letter({ id: 'deposit-race', ts: 1000 });
+        const parkedInbox = swapWhenPinned(inbox, replacement, () => deposit(depositRoot, addr, deposited));
+        expect(fs.readdirSync(inbox)).toEqual([]);
+        expect(fs.readdirSync(parkedInbox).some((name) => name.endsWith('.json'))).toBe(true);
+        const drainRoot = tmpRoot();
+        const drainInbox = path.join(drainRoot, `${addr}.inbox`);
+        const drainReplacement = `${drainInbox}.replacement`;
+        fs.mkdirSync(drainInbox);
+        fs.mkdirSync(drainReplacement);
+        fs.writeFileSync(path.join(drainInbox, '1000-pinned.json'), JSON.stringify(letter({ id: 'drain-race' })));
+        fs.writeFileSync(path.join(drainReplacement, '1000-attacker.json'), JSON.stringify(letter({ body: 'attacker' })));
+        let drained = [];
+        const parkedDrain = swapWhenPinned(drainInbox, drainReplacement, () => {
+            drained = drain(drainRoot, addr);
+        });
+        expect(drained.map((entry) => entry.id)).toEqual(['drain-race']);
+        expect(fs.readdirSync(parkedDrain)).toEqual([]);
+        expect(fs.readdirSync(drainInbox)).toEqual(['1000-attacker.json']);
+    });
+    it('reads and clears asks through the pinned asks descriptor after child swaps', () => {
+        const root = tmpRoot();
+        const addr = 'race00000002';
+        const ask = letter({ id: 'ask-race', kind: 'ask' });
+        trackIncomingAsk(root, addr, ask);
+        const asks = path.join(root, `${addr}.asks`);
+        const replacement = `${asks}.replacement`;
+        fs.mkdirSync(replacement);
+        fs.writeFileSync(path.join(replacement, `${ask.id}.json`), JSON.stringify(letter({ id: ask.id, body: 'attacker' })));
+        const result = { current: null };
+        const parked = swapWhenPinned(asks, replacement, () => {
+            result.current = readIncomingAsk(root, addr, ask.id);
+        });
+        expect(result.current?.body).toBe('hello');
+        const current = asks;
+        const secondReplacement = `${asks}.second-replacement`;
+        fs.mkdirSync(secondReplacement);
+        fs.writeFileSync(path.join(secondReplacement, `${ask.id}.json`), JSON.stringify(letter({ body: 'second-attacker' })));
+        const parkedReplacement = swapWhenPinned(current, secondReplacement, () => clearAsk(root, addr, ask.id));
+        expect(fs.existsSync(path.join(parkedReplacement, `${ask.id}.json`))).toBe(false);
+        expect(fs.existsSync(path.join(parked, `${ask.id}.json`))).toBe(true);
+        expect(fs.readFileSync(path.join(current, `${ask.id}.json`), 'utf8')).toContain('second-attacker');
+    });
+    it('keeps a watch on the pinned inbox and closes its descriptors', async () => {
+        const root = tmpRoot();
+        const descriptorDirectory = process.platform === 'darwin' ? '/dev/fd' : '/proc/self/fd';
+        const descriptorCount = () => fs.readdirSync(descriptorDirectory).length;
+        const addr = 'race00000003';
+        const inbox = path.join(root, `${addr}.inbox`);
+        const replacement = `${inbox}.replacement`;
+        fs.mkdirSync(inbox);
+        fs.mkdirSync(replacement);
+        let calls = 0;
+        let unwatch = () => { };
+        const before = descriptorCount();
+        const parked = swapWhenPinned(inbox, replacement, () => {
+            unwatch = watchInbox(root, addr, () => calls++);
+        });
+        expect(descriptorCount()).toBeGreaterThanOrEqual(before + 2);
+        try {
+            fs.writeFileSync(path.join(parked, 'mail.json'), '{}');
+            const deadline = Date.now() + 2000;
+            while (calls === 0 && Date.now() < deadline)
+                await new Promise((resolve) => setTimeout(resolve, 25));
+            expect(calls).toBeGreaterThan(0);
+        }
+        finally {
+            unwatch();
+        }
+        expect(descriptorCount()).toBe(before);
+    });
+});
 describe('aliases', () => {
     function alias(over = {}) {
         return { name: 'ci', addr: 'aaaa1111bbbb', sessionId: 'sid-1', claimedAt: Date.now(), ...over };