@sema-agent/core 7.1.0 → 7.3.0

package/dist/stores/file/mailbox-store.d.ts

@@ -1,7 +1,44 @@
 import { type MailboxAppendMessage, type MailboxLease, type MailboxStore } from "../../core/mailbox-store.js";
+/** The waiter's refusal when a box lock stays held by a LIVE process past `lockWaitMs`. Carried as
+ *  `.code` on a plain Error (consumers branch on the string); the message names the lock and the holder. */
+export declare const MAILBOX_BOX_LOCK_TIMEOUT_CODE = "mailbox.box_lock_timeout";
+/** The holder's refusal when its lock was found to have changed hands at release — the critical
+ *  section may have overlapped another process's; its effects are reported as NOT trustworthy. */
+export declare const MAILBOX_BOX_LOCK_COMPROMISED_CODE = "mailbox.box_lock_compromised";
+/**
+ * Acquire the cross-process BOX LOCK (design/385 §1.2⑥ ring 1) at `lockPath` — `<box>.jsonl.lock`.
+ * Resolves with a release function once held; rejects with `mailbox.box_lock_timeout` when the lock is
+ * not obtainable within `waitMs` — a LIVE holder keeps it, or it is unreadable/unreclaimable and needs
+ * an operator (the message names which). Exported at module level for the real-process acceptance
+ * run (a fixture that holds the lock and dies / stays alive); not part of the package surface.
+ *
+ * Reclaim protocol (a holder that DIED — the pid recorded in the lock no longer exists):
+ *  - ONE reclaimer per stale lock instance: a reclaimer first publishes a GATE named after the stale
+ *    lock's own nonce (`<lock>.reclaim.<nonce>`, `O_EXCL`); only the gate winner touches the lock, so
+ *    no second reclaimer can remove the stale file underneath the winner and let a fresh live lock
+ *    appear at the path in between — the interleaving that would otherwise let the winner move a
+ *    live holder's lock aside. Losers back off like any waiter.
+ *  - the winner renames the stale file aside, re-reads the moved file and confirms it is exactly the
+ *    (pid, nonce) it judged (belt: a mismatch is moved back untouched), unlinks it, then removes the
+ *    gate. A gate or an aside file older than {@link BOX_LOCK_RECLAIM_GRACE_MS} is the residue of a
+ *    reclaimer that died mid-reclaim and is cleared by the next one.
+ *  - a lock whose recorded pid is ALIVE is never reclaimed. Liveness is `kill(pid, 0)`: the processes
+ *    that share a box must share the host's pid namespace (a container that mounts the same volume
+ *    from another pid namespace cannot see the holder and would judge every lock dead). A dead
+ *    holder's pid reused by an unrelated long-lived process reads as alive; the waiter then times out
+ *    LOUDLY naming the pid, and the lock file is removed by hand — the accepted failure, chosen over
+ *    an age rule that would reclaim a live-but-slow holder.
+ *  - the holder verifies its nonce at release; a lock that changed hands underneath it surfaces as
+ *    `mailbox.box_lock_compromised`, never as a silent success.
+ */
+export declare function acquireMailboxBoxLock(lockPath: string, waitMs: number): Promise<() => void>;
 export interface FileMailboxStoreOptions {
     /** When false, ledger appends are NOT fsync'd. Default true. */
     fsync?: boolean;
+    /** design/385 — how long an operation waits for a box lock a LIVE process holds before failing with
+     *  `mailbox.box_lock_timeout`. Default 10 000 ms. Must be a finite number > 0 (anything else refuses
+     *  at construction — a bad knob never becomes a silent default). */
+    lockWaitMs?: number;
     /** Compact a box's event log into a snapshot-form log once it exceeds this many events. Default 500. */
     compactEvery?: number;
     /** Disclosure seat (review-510 family; server pickup receipt named this store's gap): a corrupt
@@ -14,10 +51,14 @@ export interface FileMailboxStoreOptions {
     }) => void;
 }
 export declare class FileMailboxStore implements MailboxStore {
+    /** design/385 — the whole cross-process set (box lock + fresh re-read + descriptor reopen +
+     *  compaction under the lock) is in place and accepted by `mailboxCrossProcessContract`. */
+    readonly crossProcessSafe = true;
     private readonly dir;
     private readonly tmpDir;
     private readonly fsyncEnabled;
     private readonly compactEvery;
+    private readonly lockWaitMs;
     /** Paths THIS instance has touched → the EXACT BoxState it took a ref on (server[1523] 对等复审
      *  发现1: after a drop/reap deletes the shared box, another instance's stale close() must not
      *  decrement a REBUILT box's refs — identity is checked, not just the path). */
@@ -53,6 +94,22 @@ export declare class FileMailboxStore implements MailboxStore {
      * file talked about the rule.
      */
     private lockKey;
+    /**
+     * The two-ring critical section (module header): the in-process mutex on the canonical key, then the
+     * cross-process box lock on the verbatim path. `fn` runs with both held; the box lock is released on
+     * every exit. A compromised release (the lock changed hands) surfaces as a throw AFTER `fn` — an
+     * operation whose critical section may have overlapped another process's is never reported as a
+     * success; when `fn` itself threw, its own error wins.
+     */
+    private withBox;
+    /**
+     * design/385 ring 2 — bring a CACHED box up to date with the file, inside the box lock. A mark that
+     * matches means nothing happened since this process last left the file at rest; a moved mark means
+     * another process wrote (append/lease/ack/release, or a compaction/drop that replaced the inode),
+     * and the cache is replayed from the file. A moved INODE also swap-closes the descriptor (ring 3):
+     * the next write reopens the current file instead of landing on the unlinked one.
+     */
+    private reconcile;
     private load;
     private commit;
     private compact;

package/dist/stores/file/mailbox-store.js

@@ -1,7 +1,8 @@
 import { join, resolve, sep } from "node:path";
+import { randomBytes } from "node:crypto";
 import { assertRetentionPolicy } from "../../core/retention-policy.js";
-import { existsSync, readdirSync, realpathSync } from "node:fs";
-import { newestSentAt, } from "../../core/mailbox-store.js";
+import { existsSync, linkSync, readdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { detachMailboxMessage, newestSentAt, readMailboxPeerMeta, } from "../../core/mailbox-store.js";
 import { AppendLog, atomicWriteFile, canonicalStoreKey, ensureDir, readJsonlRecords, sanitizeScope, sanitizePathComponent } from "./fs-atomic.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
 function realpathSyncSafe(p) {
@@ -12,6 +13,31 @@ function realpathSyncSafe(p) {
         return p;
     }
 }
+function diskMarkOf(path) {
+    try {
+        const st = statSync(path);
+        return { ino: st.ino, size: st.size, mtimeMs: st.mtimeMs };
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        throw err;
+    }
+}
+const UNKNOWN_MARK = { ino: -1, size: -1, mtimeMs: -1 };
+function markAfterWrite(path) {
+    try {
+        return diskMarkOf(path);
+    }
+    catch {
+        return UNKNOWN_MARK;
+    }
+}
+function sameDiskMark(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    return a.ino === b.ino && a.size === b.size && a.mtimeMs === b.mtimeMs;
+}
 const sharedBoxes = new Map();
 function listBoxFiles(scopeDir) {
     try {
@@ -35,17 +61,291 @@ function withPathLock(key, fn) {
     });
     return run;
 }
+export const MAILBOX_BOX_LOCK_TIMEOUT_CODE = "mailbox.box_lock_timeout";
+export const MAILBOX_BOX_LOCK_COMPROMISED_CODE = "mailbox.box_lock_compromised";
+const BOX_LOCK_RECLAIM_GRACE_MS = 5_000;
+const BOX_LOCK_BACKOFF_MIN_MS = 1;
+const BOX_LOCK_BACKOFF_MAX_MS = 16;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const abandonedLockNonces = new Set();
+function ownerAlive(owner) {
+    if (owner.pid === process.pid)
+        return !abandonedLockNonces.has(owner.nonce);
+    return isProcessAlive(owner.pid);
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code !== "ESRCH";
+    }
+}
+function readLockOwner(lockPath) {
+    let raw;
+    try {
+        raw = readFileSync(lockPath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        return "unobservable";
+    }
+    const [pidText, nonce, rest] = raw.split("\n");
+    if (pidText === undefined || !/^[1-9][0-9]*$/.test(pidText) || nonce === undefined || !/^[0-9a-f]{16}$/.test(nonce) || rest !== "")
+        return "unreadable";
+    return { pid: Number.parseInt(pidText, 10), nonce };
+}
+function publishLockFile(lockPath, owner) {
+    const tmp = `${lockPath}.pub.${owner.pid}.${owner.nonce}`;
+    writeFileSync(tmp, `${owner.pid}\n${owner.nonce}\n`, { mode: 0o600 });
+    try {
+        linkSync(tmp, lockPath);
+        return true;
+    }
+    catch (err) {
+        const back = readLockOwner(lockPath);
+        if (back !== undefined && back !== "unreadable" && back !== "unobservable" && back.pid === owner.pid && back.nonce === owner.nonce)
+            return true;
+        if (back === "unobservable")
+            abandonedLockNonces.add(owner.nonce);
+        if (err.code === "EEXIST")
+            return false;
+        throw err;
+    }
+    finally {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+        }
+    }
+}
+export async function acquireMailboxBoxLock(lockPath, waitMs) {
+    const mine = { pid: process.pid, nonce: randomBytes(8).toString("hex") };
+    const deadline = Date.now() + waitMs;
+    let backoff = BOX_LOCK_BACKOFF_MIN_MS;
+    let holderNote = "unknown holder";
+    let swept = false;
+    for (;;) {
+        let published;
+        try {
+            published = publishLockFile(lockPath, mine);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+            ensureDir(join(lockPath, ".."));
+            continue;
+        }
+        if (published) {
+            return () => {
+                let now = readLockOwner(lockPath);
+                if (now === "unobservable")
+                    now = readLockOwner(lockPath);
+                if (now === "unobservable") {
+                    abandonedLockNonces.add(mine.nonce);
+                    console.warn(`[sema] file mailbox: the box lock ${lockPath} could not be read back at release (a read fault); it is kept and still names this live process (pid ${process.pid}). ` +
+                        `This process reclaims it at its next use of the box; another process waits on it and times out naming this pid until then.`);
+                    return;
+                }
+                if (now === undefined || now === "unreadable" || now.nonce !== mine.nonce) {
+                    const e = new Error(`FileMailboxStore: the box lock ${lockPath} changed hands while this process held it (a stale reclaim overlapped) — the operation just performed may have raced another process; do not trust it`);
+                    e.code = MAILBOX_BOX_LOCK_COMPROMISED_CODE;
+                    e.lockPath = lockPath;
+                    throw e;
+                }
+                try {
+                    unlinkSync(lockPath);
+                }
+                catch (first) {
+                    const again = readLockOwner(lockPath);
+                    if (again === undefined || again === "unreadable" || (again !== "unobservable" && again.nonce !== mine.nonce))
+                        return;
+                    try {
+                        if (again === "unobservable")
+                            throw first;
+                        unlinkSync(lockPath);
+                    }
+                    catch {
+                        abandonedLockNonces.add(mine.nonce);
+                        console.warn(`[sema] file mailbox: the box lock ${lockPath} could not be handed back (${first.message}); it still names this live process (pid ${process.pid}). ` +
+                            `This process reclaims it at its next use of the box; another process waits on it and times out naming this pid until then.`);
+                    }
+                }
+            };
+        }
+        const owner = readLockOwner(lockPath);
+        if (owner === undefined)
+            continue;
+        let reclaim = "blocked";
+        if (owner === "unreadable") {
+            holderNote = "unreadable lock file — remove it by hand if no process holds it";
+        }
+        else if (owner === "unobservable") {
+            holderNote = "the lock file could not be read (a read fault)";
+        }
+        else if (ownerAlive(owner)) {
+            holderNote = owner.pid === process.pid ? `pid ${owner.pid} (this process — another isolate or thread of it)` : `pid ${owner.pid}`;
+        }
+        else {
+            const r = reclaimStaleBoxLock(lockPath, owner, mine);
+            reclaim = r.outcome;
+            holderNote = r.note;
+        }
+        if (reclaim === "done")
+            continue;
+        if (!swept) {
+            swept = true;
+            sweepLockResidue(join(lockPath, ".."), lockPath.slice(join(lockPath, "..").length + 1));
+        }
+        if (Date.now() >= deadline) {
+            const e = new Error(`FileMailboxStore: the box lock ${lockPath} was not obtainable within ${waitMs}ms (${holderNote}) — refusing to touch the box without it`);
+            e.code = MAILBOX_BOX_LOCK_TIMEOUT_CODE;
+            e.lockPath = lockPath;
+            if (owner !== "unreadable" && owner !== "unobservable")
+                e.holderPid = owner.pid;
+            throw e;
+        }
+        await sleep(backoff / 2 + Math.random() * (backoff / 2));
+        backoff = Math.min(BOX_LOCK_BACKOFF_MAX_MS, backoff * 2);
+    }
+}
+function ageOf(path) {
+    try {
+        return Date.now() - statSync(path).mtimeMs;
+    }
+    catch {
+        return undefined;
+    }
+}
+function reclaimStaleBoxLock(lockPath, stale, mine) {
+    const gate = `${lockPath}.reclaim.${stale.nonce}`;
+    let gateOwned;
+    try {
+        gateOwned = publishLockFile(gate, mine);
+    }
+    catch (err) {
+        return { outcome: "blocked", note: `stale lock of dead pid ${stale.pid}; the reclaim gate could not be published: ${err.message}` };
+    }
+    if (!gateOwned) {
+        const g = readLockOwner(gate);
+        if (g === "unobservable")
+            return { outcome: "blocked", note: `stale lock of dead pid ${stale.pid}; its reclaim gate could not be read (a read fault)` };
+        const gateLive = g !== undefined && g !== "unreadable" && ownerAlive(g);
+        if (gateLive)
+            return { outcome: "blocked", note: `stale lock of dead pid ${stale.pid}; pid ${g.pid} is reclaiming it` };
+        if (g === undefined || g !== "unreadable" || (ageOf(gate) ?? 0) > BOX_LOCK_RECLAIM_GRACE_MS) {
+            try {
+                unlinkSync(gate);
+            }
+            catch {
+            }
+        }
+        return { outcome: "blocked", note: `stale lock of dead pid ${stale.pid}; a previous reclaim's gate is being cleared` };
+    }
+    try {
+        const again = readLockOwner(lockPath);
+        if (again === undefined)
+            return { outcome: "done", note: "" };
+        if (again === "unobservable")
+            return { outcome: "blocked", note: `stale lock of dead pid ${stale.pid} could not be re-read under the gate (a read fault)` };
+        if (again === "unreadable" || again.pid !== stale.pid || again.nonce !== stale.nonce) {
+            return { outcome: "blocked", note: `stale lock of dead pid ${stale.pid} was reclaimed meanwhile; re-judging the current holder` };
+        }
+        const aside = `${lockPath}.stale.${mine.pid}.${mine.nonce}`;
+        try {
+            renameSync(lockPath, aside);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return { outcome: "done", note: "" };
+            return { outcome: "blocked", note: `stale lock of dead pid ${stale.pid} cannot be moved aside: ${err.message}` };
+        }
+        try {
+            unlinkSync(aside);
+        }
+        catch {
+        }
+        sweepLockResidue(join(lockPath, ".."), lockPath.slice(join(lockPath, "..").length + 1));
+        return { outcome: "done", note: "" };
+    }
+    finally {
+        try {
+            unlinkSync(gate);
+        }
+        catch {
+        }
+    }
+}
+const RESIDUE_NAME_RE = /\.jsonl\.lock\.(?:pub|stale)\.([1-9][0-9]*)\.([0-9a-f]{16})$/;
+const GATE_NAME_RE = /\.jsonl\.lock\.reclaim\.[0-9a-f]{16}$/;
+function sweepLockResidue(dir, lockName) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    const now = Date.now();
+    for (const name of names) {
+        if (lockName !== undefined && !name.startsWith(`${lockName}.`))
+            continue;
+        const isGate = GATE_NAME_RE.test(name);
+        const named = RESIDUE_NAME_RE.exec(name);
+        if (!isGate && named === null)
+            continue;
+        const p = join(dir, name);
+        let owner;
+        if (isGate) {
+            const g = readLockOwner(p);
+            if (g === "unobservable")
+                continue;
+            owner = g !== undefined && g !== "unreadable" ? g : undefined;
+        }
+        else {
+            owner = { pid: Number.parseInt(named[1], 10), nonce: named[2] };
+        }
+        if (owner !== undefined && ownerAlive(owner))
+            continue;
+        if (owner === undefined) {
+            let age;
+            try {
+                age = now - statSync(p).mtimeMs;
+            }
+            catch {
+                continue;
+            }
+            if (age <= BOX_LOCK_RECLAIM_GRACE_MS)
+                continue;
+        }
+        try {
+            unlinkSync(p);
+        }
+        catch {
+        }
+    }
+}
 export class FileMailboxStore {
+    crossProcessSafe = true;
     dir;
     tmpDir;
     fsyncEnabled;
     compactEvery;
+    lockWaitMs;
     touched = new Map();
     discloseCorrupt;
     constructor(root, opts = {}) {
         assertAdoptionBootGate(root, "FileMailboxStore");
         this.fsyncEnabled = opts.fsync !== false;
         this.compactEvery = opts.compactEvery ?? 500;
+        const lockWaitMs = opts.lockWaitMs ?? 10_000;
+        if (typeof lockWaitMs !== "number" || !Number.isFinite(lockWaitMs) || lockWaitMs <= 0) {
+            throw new Error(`FileMailboxStore: lockWaitMs must be a finite number > 0, got ${JSON.stringify(opts.lockWaitMs)}`);
+        }
+        this.lockWaitMs = lockWaitMs;
         const sink = opts.onCorruptRead;
         this.discloseCorrupt =
             sink === undefined
@@ -70,6 +370,40 @@ export class FileMailboxStore {
     lockKey(scope, handle) {
         return canonicalStoreKey(this.boxPath(scope, handle));
     }
+    withBox(key, path, fn) {
+        return withPathLock(key, async () => {
+            const release = await acquireMailboxBoxLock(`${path}.lock`, this.lockWaitMs);
+            let result;
+            try {
+                result = await fn();
+            }
+            catch (err) {
+                try {
+                    release();
+                }
+                catch {
+                }
+                throw err;
+            }
+            release();
+            return result;
+        });
+    }
+    reconcile(b) {
+        const now = diskMarkOf(b.path);
+        if (sameDiskMark(now, b.mark))
+            return;
+        if (now === undefined || b.mark === undefined || now.ino !== b.mark.ino)
+            b.log.closeForSwap();
+        const events = readJsonlRecords(b.path, this.discloseCorrupt);
+        b.messages = [];
+        b.nextSeq = 1;
+        delete b.lease;
+        for (const ev of events)
+            applyEvent(b, ev);
+        b.events = Math.max(0, events.length - (b.messages.length + 1 + (b.lease !== undefined ? 1 : 0)));
+        b.mark = now;
+    }
     load(scope, handle) {
         const path = this.boxPath(scope, handle);
         const key = canonicalStoreKey(path);
@@ -79,13 +413,15 @@ export class FileMailboxStore {
                 b.refs++;
                 this.touched.set(key, b);
             }
+            this.reconcile(b);
             return b;
         }
         ensureDir(join(this.dir, sanitizeScope(scope)));
         const events = readJsonlRecords(path, this.discloseCorrupt);
-        const state = { messages: [], nextSeq: 1, log: new AppendLog(path), events: events.length, refs: 1, path };
+        const state = { messages: [], nextSeq: 1, log: new AppendLog(path), events: events.length, refs: 1, path, mark: undefined };
         for (const ev of events)
             applyEvent(state, ev);
+        state.mark = diskMarkOf(path);
         sharedBoxes.set(key, state);
         this.touched.set(key, state);
         return state;
@@ -101,6 +437,7 @@ export class FileMailboxStore {
             catch {
             }
         }
+        b.mark = markAfterWrite(path);
     }
     compact(b, path) {
         const lines = [];
@@ -112,20 +449,29 @@ export class FileMailboxStore {
         b.log.closeForSwap();
         atomicWriteFile(this.tmpDir, path, lines.length ? `${lines.join("\n")}\n` : "");
         b.events = 0;
+        b.mark = markAfterWrite(path);
     }
     async append(scope, handle, msg) {
         if (scope === undefined || scope === "")
             throw new Error("MailboxStore.append: refusing a message without a scope");
-        return withPathLock(this.lockKey(scope, handle), () => {
+        const peerMeta = readMailboxPeerMeta(msg.peerMeta);
+        return this.withBox(this.lockKey(scope, handle), this.boxPath(scope, handle), () => {
             const b = this.load(scope, handle);
             const seq = b.nextSeq;
-            const m = { seq, ...(msg.from !== undefined ? { from: msg.from } : {}), content: msg.content, sentAt: msg.sentAt, ...(msg.hopChain !== undefined ? { hopChain: [...msg.hopChain] } : {}) };
+            const m = {
+                seq,
+                ...(msg.from !== undefined ? { from: msg.from } : {}),
+                content: msg.content,
+                sentAt: msg.sentAt,
+                ...(msg.hopChain !== undefined ? { hopChain: [...msg.hopChain] } : {}),
+                ...(peerMeta !== undefined ? { peerMeta } : {}),
+            };
             this.commit(b, this.boxPath(scope, handle), { t: "append", m });
             return seq;
         });
     }
     async claimLease(scope, handle, owner, ttlMs, now = Date.now()) {
-        return withPathLock(this.lockKey(scope, handle), () => {
+        return this.withBox(this.lockKey(scope, handle), this.boxPath(scope, handle), () => {
             const b = this.load(scope, handle);
             if (b.messages.length === 0)
                 return null;
@@ -133,11 +479,11 @@ export class FileMailboxStore {
                 return null;
             const maxSeq = b.messages[b.messages.length - 1].seq;
             this.commit(b, this.boxPath(scope, handle), { t: "lease", owner, expiresAt: now + ttlMs, maxSeq });
-            return { messages: b.messages.map((m) => ({ ...m, ...(m.hopChain !== undefined ? { hopChain: [...m.hopChain] } : {}) })), maxSeq };
+            return { messages: b.messages.map((m) => detachMailboxMessage(m)), maxSeq };
         });
     }
     async ack(scope, handle, owner, upToSeq) {
-        return withPathLock(this.lockKey(scope, handle), () => {
+        return this.withBox(this.lockKey(scope, handle), this.boxPath(scope, handle), () => {
             const b = this.load(scope, handle);
             if (b.lease === undefined || b.lease.owner !== owner)
                 return;
@@ -145,7 +491,7 @@ export class FileMailboxStore {
         });
     }
     async releaseLease(scope, handle, owner) {
-        return withPathLock(this.lockKey(scope, handle), () => {
+        return this.withBox(this.lockKey(scope, handle), this.boxPath(scope, handle), () => {
             const b = this.load(scope, handle);
             if (b.lease?.owner === owner)
                 this.commit(b, this.boxPath(scope, handle), { t: "release", owner });
@@ -154,8 +500,9 @@ export class FileMailboxStore {
     async peekCount(scope, handle) {
         const path = this.boxPath(scope, handle);
         const loaded = sharedBoxes.get(canonicalStoreKey(path));
-        if (loaded !== undefined)
+        if (loaded !== undefined && sameDiskMark(diskMarkOf(path), loaded.mark)) {
             return withPathLock(this.lockKey(scope, handle), () => loaded.messages.length);
+        }
         if (!existsSync(path))
             return 0;
         return withPathLock(this.lockKey(scope, handle), () => {
@@ -166,9 +513,9 @@ export class FileMailboxStore {
         });
     }
     async drop(scope, handle) {
-        return withPathLock(this.lockKey(scope, handle), () => {
-            const path = this.boxPath(scope, handle);
-            const key = canonicalStoreKey(path);
+        const path = this.boxPath(scope, handle);
+        const key = canonicalStoreKey(path);
+        return this.withBox(key, path, () => {
             const b = sharedBoxes.get(key);
             if (b) {
                 b.log.close();
@@ -180,6 +527,7 @@ export class FileMailboxStore {
     }
     async reap(scope, now, opts) {
         assertRetentionPolicy("MailboxStore.reap", opts);
+        sweepLockResidue(join(this.dir, sanitizeScope(scope)));
         if (opts?.maxAgeMs === undefined)
             return 0;
         let dropped = 0;
@@ -189,13 +537,16 @@ export class FileMailboxStore {
         for (const [key, b] of [...sharedBoxes]) {
             if (!b.path.startsWith(prefix))
                 continue;
-            const seen = newestSentAt(b.messages);
-            if (seen === undefined || seen >= now - maxAgeMs)
-                continue;
-            const swept = await withPathLock(key, () => {
+            if (sameDiskMark(diskMarkOf(b.path), b.mark)) {
+                const seen = newestSentAt(b.messages);
+                if (seen === undefined || seen >= now - maxAgeMs)
+                    continue;
+            }
+            const swept = await this.withBox(key, b.path, () => {
                 const live = sharedBoxes.get(key);
                 if (live === undefined || live !== b)
                     return false;
+                this.reconcile(b);
                 const newest = newestSentAt(b.messages);
                 if (newest === undefined || newest >= now - maxAgeMs)
                     return false;
@@ -212,7 +563,7 @@ export class FileMailboxStore {
             const key = canonicalStoreKey(path);
             if (sharedBoxes.has(key))
                 continue;
-            const swept = await withPathLock(key, () => {
+            const swept = await this.withBox(key, path, () => {
                 if (sharedBoxes.has(key))
                     return false;
                 const b = { messages: [], nextSeq: 1 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.1.0",
+  "version": "7.3.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",