evolcore 0.0.39 → 0.0.40

package/dist/core/memory/memory-writer.js

@@ -35,10 +35,8 @@ export function resolveScopeDirs(scope, taskCtx, ownerAid, peerKeyOverride) {
         const peerKey = peerKeyOverride ?? taskCtx.peerKey;
         if (!peerKey)
             throw new Error('relation 作用域需要 peerKey（当前会话无对端信息）');
-        // 防止路径穿越：peerKey 不能含路径分隔符或 ..
-        if (peerKey.includes('..') || peerKey.includes('/') || peerKey.includes('\\')) {
-            throw new Error(`INVALID_PEER_KEY: peerKey 格式非法: "${peerKey}"`);
-        }
+        // 防止路径穿越：peerKey 不能含路径分隔符或 ..（校验逻辑见 assertPeerKey）
+        assertPeerKey(peerKey);
         const memoryDir = path.join(root, 'agents', selfAid, 'relations', peerKey, 'memory');
         return { memoryDir, consolidatedDir: path.join(memoryDir, 'consolidated') };
     }
@@ -47,11 +45,82 @@ export function resolveScopeDirs(scope, taskCtx, ownerAid, peerKeyOverride) {
     const memoryDir = path.join(root, 'memory', 'owner', ownerAid);
     return { memoryDir, consolidatedDir: path.join(memoryDir, 'consolidated') };
 }
