pi-proactive 0.0.0-stage → 0.2.0-beta.2

package/build/src/mailbox.js

@@ -0,0 +1,984 @@
+/**
+ * `src/mailbox.ts` —— 收件侧文件邮箱（M4c：扫描 / 原子认领 / 过期归档 / 去重闭环 / 清理）。
+ *
+ * 契约（与 M4b `src/outbox.ts` 的写入端通过**目录布局 + 信封格式**耦合，两者不互相 import）：
+ * - 收件箱：`<agentDir>/proactive/mailbox/<targetAgentId>/<envelopeId>.json`（M4b 原子写 tmp+rename）
+ * - 认领：把收件箱里的信封 `rename` 到 `mailbox/<target>/claimed/<id>.json` —— 同目录 rename 是原子的，
+ *   **rename 成功者即获得处理权**；同时用 `proactive/mailbox/claims/<id>.lock`（O_EXCL 原子创建）做二次互斥与审计。
+ *   （锁文件与 task-store 的 global 任务锁 `proactive/tasks/claims/<id>.claim` **分属两个命名空间**，互不误删。）
+ * - 归档：处理成功 → `proactive/processed/<agentId>/<id>.json`；已处理（SeenSet 命中）的重复投递 → 同样落到这里。
+ * - 过期：`mailbox/<target>/expired/<id>.json`（**归档不删**，可审计）。
+ * - 坏文件：`mailbox/<target>/corrupt/<id>.corrupt-<ts>`（隔离不删，绝不抛错 —— 宿主对未捕获异常直接 exit(1)）。
+ *
+ * 所有操作**绝不抛出**给调用方的 tick 循环（除显式的编程错误）：读盘/解析/移动失败一律降级处理。
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { PROACTIVE_FILE_MODE, chmodQuiet, containedPath, ensureDir, isKnownOnDiskVersion, onDiskVersionOf, proactiveDir, reportForeignVersion, resolveAgentDir, writeAtomicFile, } from "./config.js";
+import { MAX_ENVELOPE_BYTES, agentSegment, isExpired, isWellFormedId, validateEnvelopeStrict } from "./envelope.js";
+import { SeenSet } from "./dedupe.js";
+/**
+ * **单轮扫描最多投递多少条信封**（洪水攻击的上限）。
+ *
+ * 超出部分**留在收件箱**（不丢、不归档）→ 下一轮继续处理（背压，而不是拒收）。
+ * 50 条/轮：远高于正常协作速率，又保证「一个 flood 也不能一轮把对端打爆」。
+ */
+export const DEFAULT_MAX_ENVELOPES_PER_SCAN = 50;
+/** 认领锁的默认失效时长（ms）：超过则视为持有者已崩溃，允许接管。 */
+export const DEFAULT_STALE_CLAIM_MS = 3_600_000;
+/**
+ * **墙钟回拨容忍窗口**（ms，**真实时间**）—— 偏差 P-D8 的具体规则。
+ *
+ * 规范要求（§7.3）：TTL 判定必须对墙钟回拨有容忍窗口 ——「回拨时不得让消息提前过期
+ * **或**无限延长」。
+ * 本实现的规则（三条，缺一不可）：
+ * 1. **不提前过期**：`now < createdAt`（墙钟被回拨 / 与发送方时钟偏斜）→ **不判过期**，
+ *    信封留在收件箱（丢消息不可逆，暂缓投递可逆）。
+ * 2. **不得无限延长**：回拨被观测到后，该信封的**额外滞留**以**真实时间**计
+ *    （`process.hrtime`，不受墙钟回拨影响）→ 超过本窗口仍未过期 → **判过期**并归档到 `expired/`。
+ *    ⇒ 回拨最多让一条消息多活 `CLOCK_ROLLBACK_TOLERANCE_MS`（默认 5 分钟真实时间）。
+ * 3. **代价已知**：规则 2 意味着「回拨期间处于异常的信封，最坏会比 TTL 名义值早到期至多一个窗口」
+ *    —— 这是**有界**的、且是规范明确要求用「容忍窗口」来交换的偏差
+ *    （比「无限延长」或「无界提前过期」都安全）。窗口可调（`MailboxOptions.clockRollbackToleranceMs`）。
+ *
+ * 残余限制：窗口按**进程**计（进程重启后重新计时）；跨机器的时钟偏斜不在本机控制范围内。
+ */
+export const CLOCK_ROLLBACK_TOLERANCE_MS = 5 * 60_000;
+/** 真实时间源（不受墙钟回拨影响）：以模块加载时刻为基准的 `process.hrtime` 毫秒数。 */
+const HRT_BASE_NS = process.hrtime.bigint();
+function realNowMs() {
+    return Number(process.hrtime.bigint() - HRT_BASE_NS) / 1e6;
+}
+/**
+ * 默认最大**失败重试**次数：同一信封连续失败重试超过 N 次 → 归档到终态目录 `failed/`。
+ *
+ * 为什么必须有上限：`release()` 把信封放回收件箱，而入站扫描由 1s tick 驱动 →
+ * 没有上限时「投递持续失败」的信封会**每秒**被重新认领、重新投递、再次失败
+ * （无界热重试：CPU/日志无限增长，消息永远进不了模型、也永远不被归档）。
+ */
+export const DEFAULT_MAX_RETRIES = 5;
+/** 失败重试的退避基数（ms）：第 n 次失败 → base × 2^(n-1)。 */
+export const DEFAULT_RETRY_BASE_MS = 5_000;
+/** 退避上限（ms）：任何形态的退避都不得超过它（**有界**是硬要求）。 */
+export const DEFAULT_RETRY_MAX_MS = 300_000;
+/** 节流重试（defer/drop）的退避基数（ms）：节流是「等一会儿」，不是错误。 */
+export const DEFAULT_THROTTLE_BASE_MS = 60_000;
+/**
+ * claim 文件内容首段标记：区分「邮箱的锁」与 task-store 的「global 任务锁」。
+ *
+ * 两者现在**分属不同目录**（`mailbox/claims/*.lock` vs `tasks/claims/*.claim`），
+ * 标记只用于「锁归属审计」：清理时只删**归本 agent 所有**的锁，不碰别人的。
+ */
+export const CLAIM_MARKER = "mailbox";
+/**
+ * 收件侧文件邮箱。
+ *
+ * 语义：
+ * - `scan()` 只返回**本 agent 收件箱**里可处理的信封：过期 → 归档到 `expired/`；已处理 → 落到 `processed/`；
+ *   坏文件 → 隔离到 `corrupt/`。三者都不在返回列表里。
+ * - `claim()` 是**互斥**的：先查 `seen`（已处理 → 不认领），再用 claim 文件 O_EXCL 抢锁，
+ *   最后用 `rename` 把信封移入 `claimed/`（rename 成功者才真正拥有该消息）。
+ * - `complete()` 处理成功：信封 → `processed/<agentId>/`，并 `SeenSet.mark(id)`。
+ * - `release()` 处理未成功：信封**退回收件箱**（可重试，**不丢消息**），并释放 claim 锁。
+ *   但重试**必须有界**（否则 1s tick 会把它每秒重新认领重试 → 重试风暴）：
+ *   ① 退避（记录下次可重试时刻，`scan()` 跳过未到时刻的信封）；
+ *   ② 失败重试次数上限（超过 → 归档到终态目录 `failed/`，**不删**、可审计）；
+ *   ③ 节流（defer/drop）不是错误 → 不计入失败上限。
+ */
+export class Mailbox {
+    agentDir;
+    agentId;
+    now;
+    seen;
+    staleClaimMs;
+    maxRetries;
+    retryBaseMs;
+    retryMaxMs;
+    throttleBaseMs;
+    /** 墙钟回拨容忍窗口（ms，真实时间）。 */
+    clockRollbackToleranceMs;
+    /** 真实时间源（不受墙钟回拨影响）。 */
+    realNow;
+    /** 「回拨异常信封」已滞留的真实时长（ms，按信封 id 记）—— P-D8 规则 2 的计时。 */
+    rollbackSince = new Map();
+    /** 来源校验策略（**必填**：构造时缺省即抛错，不静默宽松）。 */
+    senderPolicy;
+    /** 单轮扫描的投递上限（洪水上限）。 */
+    maxEnvelopesPerScan;
+    /** 收件箱目录（构造时做**包含性校验** → 越界即抛错，不静默）。 */
+    inboxRoot;
+    constructor(opts) {
+        this.agentDir = opts.agentDir ?? resolveAgentDir();
+        this.agentId = opts.agentId;
+        this.now = opts.now ?? Date.now;
+        this.seen = opts.seen ?? new SeenSet({ agentDir: this.agentDir, agentId: this.agentId, now: this.now });
+        this.staleClaimMs = opts.staleClaimMs ?? DEFAULT_STALE_CLAIM_MS;
+        this.maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.retryBaseMs = opts.retryBaseMs ?? DEFAULT_RETRY_BASE_MS;
+        this.retryMaxMs = opts.retryMaxMs ?? DEFAULT_RETRY_MAX_MS;
+        this.throttleBaseMs = opts.throttleBaseMs ?? DEFAULT_THROTTLE_BASE_MS;
+        if (typeof opts.senderPolicy !== "function") {
+            // **缺省即抛错**（不静默宽松）：来源校验是安全边界，漏传 = 悄悄关掉它。
+            throw new Error("Mailbox 必须显式指定 senderPolicy（缺省即抛错）：" +
+                "createStrictSenderPolicy()（注册表白名单 ＋ 主机一致）或 " +
+                "createSpecSenderPolicy()（仅字段级校验；跨机 / 互操作用）");
+        }
+        this.senderPolicy = opts.senderPolicy;
+        this.maxEnvelopesPerScan = opts.maxEnvelopesPerScan ?? DEFAULT_MAX_ENVELOPES_PER_SCAN;
+        // **包含性校验**：`agentId` 是外部可控的（`agentSegment()` 不动点号）→
+        // `agentId = ".."` 会让收件箱目录逃到 `proactive/`（进而把 `proactive/config.json`
+        // 当成信封处理掉）。越界 → **抛错**（不静默）。
+        this.inboxRoot = containedPath(path.join(proactiveDir(this.agentDir), "mailbox"), agentSegment(this.agentId));
+        this.clockRollbackToleranceMs = opts.clockRollbackToleranceMs ?? CLOCK_ROLLBACK_TOLERANCE_MS;
+        this.realNow = opts.realNow ?? realNowMs;
+    }
+    /** 本 agent 的收件箱目录（构造时已做包含性校验）。 */
+    get inboxDir() {
+        return this.inboxRoot;
+    }
+    /** 已认领（处理中）目录。 */
+    get claimedDir() {
+        return path.join(this.inboxDir, "claimed");
+    }
+    /** 过期归档目录。 */
+    get expiredDir() {
+        return path.join(this.inboxDir, "expired");
+    }
+    /** 坏文件隔离目录。 */
+    get corruptDir() {
+        return path.join(this.inboxDir, "corrupt");
+    }
+    /**
+     * **来源校验未通过**的归档目录（RELSEC P1）。
+     *
+     * 语义：**拒收但留痕** —— 信封移到这里（不删、不投递到模型），
+     * 旁边写一份 `<id>.reject.json`（原因 / 时刻 / 原始 from）→ 可审计。
+     */
+    get unverifiedDir() {
+        return path.join(this.inboxDir, "unverified");
+    }
+    /**
+     * 终态归档目录（重试耗尽 → 归档到这里，**不丢、可审计**）。
+     *
+     * 与 `expired/` / `corrupt/` 同构：归档而非删除 —— 能查「哪条消息彻底没投出去」。
+     */
+    get failedDir() {
+        return path.join(this.inboxDir, "failed");
+    }
+    /** 重试状态目录（退避时刻与计数；与信封文件分离 → 信封格式保持纯净）。 */
+    get retryDir() {
+        return path.join(this.inboxDir, "retry");
+    }
+    /**
+     * 该信封已**失败重试**的次数（0 = 没失败过 / 只被节流过）。
+     *
+     * 节流（defer/drop）不计入 —— 它是节流，不是错误。
+     */
+    releaseCount(id) {
+        return this.readRetryState(id)?.retryCount ?? 0;
+    }
+    /** 已处理归档目录（与 `seen.json` 同目录）。 */
+    get processedDir() {
+        return path.join(proactiveDir(this.agentDir), "processed", agentSegment(this.agentId));
+    }
+    /**
+     * claim 锁目录：**与 task-store 的 global 任务锁分开**（RP-9）。
+     *
+     * 旧实现两者同目录同文件名（`proactive/tasks/<id>.claim`）→ 邮箱清理会删掉
+     * task-store 的任务锁（反之亦然）→ 互斥语义被破坏。
+     * 现在：邮箱锁 = `proactive/mailbox/claims/<id>.lock`，任务锁 = `proactive/tasks/claims/<id>.claim`。
+     */
+    get claimsDir() {
+        return path.join(proactiveDir(this.agentDir), "mailbox", "claims");
+    }
+    /**
+     * 扫描收件箱，返回**可处理**的信封列表（已过期 / 已处理 / 坏文件的都已被移走）。
+     * 只读本 agent 自己的收件箱；其它 agent 的目录完全不被触碰。
+     */
+    scan() {
+        // P-D3：先把「卡在 claimed/ 里」的孤儿信封回收（认领年龄 ≥ 1 小时 → 移回收件箱）。
+        this.recoverStaleClaims();
+        const out = [];
+        const now = this.now();
+        for (const name of readDirSafe(this.inboxDir)) {
+            if (!name.endsWith(".json"))
+                continue;
+            const file = path.join(this.inboxDir, name);
+            // **体积上限**（本地 IPC 攻击面：超大 body）——**先看大小再读**：
+            // 读进内存再判断 = 已经被打爆过一次了。超限 → 隔离（不读、不投递）。
+            const size = fileSize(file);
+            if (size !== null && size > MAX_ENVELOPE_BYTES) {
+                this.quarantine(file, name);
+                continue;
+            }
+            const raw = readFileSafe(file);
+            if (raw === null) {
+                this.quarantine(file, name);
+                continue;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                this.quarantine(file, name);
+                continue;
+            }
+            // 信任边界：**严格**校验（封闭字段集 / 可选字段类型 / reply 必带 correlationId）
+            // —— 与参考对端（按 JSON Schema 实现）逐条一致。
+            const validation = validateEnvelopeStrict(parsed);
+            if (!validation.ok) {
+                this.quarantine(file, name);
+                continue;
+            }
+            const envelope = validation.envelope;
+            // **id 结构性合法性**：id 会被拼进文件名（`agentSegment()` 只换分隔符、不动点号）→
+            // 含 `../` / 绝对路径形状的 id 一律**隔离**（不投递、不参与任何路径拼接）。
+            if (!isWellFormedId(envelope.id)) {
+                this.quarantine(file, name);
+                continue;
+            }
+            // 先查 seen 再判过期：重复投递（socket + 落盘双路径 / 崩溃后重投）落到 processed/，
+            // 而不是因为信封本身已过期被误判成 expired/。
+            if (this.seen.seen(envelope.id)) {
+                moveFile(file, path.join(this.processedDir, `${agentSegment(envelope.id)}.json`));
+                this.clearRetryState(envelope.id);
+                continue;
+            }
+            // P-D8（规范 §7.3①）：TTL 判定只接受「时间向前走」的证据 ——
+            // `now < createdAt`（墙钟被回拨）时**不判过期**（保留，等时钟追上）。
+            // 理由：丢消息不可逆，暂缓投递可逆。
+            if (now >= envelope.createdAt && isExpired(envelope, now)) {
+                moveFile(file, path.join(this.expiredDir, name));
+                this.clearRetryState(envelope.id);
+                this.rollbackSince.delete(envelope.id);
+                continue;
+            }
+            if (now < envelope.createdAt) {
+                // P-D8 规则 2：**不得无限延长** —— 回拨期间滞留以**真实时间**计，
+                // 超过容忍窗口（默认 5 分钟真实时间）→ 判过期（TTL 视为已到）。
+                // 见 `CLOCK_ROLLBACK_TOLERANCE_MS` 的完整规则说明。
+                const since = this.rollbackSince.get(envelope.id);
+                if (since === undefined) {
+                    this.rollbackSince.set(envelope.id, this.realNow());
+                }
+                else if (this.realNow() - since >= this.clockRollbackToleranceMs) {
+                    moveFile(file, path.join(this.expiredDir, name));
+                    this.clearRetryState(envelope.id);
+                    this.rollbackSince.delete(envelope.id);
+                    continue;
+                }
+                // 未超窗 → **不提前过期**（保留，等时钟追上；下面照常进入处理队列）
+            }
+            else {
+                // 时钟恢复正常：该信封不再是「回拨异常」→ 清掉计时。
+                this.rollbackSince.delete(envelope.id);
+            }
+            // **退避**：未到重试时刻的信封本轮不重试
+            // （否则 1s tick 会把它每秒重新认领、重新投递、再次失败 → 重试风暴）。
+            const retryState = this.readRetryState(envelope.id);
+            // P-D8（规范 §7.3③）：退避用墙钟存储（跨进程需要），判定要求
+            // 「now ≥ nextAttemptAt」**且**「now ≥ lastAt」——时钟回拨（now < lastAt）
+            // 时**不重试**（等时钟追上），避免回拨瞬间的退避到期 → 重试风暴。
+            if (retryState && retryState.nextAttemptAt > now && now >= retryState.lastAt)
+                continue;
+            // **来源校验（RELSEC P1）**：`from` 不可自填即采信。
+            // 未通过 → **拒收**（不投递到模型）+ **可审计归档**（`unverified/`），
+            // 绝不静默丢弃，也绝不「降级为 advisory 照样投递」。
+            const verdict = this.senderPolicy(envelope);
+            if (!verdict.ok) {
+                this.archiveUnverified(file, envelope, verdict);
+                continue;
+            }
+            out.push(envelope);
+            // **洪水上限**：单轮最多投递 N 条，其余**留在收件箱**（不丢）→ 下一轮继续（背压）。
+            if (out.length >= this.maxEnvelopesPerScan)
+                break;
+        }
+        return out;
+    }
+    /**
+     * 原子认领：获得该信封的**处理权**。
+     * - 已处理（`seen`）→ `{ claimed:false, reason:"seen" }`；
+     * - 已有他人持有的有效 claim 锁 → `{ claimed:false, reason:"locked" }`；
+     * - 收件箱里已无此信封（已被他人认领）→ `{ claimed:false, reason:"missing" }`；
+     * - 成功 → 信封在 `mailbox/<target>/claimed/<id>.json`，返回 `{ claimed:true, path }`。
+     */
+    claim(envelope) {
+        if (this.seen.seen(envelope.id))
+            return { claimed: false, reason: "seen" };
+        const source = this.locateInboxFile(envelope.id);
+        if (!source)
+            return { claimed: false, reason: "missing" };
+        const claimFile = this.claimPath(envelope.id);
+        const lock = this.acquireClaimLock(claimFile);
+        if (!lock.proceed)
+            return { claimed: false, reason: "locked" };
+        const target = path.join(this.claimedDir, `${agentSegment(envelope.id)}.json`);
+        if (!moveFile(source, target)) {
+            // rename 失败（多半是别人抢先认领）→ 释放锁，让对方继续
+            if (lock.owned)
+                removeFile(claimFile);
+            return { claimed: false, reason: "error" };
+        }
+        // 认领时刻 = mtime（rename 保留原 mtime → 不刷新的话「认领年龄」会算成「信封年龄」，
+        // 一条很旧但刚被认领的信封会被误判成卡死 → 提前回收 → 可能重复处理）。
+        try {
+            fs.utimesSync(target, this.now(), this.now());
+        }
+        catch {
+            // 刷新失败不影响认领（退回用认领锁里的 ts 判龄）
+        }
+        return { claimed: true, path: target };
+    }
+    /**
+     * 处理成功：信封归档到 `processed/<agentId>/`，并记入 seen 集合。
+     * 归档失败**不抛错**（信封仍在 `claimed/`，可由 `cleanup()` 回收）。
+     */
+    complete(envelope) {
+        const from = path.join(this.claimedDir, `${agentSegment(envelope.id)}.json`);
+        moveFile(from, path.join(this.processedDir, `${agentSegment(envelope.id)}.json`));
+        this.seen.mark(envelope.id);
+        this.clearRetryState(envelope.id);
+        this.releaseClaimFile(envelope.id);
+    }
+    /**
+     * 处理未成功：信封**退回收件箱**（可被再次扫描到 → 可重试），并释放 claim 锁。
+     * **绝不丢消息**。
+     *
+     * 但**必须有界**（否则入站 1s tick 会把它每秒重新认领重试 → 重试风暴）：
+     * - **退避**：记录「下次可重试时刻」，`scan()` 跳过未到时刻的信封；
+     * - **上限**：`failed` 连续重试超过 `maxRetries` 次 → 归档到终态目录 `failed/`（**不删**，可审计）；
+     * - **节流 ≠ 错误**：`deferred`/`dropped` 不计入失败上限（只影响退避时长）。
+     */
+    release(envelope, opts) {
+        const reason = opts?.reason ?? "failed";
+        const prev = this.readRetryState(envelope.id);
+        const retryCount = reason === "failed" ? (prev?.retryCount ?? 0) + 1 : (prev?.retryCount ?? 0);
+        const throttleCount = reason === "throttled" ? (prev?.throttleCount ?? 0) + 1 : (prev?.throttleCount ?? 0);
+        const from = path.join(this.claimedDir, `${agentSegment(envelope.id)}.json`);
+        // 超过失败重试上限 → 终态归档（**不丢**：留在 `failed/` 里可审计）
+        if (reason === "failed" && retryCount > this.maxRetries) {
+            const archived = moveFile(from, path.join(this.failedDir, `${agentSegment(envelope.id)}.json`));
+            this.releaseClaimFile(envelope.id);
+            this.clearRetryState(envelope.id);
+            if (archived) {
+                console.error(`[mailbox] 信封 ${envelope.id} 重试 ${retryCount - 1} 次仍失败 → 归档到 failed/（不再重试）`);
+            }
+            return { released: false, archived, retryCount, nextAttemptAt: 0 };
+        }
+        const backoffMs = opts?.retryAfterMs ?? this.backoffMs(reason, retryCount, throttleCount);
+        const nextAttemptAt = this.now() + backoffMs;
+        this.writeRetryState({
+            id: envelope.id,
+            retryCount,
+            throttleCount,
+            nextAttemptAt,
+            lastReason: reason,
+            lastAt: this.now(),
+        });
+        moveFile(from, path.join(this.inboxDir, `${agentSegment(envelope.id)}.json`));
+        this.releaseClaimFile(envelope.id);
+        return { released: true, archived: false, retryCount, nextAttemptAt };
+    }
+    /**
+     * 扫描 → 认领 → 交给 `handler` 处理 → 归档 / 退回 的完整一轮。
+     * `handler` 抛错 ⇒ 该信封退回收件箱（不丢消息），其余信封继续处理。
+     */
+    deliver(handler) {
+        const result = { processed: 0, failed: 0, skipped: 0 };
+        for (const envelope of this.scan()) {
+            const claim = this.claim(envelope);
+            if (!claim.claimed) {
+                result.skipped += 1;
+                continue;
+            }
+            try {
+                handler(envelope);
+            }
+            catch {
+                this.release(envelope, { reason: "failed" });
+                result.failed += 1;
+                continue;
+            }
+            this.complete(envelope);
+            result.processed += 1;
+        }
+        return result;
+    }
+    /**
+     * `deliver()` 的异步版本（`handler` 可返回 Promise；reject 等同抛错 → 退回收件箱）。
+     */
+    async deliverAsync(handler) {
+        const result = { processed: 0, failed: 0, skipped: 0 };
+        for (const envelope of this.scan()) {
+            const claim = this.claim(envelope);
+            if (!claim.claimed) {
+                result.skipped += 1;
+                continue;
+            }
+            try {
+                await handler(envelope);
+            }
+            catch {
+                this.release(envelope, { reason: "failed" });
+                result.failed += 1;
+                continue;
+            }
+            this.complete(envelope);
+            result.processed += 1;
+        }
+        return result;
+    }
+    /**
+     * 过期清理：**只清本 agent 自己的目录**（收件箱 / claimed / expired / processed / 自己的 claim 文件）。
+     * - 收件箱与 claimed 里的旧信封 → 归档到 `expired/`（不删，可审计）；
+     * - `processed/` 里的旧归档 → 删除；
+     * - 自己的旧 claim 锁 → 删除（别人的 claim 文件**不碰**）。
+     * 年龄判定：信封用 `createdAt`（语义年龄），其余文件（claim 锁 / 坏文件）用 mtime。
+     */
+    cleanup(options) {
+        const result = { removed: 0, archived: 0, claimsRemoved: 0 };
+        const olderThanMs = options.olderThanMs;
+        // P-D3：回收「卡在 claimed/ 里」的孤儿信封（认领年龄 ≥ 1 小时 → 移回收件箱，可重处理）。
+        this.recoverStaleClaims();
+        // P-D2：回收残留 tmp（mtime > 1 小时）—— 阈值**不随** `olderThanMs` 变
+        // （规范 §6 阈值表固定为「tmp mtime > 1 小时」；`olderThanMs` 是信封/归档的年龄口径）。
+        result.removed += gcStaleTemporaries(this.agentDir, { now: this.now }).length;
+        // 先扫 expired/（删掉往轮遗留的超龄归档），再把本轮超龄的收件箱/认领中文件归档进去 ——
+        // 归档物本轮不会被自己删掉（否则「归档可审计」名存实亡）。
+        for (const name of readDirSafe(this.expiredDir)) {
+            const file = path.join(this.expiredDir, name);
+            if (!isFile(file))
+                continue;
+            if (this.ageOf(file) > olderThanMs && removeFile(file))
+                result.removed += 1;
+        }
+        // 收件箱/claimed：只有「超龄**且**已过 TTL」的信封才归档 —— 仍有效的消息绝不因清理而丢失。
+        for (const dir of [this.inboxDir, this.claimedDir]) {
+            for (const name of readDirSafe(dir)) {
+                const file = path.join(dir, name);
+                if (!isFile(file))
+                    continue;
+                if (this.ageOf(file) <= olderThanMs)
+                    continue;
+                if (!this.isDeadEnvelope(file))
+                    continue;
+                if (moveFile(file, path.join(this.expiredDir, name))) {
+                    result.archived += 1;
+                    result.removed += 1;
+                }
+            }
+        }
+        // **来源校验未通过的归档**（RELSEC P1）：超龄即删（否则「拒收但留痕」会变成磁盘增长面）。
+        for (const name of readDirSafe(this.unverifiedDir)) {
+            const file = path.join(this.unverifiedDir, name);
+            if (!isFile(file))
+                continue;
+            if (this.ageOf(file) > olderThanMs && removeFile(file))
+                result.removed += 1;
+        }
+        for (const name of readDirSafe(this.processedDir)) {
+            if (name === "seen.json" || name.startsWith("seen.json."))
+                continue; // seen 集合不清理
+            const file = path.join(this.processedDir, name);
+            if (!isFile(file))
+                continue;
+            if (this.ageOf(file) > olderThanMs && removeFile(file))
+                result.removed += 1;
+        }
+        for (const name of readDirSafe(this.claimsDir)) {
+            if (!name.endsWith(".lock"))
+                continue;
+            const file = path.join(this.claimsDir, name);
+            if (!isFile(file))
+                continue;
+            if (!this.ownsClaim(file))
+                continue; // 别人的锁不碰
+            if (this.ageOf(file) > olderThanMs && removeFile(file)) {
+                result.claimsRemoved += 1;
+                result.removed += 1;
+            }
+        }
+        // 重试状态文件：对应的信封已不在收件箱/认领中（已归档 / 已完成 / 已过期）→ 一并清理，避免残留。
+        for (const name of readDirSafe(this.retryDir)) {
+            if (!name.endsWith(".json"))
+                continue;
+            const file = path.join(this.retryDir, name);
+            if (!isFile(file))
+                continue;
+            const base = name.replace(/\.json$/, "");
+            const stillPending = isFile(path.join(this.inboxDir, `${base}.json`)) || isFile(path.join(this.claimedDir, `${base}.json`));
+            if (!stillPending && removeFile(file))
+                result.removed += 1;
+        }
+        return result;
+    }
+    // ---- 内部实现 ----
+    /** claim 锁文件路径（邮箱命名空间：`.lock` 后缀）。 */
+    claimPath(id) {
+        return path.join(this.claimsDir, `${agentSegment(id)}.lock`);
+    }
+    /** 在收件箱里定位某 id 的信封文件（优先按约定文件名，其次按内容匹配）。 */
+    locateInboxFile(id) {
+        const conventional = path.join(this.inboxDir, `${agentSegment(id)}.json`);
+        if (isFile(conventional))
+            return conventional;
+        for (const name of readDirSafe(this.inboxDir)) {
+            if (!name.endsWith(".json"))
+                continue;
+            const file = path.join(this.inboxDir, name);
+            const raw = readFileSafe(file);
+            if (raw === null)
+                continue;
+            try {
+                const parsed = JSON.parse(raw);
+                if (typeof parsed === "object" && parsed !== null && parsed.id === id) {
+                    return file;
+                }
+            }
+            catch {
+                // 坏文件跳过（scan 会隔离它）
+            }
+        }
+        return null;
+    }
+    /**
+     * 抢 claim 锁（O_EXCL 原子创建）。
+     * - 锁不存在 → 创建成功（**owned=true**，处理完由我们删除）。
+     * - 锁存在且属于**别的 agent** → 那把锁约束的是对方收件箱里的同名信封，与我们无关 → 放行但**不写锁**
+     *   （不覆盖、不删除对方的锁文件）；真正的互斥由 rename 保证。
+     * - 锁存在且属于**本 agent** 且未失效 → 抢不到（`locked`）：同一 agent 的另一个进程正在处理。
+     * - 锁属于本 agent 但已失效（持有者崩溃）→ 接管（删旧锁重新创建）。
+     */
+    acquireClaimLock(claimFile) {
+        ensureDir(path.dirname(claimFile));
+        const write = () => {
+            const fd = fs.openSync(claimFile, "wx");
+            try {
+                // 内容格式：`mailbox <agentId> <ts>` —— 首段标记本锁属于**邮箱**
+                // （与 task-store 的 global 任务 claim `<agentId> <ts>` 区分；两者目录已分离）。
+                fs.writeFileSync(fd, `${CLAIM_MARKER} ${this.agentId} ${this.now()}\n`, "utf8");
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            // 认领锁属「同机其它进程不该读」的落盘面 → 0600（规范 P0）。
+            chmodQuiet(claimFile, PROACTIVE_FILE_MODE);
+        };
+        try {
+            write();
+            return { proceed: true, owned: true };
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                return { proceed: false, owned: false };
+        }
+        // 已存在
+        const content = readFileSafe(claimFile);
+        if (content === null)
+            return { proceed: false, owned: false };
+        const parts = content.trim().split(/\s+/);
+        if (parts[0] !== CLAIM_MARKER) {
+            // 不是邮箱的锁（多半是 task-store 的 global 任务 claim）→ 不阻塞、不改写
+            return { proceed: true, owned: false };
+        }
+        const owner = parts[1] ?? "";
+        const ts = Number.parseInt(parts[2] ?? "", 10);
+        if (owner !== this.agentId) {
+            // 别人的锁：不阻塞、不改写（对方的锁文件由对方清理）
+            return { proceed: true, owned: false };
+        }
+        const age = Number.isFinite(ts) ? this.now() - ts : Number.POSITIVE_INFINITY;
+        if (age < this.staleClaimMs)
+            return { proceed: false, owned: false };
+        // 自己 agent 的失效锁 → 接管
+        removeFile(claimFile);
+        try {
+            write();
+            return { proceed: true, owned: true };
+        }
+        catch {
+            return { proceed: false, owned: false };
+        }
+    }
+    /** 只删除**归本 agent 所有**的 claim 文件（不碰别人的锁）。 */
+    releaseClaimFile(id) {
+        const file = this.claimPath(id);
+        if (this.ownsClaim(file))
+            removeFile(file);
+    }
+    /**
+     * 该信封是否已无投递价值：TTL 已过（`isExpired`），或文件本身不是合法信封（坏文件）。
+     * 合法且未过期的消息返回 false —— **清理不得丢弃仍然有效的消息**。
+     */
+    isDeadEnvelope(file) {
+        const raw = readFileSafe(file);
+        if (raw === null)
+            return true;
+        try {
+            const parsed = JSON.parse(raw);
+            const validation = validateEnvelopeStrict(parsed);
+            if (!validation.ok)
+                return true;
+            return isExpired(validation.envelope, this.now());
+        }
+        catch {
+            return true;
+        }
+    }
+    /** 该 claim 文件是否归本 agent 所有。 */
+    ownsClaim(file) {
+        const content = readFileSafe(file);
+        if (content === null)
+            return false;
+        const parts = content.trim().split(/\s+/);
+        return parts[0] === CLAIM_MARKER && parts[1] === this.agentId;
+    }
+    /** 文件年龄判定：信封优先用 `createdAt`（语义年龄），否则用 mtime。 */
+    ageOf(file) {
+        const raw = readFileSafe(file);
+        if (raw !== null) {
+            try {
+                const parsed = JSON.parse(raw);
+                if (typeof parsed === "object" && parsed !== null) {
+                    const createdAt = parsed.createdAt;
+                    if (typeof createdAt === "number" && Number.isFinite(createdAt)) {
+                        return this.now() - createdAt;
+                    }
+                }
+            }
+            catch {
+                // 坏文件退回 mtime
+            }
+        }
+        try {
+            return this.now() - fs.statSync(file).mtimeMs;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /** 重试状态文件路径。 */
+    retryPath(id) {
+        return path.join(this.retryDir, `${agentSegment(id)}.json`);
+    }
+    /** 读重试状态；无状态 / 坏文件 → null（**不抛错**）。 */
+    readRetryState(id) {
+        const raw = readFileSafe(this.retryPath(id));
+        if (raw === null)
+            return null;
+        try {
+            const parsed = JSON.parse(raw);
+            if (typeof parsed !== "object" || parsed === null)
+                return null;
+            // 未知版本 → 拒绝按已知格式解析（规范 V3）→ 当作「无状态」。
+            if (!isKnownOnDiskVersion(onDiskVersionOf(parsed)))
+                return null;
+            const s = parsed;
+            if (typeof s.nextAttemptAt !== "number" || !Number.isFinite(s.nextAttemptAt))
+                return null;
+            return {
+                id,
+                retryCount: typeof s.retryCount === "number" ? s.retryCount : 0,
+                throttleCount: typeof s.throttleCount === "number" ? s.throttleCount : 0,
+                nextAttemptAt: s.nextAttemptAt,
+                lastReason: s.lastReason === "throttled" ? "throttled" : "failed",
+                lastAt: typeof s.lastAt === "number" ? s.lastAt : 0,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 写重试状态（原子：tmp **独占** + 同目录 rename + 0600）。
+     *
+     * 不 fsync：重试记账是**派生**状态（删掉 = 立即重试，规范 §1.4）→ 不值得 fsync。
+     * 未知版本 → **拒绝写入**（不得覆盖原文件，规范 V3②）。
+     */
+    writeRetryState(state) {
+        const file = this.retryPath(state.id);
+        if (this.foreignRetryVersion(file) !== null) {
+            reportForeignVersion("重试 sidecar", file, this.foreignRetryVersion(file));
+            return;
+        }
+        try {
+            writeAtomicFile(file, `${JSON.stringify(state, null, 2)}\n`);
+        }
+        catch {
+            // 写不进去不抛错（退避记账丢失 = 立即重试，仍有 maxRetries 兜底）
+        }
+    }
+    /** 该 sidecar 文件当前是否是**不认识的版本**（是 → 不得覆盖原文件，规范 V3②）。 */
+    foreignRetryVersion(file) {
+        const raw = readFileSafe(file);
+        if (raw === null)
+            return null;
+        try {
+            const version = onDiskVersionOf(JSON.parse(raw));
+            if (isKnownOnDiskVersion(version))
+                return null;
+            return typeof version === "string" ? version : (JSON.stringify(version) ?? "缺失");
+        }
+        catch {
+            return null; // 坏文件不是「未知版本」→ 按无状态处理
+        }
+    }
+    /** 清重试状态（信封已归档 / 已完成 → 不再需要退避信息）。 */
+    clearRetryState(id) {
+        removeFile(this.retryPath(id));
+    }
+    /**
+     * 指数退避时长（ms，**有界**）：第 n 次 → base × 2^(n-1)，封顶 `retryMaxMs`。
+     *
+     * 失败与节流分开计数：节流（defer/drop）不是错误 → 退避更长但**不计入失败上限**。
+     */
+    backoffMs(reason, retryCount, throttleCount) {
+        const attempts = reason === "failed" ? retryCount : throttleCount;
+        const base = reason === "failed" ? this.retryBaseMs : this.throttleBaseMs;
+        const exp = base * 2 ** Math.min(Math.max(attempts, 1) - 1, 16);
+        return Math.min(exp, this.retryMaxMs);
+    }
+    /**
+     * **来源校验未通过 → 拒收并归档**（RELSEC P1）。
+     *
+     * - 信封移入 `unverified/`（**不投递**、**不删**）；
+     * - 写一份 `<id>.reject.json` 旁证（原因 / 时刻 / from / to）；
+     * - `console.error` 上报（宿主的用户可见通道有限 → stderr + 归档双留痕）。
+     */
+    archiveUnverified(file, envelope, verdict) {
+        const reason = verdict.ok ? "unknown" : verdict.reason;
+        const detail = verdict.ok ? "" : verdict.error;
+        const target = path.join(this.unverifiedDir, `${agentSegment(envelope.id)}.json`);
+        moveFile(file, target);
+        archiveUnverifiedEnvelope({
+            agentDir: this.agentDir,
+            agentId: this.agentId,
+            envelope,
+            reason,
+            error: detail,
+            at: this.now(),
+        });
+    }
+    /** 坏文件隔离到 `corrupt/`（保留原 id 便于审计；**不删**）。 */
+    quarantine(file, name) {
+        const base = name.replace(/\.json$/, "");
+        const target = path.join(this.corruptDir, `${base}.corrupt-${this.now()}`);
+        moveFile(file, target);
+    }
+    /**
+     * 回收**认领中卡死**的信封（偏差 P-D3）。
+     *
+     * 实测（规范 §4.2 场景 2）：进程在 `rename` 到 `claimed/` 之后崩溃 → 信封永远卡在
+     * `claimed/`：`scan()` 只扫收件箱（看不到它）、`claim()` 在收件箱里找不到 → `reason:"missing"`、
+     * `cleanup()` 又只在「TTL 也过期」时才归档 → **该消息再也不会被处理**（永久卡死）。
+     *
+     * 回收规则（规范 §6 阈值表「`claimed/` 里的信封 · 邮箱持有者 · 每次 `scan()` · 信封年龄 ≥
+     * 认领锁失效时长（1 小时）」）：认领年龄 ≥ `staleClaimMs` → 回收。
+     *
+     * **重投递 vs 归档（取舍与理由）**：本实现选**重投递（移回收件箱）**。
+     * 归档同样能消除「卡死」，但那条消息就**永远不会被用户看到**（= 功能性丢消息，只是可审计）；
+     * 重投递让它重新可处理，符合「不丢消息」的第一原则。
+     * 代价是「可能重复处理」：原持有者若只是慢（而非崩溃）而最终完成，它会 `seen.mark(id)`
+     * → 重投递的那份在 `scan()` 里命中 `seen` → 落到 `processed/` 而**不被再次处理**；
+     * 为此回收时给重投递的信封写一个**短暂退避**（`retry/` sidecar），
+     * 让还活着的原持有者有机会先落 `seen`（退避到期前 `scan()` 会跳过它）。
+     */
+    recoverStaleClaims() {
+        const now = this.now();
+        let recovered = 0;
+        for (const name of readDirSafe(this.claimedDir)) {
+            if (!name.endsWith(".json"))
+                continue;
+            const file = path.join(this.claimedDir, name);
+            if (!isFile(file))
+                continue;
+            const id = name.replace(/\.json$/, "");
+            // 认领年龄：认领锁里的 ts（权威）→ 认领文件 mtime（认领时刷新过）
+            if (this.claimAge(id, file, now) < this.staleClaimMs)
+                continue;
+            if (!moveFile(file, path.join(this.inboxDir, name)))
+                continue;
+            this.releaseClaimFile(id);
+            this.writeRetryState({
+                id,
+                retryCount: 0,
+                throttleCount: 0,
+                nextAttemptAt: now + DEFAULT_RECOVERY_GRACE_MS,
+                lastReason: "throttled",
+                lastAt: now,
+            });
+            recovered += 1;
+        }
+        return recovered;
+    }
+    /** 认领年龄（ms）：认领锁里的 ts（权威）→ 认领文件的 mtime（认领时刷新过）。 */
+    claimAge(id, file, now) {
+        const content = readFileSafe(this.claimPath(id));
+        if (content !== null) {
+            const parts = content.trim().split(/\s+/);
+            if (parts[0] === CLAIM_MARKER) {
+                const ts = Number.parseInt(parts[2] ?? "", 10);
+                if (Number.isFinite(ts))
+                    return now - ts;
+            }
+        }
+        try {
+            return now - fs.statSync(file).mtimeMs;
+        }
+        catch {
+            return 0;
+        }
+    }
+}
+/** 残留 tmp 的回收阈值（ms）：tmp 文件 mtime > 1 小时即删（规范 §6 阈值表）。 */
+export const DEFAULT_TMP_STALE_MS = 3_600_000;
+/** tmp 文件名判定：`*.tmp`（固定 tmp 名）或 `*.tmp-<pid>-<ts>`（唯一 tmp 名）。 */
+function isTemporaryName(name) {
+    return /\.tmp(-.*)?$/.test(name);
+}
+/** 递归遍历目录下的普通文件（不跟随符号链接；目录不存在 → 什么都不做）。 */
+function walkFiles(dir, visit, depth = 0) {
+    if (depth > 8)
+        return;
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            walkFiles(full, visit, depth + 1);
+        else if (entry.isFile())
+            visit(full);
+    }
+}
+/**
+ * 回收**残留 tmp**（偏差 P-D2）。
+ *
+ * 规范 §6 阈值表：「残留 tmp（全部写点）· 持有 `<proactiveDir>` 的进程 · 每次启动 + 每 1 小时 ·
+ * tmp 文件 mtime > 1 小时 → 删除」。
+ *
+ * 实测（规范 §4.2 场景 1）：崩溃在「tmp 已写、rename 未发生」→ `mailbox/<seg>/<id>.json.tmp-<pid>-<ts>`
+ * 残留，而 `cleanup()` 不删 tmp → **无回收责任方**（磁盘无限增长，且残留内容可能被误当成信封）。
+ *
+ * 覆盖全部写点：`tasks.json.tmp` / `seen.json.tmp` / `config.json.tmp` / `agents/*.tmp` /
+ * `mailbox/<seg>/*.tmp-<pid>-<ts>` / `retry/*.tmp-<pid>`。
+ * 返回被删除的 tmp 路径（**不抛错**）。
+ */
+export function gcStaleTemporaries(agentDir, opts) {
+    const now = opts?.now ?? Date.now;
+    const staleMs = opts?.staleMs ?? DEFAULT_TMP_STALE_MS;
+    const removed = [];
+    walkFiles(proactiveDir(agentDir), (file) => {
+        if (!isTemporaryName(path.basename(file)))
+            return;
+        let mtime;
+        try {
+            mtime = fs.statSync(file).mtimeMs;
+        }
+        catch {
+            return;
+        }
+        if (now() - mtime <= staleMs)
+            return;
+        if (removeFile(file))
+            removed.push(file);
+    });
+    return removed;
+}
+/**
+ * 回收后重投递的**短暂退避**（ms）。
+ *
+ * 为什么需要：回收时原持有者可能只是「慢」而不是崩溃；给它一个窗口去 `seen.mark(id)`，
+ * 重投递的那份就会被去重（落到 `processed/`，不重复处理）。
+ */
+export const DEFAULT_RECOVERY_GRACE_MS = 5_000;
+/** 读目录；目录不存在 → 空数组（**不抛错**）。 */
+function readDirSafe(dir) {
+    try {
+        return fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+/** 读文件；失败 → null（**不抛错**）。 */
+function readFileSafe(file) {
+    try {
+        return fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * **拒收归档**（RELSEC P1）：把来源校验未通过的信封写进 `mailbox/<agent>/unverified/` 并留旁证。
+ *
+ * 邮箱路径与 socket 路径共用（socket 没有「文件可搬」的概念 → 直接写一份归档）。
+ * 返回归档路径（失败 → null）。
+ */
+export function archiveUnverifiedEnvelope(opts) {
+    const dir = containedPath(path.join(proactiveDir(opts.agentDir), "mailbox"), agentSegment(opts.agentId), "unverified");
+    const base = agentSegment(opts.envelope.id);
+    const target = path.join(dir, `${base}.json`);
+    try {
+        writeAtomicFile(target, `${JSON.stringify(opts.envelope, null, 2)}\n`);
+        writeAtomicFile(path.join(dir, `${base}.reject.json`), `${JSON.stringify({
+            id: opts.envelope.id,
+            from: opts.envelope.from,
+            to: opts.envelope.to,
+            reason: opts.reason,
+            detail: opts.error,
+            at: opts.at,
+        }, null, 2)}\n`);
+    }
+    catch {
+        return null;
+    }
+    console.error(`[mailbox] 来源校验未通过（${opts.reason}）→ 拒收并归档：${opts.envelope.id}（from=${opts.envelope.from}）：${opts.error}`);
+    return target;
+}
+/** 读文件大小（失败 → null；**不抛错**）。 */
+function fileSize(file) {
+    try {
+        return fs.statSync(file).size;
+    }
+    catch {
+        return null;
+    }
+}
+/** 是否是普通文件。 */
+function isFile(file) {
+    try {
+        return fs.statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** 移动文件（自动建目标目录）；失败 → false（**不抛错**）。 */
+function moveFile(from, to) {
+    try {
+        ensureDir(path.dirname(to));
+        fs.renameSync(from, to);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** 删除文件；失败 → false（**不抛错**）。 */
+function removeFile(file) {
+    try {
+        fs.unlinkSync(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}