+/**
+ * peerKey 校验。单一实现，避免多处各写一份、强度漂移。
+ *
+ * peerKey 会拼进文件路径，是外部输入面（来自 note 的 speakers、`<peerKey>/consolidated/x.md`
+ * 形式的候选路径），所以这里比"拒 .. / \ / /"更严：空串会让 path.join 折叠成
+ * relations/memory，`C:` 在 Windows 上是 drive-relative，NUL 会截断 fs 调用。
+ */
+export function assertPeerKey(peerKey) {
+    if (!peerKey)
+        throw new Error('INVALID_PEER_KEY: peerKey 不能为空');
+    if (peerKey.length > 128)
+        throw new Error(`INVALID_PEER_KEY: peerKey 过长（${peerKey.length} > 128）`);
+    if (peerKey.includes('..') || peerKey.includes('/') || peerKey.includes('\\')) {
+        throw new Error(`INVALID_PEER_KEY: peerKey 格式非法: "${peerKey}"`);
+    }
+    if (/^[A-Za-z]:/.test(peerKey) || path.isAbsolute(peerKey)) {
+        throw new Error(`INVALID_PEER_KEY: peerKey 不能是绝对路径: "${peerKey}"`);
+    }
+    // 控制字符（含 NUL）会让 fs 调用截断或抛错
+    if (/[\x00-\x1f\x7f]/.test(peerKey)) {
+        throw new Error(`INVALID_PEER_KEY: peerKey 含控制字符: "${peerKey}"`);
+    }
+    return peerKey;
+}
+/** 某个关系的 memory 根：agents/<selfAid>/relations/<peerKey>/memory */
+function relationMemoryDirOf(selfAid, peerKey) {
+    assertPeerKey(peerKey);
+    return path.join(resolveRoot(), 'agents', selfAid, 'relations', peerKey, 'memory');
+}
+/**
+ * 把 `<peerKey>/consolidated/<file>` 形式的路径解析成该关系 consolidated/ 下的绝对路径。
+ *
+ * 这是 generalize / promote 跨层操作本关系源文件的解析原语。与"任意绝对路径"相比，
+ * 它要求路径显式带上来源关系，因此不会有"这是哪个关系"的歧义——同一个
+ * `consolidated/x.md` 在 agent 作用域下会被解析成 agent 级的同名文件，改错对象
+ * 还不报错，正是这个前缀要消除的问题。
+ *
+ * 返回 undefined 表示不是这个形态（交给调用方继续走其他分支）。
+ */
+function resolvePeerPrefixedPath(selfAid, allowedPeerKey, input) {
+    const normalized = input.replace(/\\/g, '/');
+    const parts = normalized.split('/');
+    // 至少 <peerKey>/consolidated/<file>
+    if (parts.length < 3 || parts[1] !== 'consolidated')
+        return undefined;
+    const peerKey = parts[0];
+    if (!peerKey)
+        return undefined;
+    // peerKey 里本来就可能带 `#`（aun#xxx），不能靠字符判断形态，靠段结构。
+    if (peerKey === 'consolidated' || peerKey === 'pending' || peerKey === 'archive')
+        return undefined;
+    // 整理一律按关系进行：只允许操作本次会话所属关系。会话没有所属关系（如 owner 层 forget）
+    // 时一律拒绝——放开等于让它对读不到的关系目录做 archive/update，绕过 grants 模型。
+    if (!allowedPeerKey || peerKey !== allowedPeerKey) {
+        throw new Error(`ROLE_ACCESS_DENIED: 只能操作本次整理会话所属关系（${allowedPeerKey ?? '无'}）的记忆，收到: ${peerKey}`);
+    }
+    const memoryDir = relationMemoryDirOf(selfAid, peerKey);
+    const consolidatedDir = path.join(memoryDir, 'consolidated');
+    const abs = path.resolve(consolidatedDir, parts.slice(2).join('/'));
+    // 包含性校验用 path.relative，不用 startsWith（Windows 大小写不一致时行为不定）
+    const rel = path.relative(consolidatedDir, abs);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+        throw new Error(`ROLE_ACCESS_DENIED: 路径越界: ${input}`);
+    }
+    return abs;
+}
 /**
  * 把用户给的路径解析成 consolidated/ 下的绝对路径。
- * 允许 slug / <slug>.md / 相对或绝对路径（须落在本作用域的 consolidated/ 内）。
  *
- * forget-agent 模式特殊处理：允许路径落在任意 relation 的 consolidated/ 下。
+ * 接受的形态：
+ *   - `slug` / `<slug>.md`           本作用域
+ *   - `consolidated/xxx.md`          本作用域（相对 memory 根）
+ *   - `<peerKey>/consolidated/x.md`  本次会话所属关系的 consolidated/（见 resolvePeerPrefixedPath）
+ *   - 落在上述范围内的绝对路径
+ *
+ * generalize / promote 产出在 agent / owner 层，靠 `<peerKey>/consolidated/` 前缀跨层操作本关系的源文件。
  */
 export function resolveConsolidatedPath(dirs, input, taskCtx) {
     const base = path.resolve(dirs.consolidatedDir);
@@ -61,6 +130,13 @@ export function resolveConsolidatedPath(dirs, input, taskCtx) {
         assertSlug(slug);
         return path.join(base, `${slug}.md`);
     }
+    // 跨关系形态优先：`<peerKey>/consolidated/x.md` 在 agent 作用域下若走下面的
+    // 本作用域候选，会被解析成 agent 级的同名文件，静默改错对象。
+    if (taskCtx?.selfAid) {
+        const crossRelation = resolvePeerPrefixedPath(taskCtx.selfAid, taskCtx.peerKey, input);
+        if (crossRelation)
+            return crossRelation;
+    }
     // 允许 "consolidated/xxx.md" 这种相对 MEMORY.md 的写法
     const candidates = [path.resolve(input), path.resolve(dirs.memoryDir, input)];
     for (const abs of candidates) {
@@ -68,21 +144,8 @@ export function resolveConsolidatedPath(dirs, input, taskCtx) {
         if (!rel.startsWith('..') && !path.isAbsolute(rel))
             return abs;
     }
-    // forget-agent 模式：允许路径落在任意 relation 的 consolidated/ 下，或 agent 自身的 consolidated/
-    const isForgetAgent = taskCtx?.memoryMode === 'forget' && taskCtx?.memoryScope === 'agent';
-    if (isForgetAgent && taskCtx?.selfAid) {
-        const relationsRoot = path.join(resolveRoot(), 'agents', taskCtx.selfAid, 'relations');
-        const absInput = path.resolve(input);
-        const relToRelations = path.relative(relationsRoot, absInput);
-        // 检查是否在某个 relation 的 consolidated/ 下
-        if (!relToRelations.startsWith('..') && !path.isAbsolute(relToRelations)) {
-            const parts = relToRelations.split(path.sep);
-            if (parts.length >= 3 && parts[1] === 'memory' && parts[2] === 'consolidated') {
-                return absInput;
-            }
-        }
-    }
-    throw new Error(`ROLE_ACCESS_DENIED: 只能操作本作用域 consolidated/ 下的记忆（${base}），当前路径越界: ${input}`);
+    throw new Error(`ROLE_ACCESS_DENIED: 只能操作本作用域 consolidated/ 下的记忆（${base}），当前路径越界: ${input}。`
+        + `跨关系操作用 \`<peerKey>/consolidated/<文件名>\` 形式（peerKey 必须是本次会话所属关系）。`);
 }
 function assertSlug(slug) {
     if (!SLUG_RE.test(slug)) {
@@ -143,8 +206,10 @@ export async function createMemory(req) {
     setMemoryField(document, 'name', req.slug);
     setMemoryField(document, 'description', req.description.trim());
     setMemoryField(document, 'scope', req.scope);
-    if (req.scope === 'relation' && req.taskCtx.peerKey)
-        setMemoryField(document, 'peerKey', req.taskCtx.peerKey);
+    // 与 resolveScopeDirs 取同一个值：frontmatter 记的必须是实际落盘目录的关系
+    const relationPeerKey = req.targetPeerKey ?? req.taskCtx.peerKey;
+    if (req.scope === 'relation' && relationPeerKey)
+        setMemoryField(document, 'peerKey', relationPeerKey);
     if (req.scope === 'owner' && req.ownerAid)
         setMemoryField(document, 'ownerAid', req.ownerAid);
     setMemoryField(document, 'createdAt', createdAt);
@@ -158,8 +223,13 @@ export async function createMemory(req) {
         setMemoryField(document, 'tags', req.tags);
     if (req.keywords?.length)
         setMemoryField(document, 'keywords', req.keywords);
-    if (replacePaths.length > 0)
-        setMemoryField(document, 'replaces', replacePaths.map(p => path.relative(dirs.memoryDir, p)));
+    // replaces 基准统一到 agents/<selfAid>/，与 generalizedFrom / promotedFrom 一致。
+    // 用 dirs.memoryDir 做基准时，跨关系的条目会变成 `../../relations/x/...`，
+    // 同一个文件里两种基准，将来读它的人得先猜。
+    if (replacePaths.length > 0) {
+        const agentRoot = path.join(resolveRoot(), 'agents', req.taskCtx.selfAid ?? '');
+        setMemoryField(document, 'replaces', replacePaths.map(p => path.relative(agentRoot, p)));
+    }
     document.body = req.content.trimEnd();
     const tmp = targetPath + '.tmp';
     fs.writeFileSync(tmp, serializeMemoryDocument(document), 'utf-8');
@@ -167,23 +237,34 @@ export async function createMemory(req) {
     registerFile(targetPath, req.taskCtx.selfAid);
     // 归档被替换的旧文件（在写入成功之后做，失败不影响新文件）
     const archived = [];
+    const archivedSources = [];
     for (const p of replacePaths) {
         if (!fs.existsSync(p))
             continue;
         if (path.resolve(p) === path.resolve(targetPath))
             continue;
-        const dest = archivePath(dirs.memoryDir, p);
+        // 跟随源文件所在层归档，跨关系时落进该关系自己的 archive/
+        const srcMemoryDir = sourceMemoryDirOf(p);
+        const dest = archivePath(srcMemoryDir, p);
         fs.mkdirSync(path.dirname(dest), { recursive: true });
         try {
             fs.renameSync(p, dest);
             archived.push(dest);
+            archivedSources.push(p);
             moveRecord(p, dest);
         }
         catch { /* 归档失败不影响主流程，由下次整理清理 */ }
     }
-    // 刷新本作用域的 _meta.json（扫描优化用；失败不影响主流程）
+    // 刷新 _meta.json（扫描优化用；失败不影响主流程）。
+    // 跨关系归档时源关系也要刷，否则它 _meta.json 里的标签计数不更新，
+    // 定时检查会反复拉起同一个整理会话。
     refreshMemoryMeta(dirs.memoryDir);
-    return { ok: true, filePath: targetPath, archived, scopeDirs: dirs };
+    for (const src of archivedSources) {
+        const srcMemoryDir = sourceMemoryDirOf(src);
+        if (path.resolve(srcMemoryDir) !== path.resolve(dirs.memoryDir))
+            refreshMemoryMeta(srcMemoryDir);
+    }
+    return { ok: true, filePath: targetPath, archived, archivedSources, scopeDirs: dirs };
 }
 /** 列出本作用域内除 exceptPath 之外、带 profile 标签的记忆文件。 */
 function findProfileMemories(dirs, exceptPath) {
@@ -214,9 +295,34 @@ function readExistingCreatedAt(filePath) {
     catch { /* ignore */ }
     return undefined;
 }
-/** 归档路径：<memory>/archive/consolidated/<原文件名> */
+/**
+ * 从一条 consolidated/ 记忆文件的绝对路径反推它所属的 memory 根。
+ *
+ * 归档必须跟随**源文件**所在层，不能一律用本作用域的 memoryDir：跨关系归档时
+ * 后者会把关系级记忆塞进 agent 级 archive/，而 restoreMemoryFile 是按 scope 找
+ * 自己的 archive 的，那条记忆就再也捞不回来了。
+ */
+export function sourceMemoryDirOf(filePath) {
+    const consolidatedDir = path.dirname(filePath);
+    if (path.basename(consolidatedDir) !== 'consolidated') {
+        throw new Error(`INTERNAL: 记忆文件不在 consolidated/ 下: ${filePath}`);
+    }
+    return path.dirname(consolidatedDir);
+}
+/**
+ * 归档路径：<源文件的 memory 根>/archive/consolidated/<原文件名>。
+ *
+ * 目标已存在时加时间戳后缀，不静默覆盖——同一关系里两次归档同名文件是可能的
+ * （比如先归档又被重建再归档），覆盖会让第一次归档的内容无声消失。
+ */
 function archivePath(memoryDir, filePath) {
-    return path.join(memoryDir, 'archive', 'consolidated', path.basename(filePath));
+    const dir = path.join(memoryDir, 'archive', 'consolidated');
+    const base = path.join(dir, path.basename(filePath));
+    if (!fs.existsSync(base))
+        return base;
+    const stem = path.basename(filePath).replace(/\.md$/, '');
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return path.join(dir, `${stem}.${stamp}.md`);
 }
 /**
  * 把 agent 级或 owner 级记忆降级回上一层（agent→relation 或 owner→agent）。
@@ -294,25 +400,45 @@ export async function updateMemory(req) {
     fs.writeFileSync(tmp, serializeMemoryDocument(document), 'utf-8');
     fs.renameSync(tmp, filePath);
     registerFile(filePath, req.taskCtx.selfAid);
-    refreshMemoryMeta(dirs.memoryDir);
-    return { ok: true, filePath, prevTags, scopeDirs: dirs };
+    // 跨层 update（如泛化时去掉关系级条目的 to-generalize 标签）时，
+    // 要刷的是**该文件所在层**的 _meta.json，不是本作用域那份。
+    const targetMemoryDir = sourceMemoryDirOf(filePath);
+    refreshMemoryMeta(targetMemoryDir);
+    return { ok: true, filePath, prevTags, scopeDirs: dirs, targetMemoryDir };
 }
 // ── archive ────────────────────────────────────────────────────────────────
 export async function archiveMemory(req) {
     const dirs = resolveScopeDirs(req.scope, req.taskCtx, req.ownerAid);
     const archived = [];
+    const archivedSources = [];
     for (const t of req.targets) {
         const p = resolveConsolidatedPath(dirs, t, req.taskCtx);
         if (!fs.existsSync(p))
             throw new Error(`找不到记忆文件: ${p}`);
-        const dest = archivePath(dirs.memoryDir, p);
+        // 只归档普通文件：renameSync 一个目录会把它整个搬进 archive/，
+        // 符号链接则会让后续读取跟到别处（与 grants.checkWriteTargets 的判据对齐）。
+        const stat = fs.lstatSync(p);
+        if (!stat.isFile()) {
+            throw new Error(`不是普通文件，拒绝归档: ${p}`);
+        }
+        // 跟随源文件所在层归档，跨关系时落进该关系自己的 archive/
+        const srcMemoryDir = sourceMemoryDirOf(p);
+        const dest = archivePath(srcMemoryDir, p);
         fs.mkdirSync(path.dirname(dest), { recursive: true });
         fs.renameSync(p, dest);
         moveRecord(p, dest);
         archived.push(dest);
+        archivedSources.push(p);
     }
+    // 跨关系归档时源关系也要刷 _meta.json，否则它 _meta.json 里的标签计数不更新，
+    // 定时检查会反复拉起同一个整理会话。
     refreshMemoryMeta(dirs.memoryDir);
-    return { ok: true, archived, scopeDirs: dirs };
+    for (const src of archivedSources) {
+        const srcMemoryDir = sourceMemoryDirOf(src);
+        if (path.resolve(srcMemoryDir) !== path.resolve(dirs.memoryDir))
+            refreshMemoryMeta(srcMemoryDir);
+    }
+    return { ok: true, archived, archivedSources, scopeDirs: dirs };
 }
 const NOTE_MAX_CONTENT_BYTES = 4 * 1024;
 function assertMemoryEnabled(memoryConfig) {

package/dist/core/memory/relation-idle-monitor.js

@@ -0,0 +1,287 @@
+/**
+ * relation-idle-monitor.ts — 关系级空闲 / 兜底计时
+ *
+ * 记忆整理一律以关系为单位（selfAid + peerKey；群聊按 groupId 算一个关系）。
+ * 每个关系一个计时器，到期时间取两者较早者：
+ *
+ *   空闲  lastInboundAt          + idleHours（默认 1）            最后一条入站后没有新入站
+ *   兜底  firstUnsweptInboundAt  + maxUnconsolidatedHours（默认 8） 最早一条未整理入站等太久
+ *
+ * 兜底从「最早未整理入站」起算而不是「上次整理时间」：沉寂多日的关系一来消息不会立刻被强整。
+ * 只计真实入站：owner 插话（owner-inject）、系统渠道、后台会话、trigger 不算。
+ *
+ * 到期后交给 startSweep（关系整理链，见 relation-sweep.ts），链跑完回调 onSweepFinished。
+ * 同一关系同时只跑一条链；链开始时清空 firstUnsweptInboundAt，期间的入站算新一轮。
+ * 状态落盘，重启后恢复；中断的链按「有未整理入站」处理，启动后立即重跑。
+ */
+import fs from 'fs';
+import path from 'path';
+import { formatPeerKey } from '../relation/peer-identity.js';
+import { isNonAgentSessionChannel } from '../system-channels.js';
+import { atomicWriteJson, decodeDirSegment, tryParseChannelSessionKey } from '../session/session-fs-store.js';
+import { logger } from '../../utils/logger.js';
+import { DEFAULT_MAX_UNCONSOLIDATED_HOURS, DEFAULT_RELATION_IDLE_HOURS } from './consolidation-trigger.js';
+const HOUR_MS = 60 * 60 * 1000;
+/** setTimeout 的上限约 24.8 天；更远的到期时间分段等。 */
+const MAX_TIMER_MS = 2 ** 31 - 1;
+/** 没有待整理入站、超过这么久没动静的条目不再落盘（路由信息下次入站会重新带上）。 */
+const PRUNE_AFTER_MS = 7 * 24 * HOUR_MS;
+const SAVE_DEBOUNCE_MS = 1000;
+/**
+ * 把一条入站日志换算成关系入站信号；不是真实关系入站时返回 undefined。
+ *
+ * chatDir 形如 `<sessionsDir>/<selfAid>/sessions/<type>#<name>#<channelId>`，
+ * channelType / 渠道实例名 / selfAid 都从路径取——日志条目本身只有 from/to。
+ */
+export function relationInboundFromLog(chatDir, entry) {
+    if (entry.dir !== 'in')
+        return undefined;
+    if (entry.source === 'owner-inject')
+        return undefined;
+    if (entry.peerType === 'system')
+        return undefined;
+    const parsed = tryParseChannelSessionKey(path.basename(chatDir));
+    if (!parsed)
+        return undefined;
+    const { channelType, channelName, channelId } = parsed;
+    if (isNonAgentSessionChannel(channelType))
+        return undefined;
+    if (channelId.startsWith('bg:') || channelId.startsWith('trigger:'))
+        return undefined;
+    const sessionsSeg = path.basename(path.dirname(chatDir));
+    if (sessionsSeg !== 'sessions')
+        return undefined;
+    const selfAid = decodeDirSegment(path.basename(path.dirname(path.dirname(chatDir))));
+    if (!selfAid || selfAid === '_unknown')
+        return undefined;
+    const chatType = entry.chatType === 'group' ? 'group' : 'private';
+    // 群聊按群算一个关系；私聊按发送者（AUN 下 from 即对端 AID，其他渠道 from 是用户 ID）
+    const peerId = chatType === 'group'
+        ? (entry.groupId || channelId)
+        : (entry.from && entry.from !== 'unknown' ? entry.from : channelId);
+    if (!peerId || peerId.startsWith('bg:') || peerId.startsWith('trigger:'))
+        return undefined;
+    return {
+        selfAid,
+        peerKey: formatPeerKey(channelType, peerId),
+        route: {
+            channel: channelType,
+            channelId,
+            chatType,
+            peerId,
+            channelKey: `${channelType}#${selfAid}#${channelName}`,
+            ...(entry.threadId ? { threadId: entry.threadId } : {}),
+        },
+    };
+}
+function relationKey(selfAid, peerKey) {
+    return `${selfAid}\u0000${peerKey}`;
+}
+function positiveHours(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+export class RelationIdleMonitor {
+    deps;
+    entries = new Map();
+    active = false;
+    saveTimer;
+    now;
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? Date.now;
+    }
+    /** 加载落盘状态。中断的链按「有未整理入站」恢复。 */
+    load() {
+        let raw;
+        try {
+            raw = JSON.parse(fs.readFileSync(this.deps.statePath, 'utf-8'));
+        }
+        catch {
+            return;
+        }
+        if (!raw || raw.version !== 1 || !Array.isArray(raw.entries))
+            return;
+        for (const item of raw.entries) {
+            if (!item?.selfAid || !item?.peerKey)
+                continue;
+            const entry = {
+                selfAid: item.selfAid,
+                peerKey: item.peerKey,
+                ...(typeof item.lastInboundAt === 'number' ? { lastInboundAt: item.lastInboundAt } : {}),
+                ...(typeof item.firstUnsweptAt === 'number' ? { firstUnsweptAt: item.firstUnsweptAt } : {}),
+                ...(item.route ? { route: item.route } : {}),
+            };
+            // 上次进程退出时链还在跑：那一轮没跑完，当作它覆盖的入站还没整理
+            if (typeof item.sweepingSince === 'number') {
+                entry.firstUnsweptAt = Math.min(entry.firstUnsweptAt ?? item.sweepingSince, item.sweepingSince);
+            }
+            this.entries.set(relationKey(entry.selfAid, entry.peerKey), entry);
+        }
+    }
+    /** 开始计时（启动流程末尾调用）。已过期的立即触发。 */
+    start() {
+        this.active = true;
+        for (const entry of this.entries.values())
+            this.schedule(entry);
+    }
+    stop() {
+        this.active = false;
+        for (const entry of this.entries.values()) {
+            if (entry.timer)
+                clearTimeout(entry.timer);
+            entry.timer = undefined;
+        }
+        if (this.saveTimer)
+            clearTimeout(this.saveTimer);
+        this.saveTimer = undefined;
+        this.saveNow();
+    }
+    /** 关系有一条真实入站。 */
+    recordInbound(inbound) {
+        const at = this.now();
+        const entry = this.ensureEntry(inbound.selfAid, inbound.peerKey);
+        entry.lastInboundAt = at;
+        if (entry.firstUnsweptAt === undefined)
+            entry.firstUnsweptAt = at;
+        entry.route = inbound.route;
+        this.schedule(entry);
+        this.scheduleSave();
+    }
+    /**
+     * 要求尽快整理某个关系（群链写入了发言人关系、pending 堆积兜底等），不等计时。
+     * 链在跑时记一笔，链结束后再跑一轮。
+     */
+    requestSweep(selfAid, peerKey, propagate) {
+        // 与计时到期同一道门：开关关闭、首次设定未完成时不起链
+        if (!this.deps.canSweep(selfAid, peerKey))
+            return;
+        const entry = this.ensureEntry(selfAid, peerKey);
+        if (entry.sweepingSince !== undefined) {
+            entry.sweepRequested = true;
+            return;
+        }
+        this.begin(entry, propagate);
+    }
+    /** 整理链结束（无论成败、无论起没起会话）。 */
+    onSweepFinished(selfAid, peerKey) {
+        const entry = this.entries.get(relationKey(selfAid, peerKey));
+        if (!entry || entry.sweepingSince === undefined)
+            return;
+        entry.sweepingSince = undefined;
+        if (entry.sweepRequested) {
+            entry.sweepRequested = false;
+            this.begin(entry, false);
+            return;
+        }
+        this.schedule(entry);
+        this.scheduleSave();
+    }
+    /** 测试与诊断用：当前状态快照。 */
+    snapshot(selfAid, peerKey) {
+        const entry = this.entries.get(relationKey(selfAid, peerKey));
+        if (!entry)
+            return undefined;
+        const { timer: _timer, ...rest } = entry;
+        return { ...rest, dueAt: this.dueAt(entry) };
+    }
+    ensureEntry(selfAid, peerKey) {
+        const key = relationKey(selfAid, peerKey);
+        let entry = this.entries.get(key);
+        if (!entry) {
+            entry = { selfAid, peerKey };
+            this.entries.set(key, entry);
+        }
+        return entry;
+    }
+    /** 没有待整理入站时不计时。 */
+    dueAt(entry) {
+        if (entry.firstUnsweptAt === undefined)
+            return undefined;
+        const timing = this.deps.getTiming(entry.selfAid);
+        const idleMs = positiveHours(timing?.idleHours, DEFAULT_RELATION_IDLE_HOURS) * HOUR_MS;
+        const maxMs = positiveHours(timing?.maxUnconsolidatedHours, DEFAULT_MAX_UNCONSOLIDATED_HOURS) * HOUR_MS;
+        const last = entry.lastInboundAt ?? entry.firstUnsweptAt;
+        return Math.min(last + idleMs, entry.firstUnsweptAt + maxMs);
+    }
+    schedule(entry) {
+        if (entry.timer)
+            clearTimeout(entry.timer);
+        entry.timer = undefined;
+        if (!this.active || entry.sweepingSince !== undefined)
+            return;
+        const due = this.dueAt(entry);
+        if (due === undefined)
+            return;
+        const delay = Math.max(0, Math.min(due - this.now(), MAX_TIMER_MS));
+        entry.timer = setTimeout(() => {
+            entry.timer = undefined;
+            // 分段等待：还没到真正的到期时间就再排一次
+            if ((this.dueAt(entry) ?? Infinity) > this.now()) {
+                this.schedule(entry);
+                return;
+            }
+            this.fire(entry);
+        }, delay);
+        entry.timer.unref?.();
+    }
+    fire(entry) {
+        if (!this.active || entry.sweepingSince !== undefined)
+            return;
+        if (!this.deps.canSweep(entry.selfAid, entry.peerKey)) {
+            // 现在整理不了（开关关闭、首次设定未完成等）：这一轮作废，等下一条入站重新计时
+            entry.firstUnsweptAt = undefined;
+            this.scheduleSave();
+            return;
+        }
+        this.begin(entry, true);
+    }
+    begin(entry, propagate) {
+        if (entry.timer)
+            clearTimeout(entry.timer);
+        entry.timer = undefined;
+        entry.sweepingSince = this.now();
+        entry.firstUnsweptAt = undefined;
+        this.scheduleSave();
+        logger.info(`[Memory] 关系整理链开始（aid=${entry.selfAid}，peerKey=${entry.peerKey}）`);
+        try {
+            this.deps.startSweep({ selfAid: entry.selfAid, peerKey: entry.peerKey, route: entry.route, propagate });
+        }
+        catch (error) {
+            logger.warn(`[Memory] 关系整理链启动失败（peerKey=${entry.peerKey}）: ${error?.message}`);
+            this.onSweepFinished(entry.selfAid, entry.peerKey);
+        }
+    }
+    scheduleSave() {
+        if (this.saveTimer)
+            return;
+        this.saveTimer = setTimeout(() => {
+            this.saveTimer = undefined;
+            this.saveNow();
+        }, SAVE_DEBOUNCE_MS);
+        this.saveTimer.unref?.();
+    }
+    saveNow() {
+        const now = this.now();
+        const entries = [];
+        for (const entry of this.entries.values()) {
+            const pending = entry.firstUnsweptAt !== undefined || entry.sweepingSince !== undefined;
+            if (!pending && (entry.lastInboundAt === undefined || now - entry.lastInboundAt > PRUNE_AFTER_MS))
+                continue;
+            entries.push({
+                selfAid: entry.selfAid,
+                peerKey: entry.peerKey,
+                ...(entry.lastInboundAt !== undefined ? { lastInboundAt: entry.lastInboundAt } : {}),
+                ...(entry.firstUnsweptAt !== undefined ? { firstUnsweptAt: entry.firstUnsweptAt } : {}),
+                ...(entry.sweepingSince !== undefined ? { sweepingSince: entry.sweepingSince } : {}),
+                ...(entry.route ? { route: entry.route } : {}),
+            });
+        }
+        try {
+            fs.mkdirSync(path.dirname(this.deps.statePath), { recursive: true });
+            atomicWriteJson(this.deps.statePath, { version: 1, entries });
+        }
+        catch (error) {
+            logger.warn(`[Memory] 关系空闲状态落盘失败: ${error?.message}`);
+        }
+    }
+}