@runko/persist-mongo 0.1.1 → 0.2.0

package/dist/index.cjs

@@ -3,6 +3,9 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const LEDGER_COLLECTION = "agent_ledger";
 const DECISIONS_COLLECTION = "agent_decisions";
 const QUEUE_COLLECTION = "agent_queue";
+const LEASES_COLLECTION = "agent_leases";
+const NODES_COLLECTION = "agent_nodes";
+const TAILS_COLLECTION = "agent_tool_tails";
 /**
 * **写进 BSON 之前先过一遍 JSON。**
 *
@@ -44,12 +47,33 @@ function fromBson(value) {
 	return value;
 }
 //#endregion
-//#region src/stores.ts
-const OK = { ok: true };
-/** 重复键。并发 upsert 撞同一个唯一索引时驱动抛这个，见 `upsertOnce`。 */
+//#region src/errors.ts
+/**
+* 认 MongoDB 驱动抛出来的两类错误。
+*
+* **它们是本包里唯一需要「看错误内部」的地方**，所以收在一个文件里：驱动抛的是
+* `MongoServerError`，但 `instanceof` 在跨 driver 实例（宿主装的那份 vs 我们看到的那份）
+* 时不可靠，判 `code` 才稳。
+*
+* **一个断言都没有**：`typeof x === "object"` + `x !== null` + `"code" in x` 三步之后，
+* TypeScript 已经把它收窄成「有 `code` 这个键的对象」，直接读就行（`in` 的收窄行为从
+* TS 4.9 起就有了）。这正是仓库规范要的写法——用类型守卫，不用 `as`。
+*/
+/** 重复键。唯一索引挡下并发插入 / upsert 时驱动抛这个。 */
 const DUPLICATE_KEY = 11e3;
+/** 同名索引已存在但选项或键不同时 Mongo 报的两个 code。 */
+const INDEX_CONFLICT_CODES = /* @__PURE__ */ new Set([85, 86]);
+/** 取出 `error.code`，拿不到就 `undefined`。 */
+function codeOf(error) {
+	if (typeof error !== "object" || error === null || !("code" in error)) return;
+	return error.code;
+}
 function isDuplicateKeyError(error) {
-	return typeof error === "object" && error !== null && "code" in error && error.code === DUPLICATE_KEY;
+	return codeOf(error) === DUPLICATE_KEY;
+}
+function isIndexConflict(error) {
+	const code = codeOf(error);
+	return typeof code === "number" && INDEX_CONFLICT_CODES.has(code);
 }
 /**
 * 幂等插入的**兜底那一半**：吞掉重复键，其余错误照抛。
@@ -61,9 +85,7 @@ function isDuplicateKeyError(error) {
 * 挡下后一个。这是 MongoDB 明确记录的行为，不是 bug。那一支的结果照样是「已经有了
 * 一行」——契约要的是「不得写出两行」，满足了，所以吞掉。
 *
-* **只包异常处理、不包 `updateOne` 本身**是刻意的：这样 `$setOnInsert` 的字段能在
-* **具体的调用点**跟具体的文档类型对上，写错字段当场编译不过。包成一个泛型 helper
-* 反而会把类型冲开、逼出一个 `as`。
+* 收在这里（而不是各自 store 一份）是因为 `stores.ts` 与 `tails.ts` 都要用它。
 */
 async function ignoringDuplicateKey(write) {
 	try {
@@ -73,6 +95,9 @@ async function ignoringDuplicateKey(write) {
 		return;
 	}
 }
+//#endregion
+//#region src/stores.ts
+const OK$1 = { ok: true };
 function createLedgerStore(db) {
 	const col = db.collection(LEDGER_COLLECTION);
 	return {
@@ -83,12 +108,12 @@ function createLedgerStore(db) {
 			}, { $setOnInsert: {
 				payload: toBson(entry.message),
 				ts: entry.ts
-			} }, { upsert: true })))?.upsertedCount === 1) return OK;
+			} }, { upsert: true })))?.upsertedCount === 1) return OK$1;
 			const existing = await col.findOne({
 				conversationId: entry.conversationId,
 				seq: entry.seq
 			}, { projection: { _id: 0 } });
-			if (existing !== null && fromBson(existing.payload).id === entry.message.id) return OK;
+			if (existing !== null && fromBson(existing.payload).id === entry.message.id) return OK$1;
 			return {
 				ok: false,
 				reason: "rejected"
@@ -120,8 +145,15 @@ function createLedgerStore(db) {
 function isOutcome(value) {
 	return value === "allow" || value === "deny" || value === "answered" || value === "timeout";
 }
-/** 可选字段一律「有才放进去」——`exactOptionalPropertyTypes` 下不能给 `undefined`。 */
-function toRecord(doc) {
+/**
+* 可选字段一律「有才放进去」。
+*
+* 这个函数是在**两种「没有」之间翻译**：库里用 `null` 表示没有，`DecisionRecord` 用
+* 「键不存在」表示没有。写成 `toolName: doc.toolName ?? undefined` 会造出第三种形状
+* ——键在、值是 `undefined`——它既不是库那边的表示、也不是接口这边的表示，而且
+* `"toolName" in record` 会答 `true`，把「没有」说成「有」。
+*/
+function toRecord$1(doc) {
 	return {
 		conversationId: doc.conversationId,
 		toolCallId: doc.toolCallId,
@@ -154,7 +186,7 @@ function createDecisionStore(db) {
 				requestedAt: entry.requestedAt,
 				decidedAt: entry.decidedAt ?? null
 			} }, { upsert: true }));
-			return OK;
+			return OK$1;
 		},
 		async settle(conversationId, toolCallId, settlement) {
 			return (await col.updateOne({
@@ -173,7 +205,14 @@ function createDecisionStore(db) {
 			return (await col.find({
 				conversationId,
 				decidedAt: null
-			}, { projection: { _id: 0 } }).sort({ requestedAt: 1 }).toArray()).map(toRecord);
+			}, { projection: { _id: 0 } }).sort({ requestedAt: 1 }).toArray()).map(toRecord$1);
+		},
+		async get(conversationId, toolCallId) {
+			const doc = await col.findOne({
+				conversationId,
+				toolCallId
+			}, { projection: { _id: 0 } });
+			return doc === null ? void 0 : toRecord$1(doc);
 		}
 	};
 }
@@ -292,12 +331,574 @@ function createQueueStore(db) {
 	};
 }
 //#endregion
-//#region src/migrate.ts
-/** 同名索引已存在但选项不同时 Mongo 报的两个 code。 */
-const INDEX_CONFLICT_CODES = /* @__PURE__ */ new Set([85, 86]);
-function isIndexConflict(error) {
-	return typeof error === "object" && error !== null && "code" in error && typeof error.code === "number" && INDEX_CONFLICT_CODES.has(error.code);
+//#region src/tails.ts
+const OK = { ok: true };
+/**
+* `JsonValue` 深比较，与对象键的排列顺序无关——MongoDB 的驱动/序列化过程不保证
+* 写入与读回时对象键的顺序一致，`JSON.stringify` 直接比较会把「同一个对象、键序不同」
+* 误判成不相等。
+*/
+function jsonValueEquals(a, b) {
+	if (a === b) return true;
+	if (Array.isArray(a) || Array.isArray(b)) {
+		if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+		return a.every((item, index) => {
+			const other = b.at(index);
+			return other !== void 0 && jsonValueEquals(item, other);
+		});
+	}
+	if (typeof a === "object" && a !== null && typeof b === "object" && b !== null) {
+		const aEntries = Object.entries(a);
+		const bKeys = Object.keys(b);
+		if (aEntries.length !== bKeys.length) return false;
+		return aEntries.every(([key, value]) => {
+			const other = b[key];
+			return other !== void 0 && jsonValueEquals(value, other);
+		});
+	}
+	return false;
+}
+/** 结构相等：用来判断「读回来的那条是不是我刚写的那条」（见 `complete` 的读回确认）。 */
+function outcomeEquals(a, b) {
+	if (a.kind !== b.kind) return false;
+	if (a.kind === "output" && b.kind === "output") return jsonValueEquals(a.output, b.output);
+	if (a.kind === "error" && b.kind === "error") return a.errorText === b.errorText;
+	return false;
+}
+function toRecord(doc) {
+	return {
+		conversationId: doc.conversationId,
+		toolCallId: doc.toolCallId,
+		toolName: doc.toolName,
+		runner: doc.runner,
+		startedAt: doc.startedAt,
+		deadline: doc.deadline,
+		...doc.outcome !== null ? { outcome: fromBson(doc.outcome) } : {},
+		...doc.settledAt !== null ? { settledAt: doc.settledAt } : {},
+		stopRequested: doc.stopRequested
+	};
+}
+function createToolTailStore(db) {
+	const col = db.collection(TAILS_COLLECTION);
+	return {
+		async begin(record) {
+			await ignoringDuplicateKey(() => col.updateOne({
+				conversationId: record.conversationId,
+				toolCallId: record.toolCallId
+			}, { $setOnInsert: {
+				toolName: record.toolName,
+				runner: record.runner,
+				startedAt: record.startedAt,
+				deadline: record.deadline,
+				outcome: null,
+				settledAt: null,
+				stopRequested: false
+			} }, { upsert: true }));
+			return OK;
+		},
+		async complete(conversationId, toolCallId, outcome, settledAt) {
+			await col.updateOne({
+				conversationId,
+				toolCallId,
+				outcome: null
+			}, { $set: {
+				outcome: toBson(outcome),
+				settledAt
+			} });
+			const doc = await col.findOne({
+				conversationId,
+				toolCallId
+			}, { projection: {
+				outcome: 1,
+				settledAt: 1
+			} });
+			if (doc === null || doc.outcome === null) return false;
+			return outcomeEquals(fromBson(doc.outcome), outcome) && doc.settledAt === settledAt;
+		},
+		async get(conversationId, toolCallId) {
+			const doc = await col.findOne({
+				conversationId,
+				toolCallId
+			}, { projection: { _id: 0 } });
+			return doc === null ? void 0 : toRecord(doc);
+		},
+		async requestStop(conversationId, toolCallId) {
+			await col.updateOne({
+				conversationId,
+				toolCallId,
+				outcome: null
+			}, { $set: { stopRequested: true } });
+			const doc = await col.findOne({
+				conversationId,
+				toolCallId
+			}, { projection: {
+				outcome: 1,
+				stopRequested: 1
+			} });
+			return doc !== null && doc.outcome === null && doc.stopRequested === true;
+		}
+	};
+}
+//#endregion
+//#region src/arbitration.ts
+/** 心跳间隔的默认值（毫秒）。与 SQL 那一档同款，定案见技术方案 §8.3。 */
+const DEFAULT_HEARTBEAT_MS = 5e3;
+/** 超时接管阈值的默认值（毫秒）——12 个心跳。 */
+const DEFAULT_TAKEOVER_MS = 6e4;
+/** 阈值至少要是心跳的几倍。配成 2× 会让一次正常的调度延迟就触发误判。 */
+const MIN_BEATS_BEFORE_TAKEOVER = 3;
+/**
+* 建一个租约版归属仲裁机制。
+*
+* ```ts
+* const arbitration = mongoArbitration(db, { holder: process.env.POD_NAME });
+* createAgentRuntime({ ..., persistence: mongoPersistence(db), arbitration });
+* ```
+*
+* **吃的是同一个 `Db`**——跟 `mongoPersistence(db)` 一样。`migrate(db)` 已经把租约集合要的
+* 索引一起建了，不用再调别的。
+*/
+function mongoArbitration(db, opts) {
+	const heartbeatMs = opts.heartbeatMs ?? 5e3;
+	const takeoverMs = opts.takeoverMs ?? 6e4;
+	const now = opts.now ?? Date.now;
+	if (takeoverMs < heartbeatMs * MIN_BEATS_BEFORE_TAKEOVER) throw new Error(`mongoArbitration: takeoverMs (${String(takeoverMs)}ms) must be at least ${String(MIN_BEATS_BEFORE_TAKEOVER)}× heartbeatMs (${String(heartbeatMs)}ms). A shorter threshold turns one ordinary scheduling delay into two simultaneous holders, which corrupts the ledger silently.`);
+	const col = db.collection(LEASES_COLLECTION);
+	/**
+	* 本进程起来的时刻。
+	*
+	* **挂在自己名下、心跳却早于这一刻的租约，一定是上一辈子留下的**——一个刚起来的进程
+	* 不可能已经在跑任何一轮。启动扫描据此立刻收拾它，不必干等[接管阈值](../../../docs/terms.md)：
+	* 崩溃后马上重启的会话，重启完就能用。
+	*
+	* **前提是每个进程的 `holder` 唯一。** 两个活着的进程配成同一个名字时，后起来的那个会把
+	* 先来的那一轮抢过去；先来的手里那个[租期标识](../../../docs/terms.md)已经作废、写不进账本，
+	* 所以坏的是那一轮，不是数据。
+	*/
+	const startedAt = now();
+	/** 挂在我名下、心跳早于本进程启动 = 上一辈子的残留。 */
+	const isMyOrphan = (doc) => doc.holder === opts.holder && doc.heartbeatAt < startedAt;
+	/**
+	* 陈旧判据：心跳超过接管阈值没续，**或者**是我自己上一辈子的残留。
+	*
+	* `listStale`、`clearStale`、`acquire` 三处共用这一条——判据一旦不一致，`recover()` 的
+	* `listStale → clearStale → acquire` 会互相打架（见 `clearStale` 的注释）。
+	*/
+	const staleOr = (at) => [{ heartbeatAt: { $lt: at - takeoverMs } }, {
+		holder: opts.holder,
+		heartbeatAt: { $lt: startedAt }
+	}];
+	/** 一条租约是不是「有人持有且还活着」。我自己上一辈子的残留不算活着。 */
+	const isLive = (doc, at) => doc.leaseToken !== null && at - doc.heartbeatAt <= takeoverMs && !isMyOrphan(doc);
+	/**
+	* [交接预留](../../../docs/terms.md)还有效吗——`reservedUntil` 缺席或已过 = 没有预留，
+	* 退化成「没人持有」。返回预留给谁，`undefined` = 没有有效预留。
+	*/
+	const activeReservedFor = (doc, at) => {
+		if (doc === null || doc.reservedFor === null || doc.reservedUntil === null) return;
+		return doc.reservedUntil > at ? doc.reservedFor : void 0;
+	};
+	async function acquire(conversationId, ctx) {
+		const at = now();
+		const existing = await col.findOne({ _id: conversationId });
+		const reservedFor = activeReservedFor(existing, at);
+		if (reservedFor !== void 0 && reservedFor !== opts.holder) return {
+			ok: false,
+			reason: "busy",
+			holder: reservedFor
+		};
+		if (existing !== null && isLive(existing, at)) return {
+			ok: false,
+			reason: "busy",
+			holder: existing.holder ?? void 0
+		};
+		const token = crypto.randomUUID();
+		if (existing === null) {
+			const watermark = await ctx.seedSeq();
+			try {
+				await col.insertOne({
+					_id: conversationId,
+					holder: null,
+					leaseToken: null,
+					seqWatermark: watermark,
+					heartbeatAt: 0,
+					acquiredAt: at,
+					reservedFor: null,
+					reservedUntil: null,
+					awaitingTakeover: false
+				});
+			} catch (error) {
+				if (!isDuplicateKeyError(error)) throw error;
+			}
+		} else if (existing.seqWatermark === null) {
+			const watermark = await ctx.seedSeq();
+			await col.updateOne({
+				_id: conversationId,
+				seqWatermark: null
+			}, { $set: { seqWatermark: watermark } });
+		}
+		if (await col.findOneAndUpdate({
+			_id: conversationId,
+			$or: [{ leaseToken: null }, ...staleOr(at)],
+			$and: [{ $or: [
+				{ reservedFor: null },
+				{ reservedFor: opts.holder },
+				{ reservedUntil: { $lte: at } }
+			] }]
+		}, { $set: {
+			holder: opts.holder,
+			leaseToken: token,
+			heartbeatAt: at,
+			acquiredAt: at,
+			reservedFor: null,
+			reservedUntil: null
+		} }, { returnDocument: "after" }) === null) {
+			const current = await col.findOne({ _id: conversationId });
+			const blockedBy = activeReservedFor(current, now());
+			if (blockedBy !== void 0 && blockedBy !== opts.holder) return {
+				ok: false,
+				reason: "busy",
+				holder: blockedBy
+			};
+			return {
+				ok: false,
+				reason: "busy",
+				holder: current?.holder ?? void 0
+			};
+		}
+		const grant = createGrant(conversationId, token, at);
+		if (existing !== null && existing.leaseToken !== null) return {
+			ok: true,
+			grant,
+			takeover: existing.holder !== null ? { holder: existing.holder } : {}
+		};
+		return {
+			ok: true,
+			grant
+		};
+	}
+	function createGrant(conversationId, token, acquiredAt) {
+		const controller = new AbortController();
+		let released = false;
+		/** 取号串起来跑：同一个 grant 的两次 `nextSeq` 交错会读到同一个水位。 */
+		let chain = Promise.resolve();
+		/**
+		* 最后一次成功心跳**写进 `heartbeatAt` 的那个时刻**——不是往返回来之后重新取的
+		* `now()`。别的副本判死看的就是库里那个值，围栏必须拿同一个基准算余量；用 ack
+		* 之后的时刻会把整条往返白送出去，往返一旦接近心跳间隔（库劣化时很常见，而库劣化
+		* 正是这段代码存在的理由）余量就归零甚至变负——收手比别人接管还晚。
+		*/
+		let lastBeatAt = acquiredAt;
+		/** 上一拍还没跑完就别再起一拍（库卡住时 `beat` 可能比间隔还慢）。 */
+		let beating = false;
+		/**
+		* 别人最早能在 `lastBeatAt + takeoverMs` 接管我，所以留一拍的余量提前收手。
+		* 这条依赖各副本时钟大致同步；时钟不可信的部署应该把 `takeoverMs` 调大，
+		* 而不是把这个余量调小。
+		*/
+		const fenceExpired = () => now() - lastBeatAt >= takeoverMs - heartbeatMs;
+		/**
+		* 心跳。**它同时是「我还持有吗」的主要发现路径**——比 `nextSeq` 更早，因为一轮里
+		* 可能很久才写一次账本。打不中就说明令牌被换了：立刻 abort，让正在跑的那一轮走
+		* 既有的中断收尾。
+		*
+		* **失败要分两档处理，这是这段最容易写错的地方**：
+		*
+		* - 偶发一两次失败 → 什么都不做，下一拍再试（网络抖动不该中断用户的一轮）。
+		* - **连续失败到逼近接管阈值 → 自己主动停手**（自我围栏）。不这么做的话：库连不上
+		*   恰恰是副本停跳最常见的原因，那时我的心跳每拍都失败、永远不 abort，而别人在
+		*   `takeoverMs` 之后已经合法接管并开始跑——账本有令牌 CAS 挡着不会写坏，但
+		*   **沙盒挡不住**，两个执行同时改同一个工作区就是互相踩文件。
+		*
+		* **围栏判断必须放在最前面**，在防重入早退之前。心跳失败有两种形状：抛错（连不上）
+		* 与**挂住不返回**（TCP 黑洞、连接池耗尽、网络分区下的 TCP 停滞）——后者更常见，
+		* 而且**不会进 `catch`**，它只是让上一拍永远不结束。围栏判断若只写在 `catch` 里，
+		* `beating` 会永久停在 `true`，此后每一拍都在防重入这里就 return 了，于是老持有者
+		* 永远不停手，而别人早已合法接管。
+		*/
+		const beat = async () => {
+			if (released || controller.signal.aborted) return;
+			if (fenceExpired()) {
+				lose();
+				return;
+			}
+			if (beating) return;
+			beating = true;
+			const beatAt = now();
+			try {
+				if ((await col.updateOne({
+					_id: conversationId,
+					leaseToken: token
+				}, { $set: { heartbeatAt: beatAt } })).matchedCount > 0) {
+					lastBeatAt = beatAt;
+					return;
+				}
+			} catch {
+				return;
+			} finally {
+				beating = false;
+			}
+			lose();
+		};
+		const timer = setInterval(() => {
+			beat();
+		}, heartbeatMs);
+		if (typeof timer.unref === "function") timer.unref();
+		function lose() {
+			if (controller.signal.aborted) return;
+			clearInterval(timer);
+			controller.abort(/* @__PURE__ */ new Error("lease lost"));
+		}
+		return {
+			conversationId,
+			holder: opts.holder,
+			signal: controller.signal,
+			get valid() {
+				return !released && !controller.signal.aborted;
+			},
+			async nextSeq() {
+				const run = chain.then(async () => {
+					if (released || controller.signal.aborted) return {
+						ok: false,
+						reason: "lost_ownership"
+					};
+					try {
+						const beatAt = now();
+						const doc = await col.findOneAndUpdate({
+							_id: conversationId,
+							leaseToken: token
+						}, {
+							$inc: { seqWatermark: 1 },
+							$set: { heartbeatAt: beatAt }
+						}, { returnDocument: "after" });
+						if (doc === null || doc.seqWatermark === null) {
+							lose();
+							return {
+								ok: false,
+								reason: "lost_ownership"
+							};
+						}
+						lastBeatAt = beatAt;
+						return {
+							ok: true,
+							seq: doc.seqWatermark
+						};
+					} catch {
+						return {
+							ok: false,
+							reason: "lost_ownership"
+						};
+					}
+				});
+				chain = run.catch(() => void 0);
+				return await run;
+			},
+			async release() {
+				if (released) return;
+				released = true;
+				clearInterval(timer);
+				await col.updateOne({
+					_id: conversationId,
+					leaseToken: token
+				}, { $set: {
+					holder: null,
+					leaseToken: null
+				} });
+			},
+			async releaseTo(node, handoverOpts) {
+				if (released) return;
+				released = true;
+				clearInterval(timer);
+				const at = now();
+				await col.updateOne({
+					_id: conversationId,
+					leaseToken: token
+				}, { $set: {
+					holder: null,
+					leaseToken: null,
+					reservedFor: node,
+					reservedUntil: at + handoverOpts.ttlMs
+				} });
+			}
+		};
+	}
+	return {
+		acquire,
+		async inspect(conversationId) {
+			const at = now();
+			const doc = await col.findOne({ _id: conversationId });
+			if (doc !== null && isLive(doc, at)) return {
+				held: true,
+				...doc.holder !== null ? { holder: doc.holder } : {}
+			};
+			const reservedFor = activeReservedFor(doc, at);
+			if (reservedFor !== void 0) return {
+				held: true,
+				holder: reservedFor,
+				reserved: true
+			};
+			return { held: false };
+		},
+		/**
+		* 「有人持有但心跳已超时」的那些会话。
+		*
+		* **语义跟内存版不一样，但两个都对**：内存版的归属表跟进程同生共死，看不到自己上次
+		* 崩溃的残留（恒返回空数组）；租约版看得到——那正是它存在的理由。
+		*/
+		async listStale() {
+			return (await col.find({
+				leaseToken: { $ne: null },
+				$or: staleOr(now())
+			}, { projection: { holder: 1 } }).toArray()).map((doc) => ({
+				conversationId: doc._id,
+				...doc.holder !== null ? { holder: doc.holder } : {}
+			}));
+		},
+		/**
+		* 清一条陈旧标记。**必须带上跟 `listStale` 同一条陈旧判据**，不能只按会话清——
+		* 否则会擦掉一个**活着的**持有者的租约。
+		*
+		* 触发路径就在框架自己身上：`recover()` 的顺序是 `listStale → clearStale → acquire`。
+		* 多副本滚动重启时两个副本同时开机、扫到同一条陈旧会话：A 先清完并抢到令牌开始补写，
+		* B 随后若无条件清一次就把 A 的令牌抹掉了——要么同一个会话被补两条「已停止」标记，
+		* 要么 A 补到一半被判出局。带上判据之后 B 这一下是 no-op，它的 `acquire` 会老实报 busy。
+		*/
+		async clearStale(conversationId) {
+			await col.updateOne({
+				_id: conversationId,
+				$or: staleOr(now())
+			}, { $set: {
+				holder: null,
+				leaseToken: null
+			} });
+		},
+		/**
+		* 打[待接手](../../../docs/terms.md)标记。幂等，行不存在也要能打——`upsert` 补一份
+		* 「没人持有」的空租约。
+		*
+		* **`seqWatermark` 垫成 `null`，不是 0**：这份文档从没被真正 `acquire` 过，水位还没从
+		* 账本问过。写死成 0 会让下一次 `acquire()` 误以为已经播种、跳过 `seedSeq()`，发号从 1
+		* 开始，跟账本里已有的 seq 撞车。`acquire()` 见到 `null` 会自己补种。
+		*/
+		async markAwaitingTakeover(conversationId) {
+			await col.updateOne({ _id: conversationId }, {
+				$set: { awaitingTakeover: true },
+				$setOnInsert: {
+					holder: null,
+					leaseToken: null,
+					seqWatermark: null,
+					heartbeatAt: 0,
+					acquiredAt: now(),
+					reservedFor: null,
+					reservedUntil: null
+				}
+			}, { upsert: true });
+		},
+		/** 撤掉待接手标记。幂等：文档本来就不存在时是 no-op（不 upsert）。 */
+		async clearAwaitingTakeover(conversationId) {
+			await col.updateOne({ _id: conversationId }, { $set: { awaitingTakeover: false } });
+		},
+		/**
+		* [定时回捞](../../../docs/terms.md)候选：只看打了待接手标记的那些，排除掉「有活着的
+		* 持有者」与「有有效预留」——那两种已经有人会推，回捞抢了没意义。
+		*
+		* **候选不看待发队列是不是空的。** 队列不空不等于卡住——在等人答复、按设计排着后续
+		* 消息的对话，队列也不空，但永远推不动，会白白占满每次的 `limit`，挤掉真正卡住（打了
+		* 待接手标记）的那些。真正需要回捞推一把的队列，框架会在崩溃恢复、下线交接时主动打上
+		* 待接手标记，不需要这里再兜底扫队列。
+		*/
+		async listSweepCandidates(sweepOpts) {
+			const at = now();
+			const candidateIds = (await col.find({ awaitingTakeover: true }, { projection: { _id: 1 } }).toArray()).map((doc) => doc._id);
+			if (candidateIds.length === 0) return [];
+			const docs = await col.find({ _id: { $in: candidateIds } }).toArray();
+			const byId = new Map(docs.map((doc) => [doc._id, doc]));
+			const result = [];
+			for (const id of candidateIds) {
+				if (result.length >= sweepOpts.limit) break;
+				const doc = byId.get(id) ?? null;
+				if (doc !== null && isLive(doc, at)) continue;
+				if (activeReservedFor(doc, at) !== void 0) continue;
+				result.push(id);
+			}
+			return result;
+		}
+	};
 }
+//#endregion
+//#region src/nodes.ts
+/**
+* 建一个节点登记表。
+*
+* ```ts
+* const registry = mongoNodeRegistry(db);
+* await registry.register({ node: process.env.RUNKO_NODE_URL, releaseSeq: Number(process.env.RUNKO_RELEASE_SEQ) });
+* ```
+*/
+function mongoNodeRegistry(db, opts = {}) {
+	const now = opts.now ?? Date.now;
+	const col = db.collection(NODES_COLLECTION);
+	const leases = db.collection(LEASES_COLLECTION);
+	const toRecord = (doc) => ({
+		node: doc._id,
+		releaseSeq: doc.releaseSeq,
+		state: doc.state === "leaving" ? "leaving" : "ready",
+		heartbeatAt: doc.heartbeatAt,
+		startedAt: doc.startedAt
+	});
+	return {
+		async register(self) {
+			const at = now();
+			await col.updateOne({ _id: self.node }, { $set: {
+				releaseSeq: self.releaseSeq,
+				state: "ready",
+				heartbeatAt: at,
+				startedAt: at
+			} }, { upsert: true });
+		},
+		async heartbeat(node) {
+			await col.updateOne({ _id: node }, { $set: { heartbeatAt: now() } });
+		},
+		async markLeaving(node) {
+			await col.updateOne({ _id: node }, { $set: { state: "leaving" } });
+		},
+		async remove(node) {
+			await col.deleteOne({ _id: node });
+		},
+		async candidates(self, candOpts) {
+			const at = now();
+			const docs = await col.find({
+				_id: { $ne: self.node },
+				state: "ready",
+				heartbeatAt: { $gte: at - candOpts.freshMs },
+				releaseSeq: { $gte: self.releaseSeq }
+			}).toArray();
+			const loadDocs = await leases.find({ holder: { $ne: null } }, { projection: { holder: 1 } }).toArray();
+			const loadByHolder = /* @__PURE__ */ new Map();
+			for (const doc of loadDocs) {
+				if (doc.holder === null) continue;
+				loadByHolder.set(doc.holder, (loadByHolder.get(doc.holder) ?? 0) + 1);
+			}
+			const candidates = docs.map((doc) => ({
+				...toRecord(doc),
+				load: loadByHolder.get(doc._id) ?? 0
+			}));
+			candidates.sort((a, b) => {
+				const aTier = a.releaseSeq > self.releaseSeq ? 0 : 1;
+				const bTier = b.releaseSeq > self.releaseSeq ? 0 : 1;
+				if (aTier !== bTier) return aTier - bTier;
+				if (a.load !== b.load) return a.load - b.load;
+				return a.node < b.node ? -1 : a.node > b.node ? 1 : 0;
+			});
+			return candidates;
+		},
+		async list() {
+			return (await col.find({}).toArray()).map(toRecord);
+		}
+	};
+}
+//#endregion
+//#region src/migrate.ts
 /**
 * 建一个具名索引，**同名不同选项时删了重建**。
 *
@@ -338,6 +939,18 @@ async function migrate(db) {
 		}, {
 			unique: true,
 			name: "agent_queue_conversation_seq"
+		}),
+		ensureIndex(db, LEASES_COLLECTION, {
+			heartbeatAt: 1,
+			leaseToken: 1
+		}, { name: "agent_leases_heartbeat_token" }),
+		ensureIndex(db, LEASES_COLLECTION, { awaitingTakeover: 1 }, { name: "agent_leases_awaiting_takeover" }),
+		ensureIndex(db, TAILS_COLLECTION, {
+			conversationId: 1,
+			toolCallId: 1
+		}, {
+			unique: true,
+			name: "agent_tool_tails_conversation_call"
 		})
 	]);
 }
@@ -350,20 +963,28 @@ const RUNKO_PERSIST_MONGO_VERSION = "0.0.0";
 * **吃 `Db` 而不是 `MongoClient`**：选哪个 database 是宿主的决定（多租户可能一租户
 * 一个 db），连接的生命周期也归宿主管——本包不 connect、不 close。
 *
-* 三个集合固定叫 `agent_ledger` / `agent_decisions` / `agent_queue`，你自己的集合
-* 照常在同一个 db 里，互不干扰。
+* 四个集合固定叫 `agent_ledger` / `agent_decisions` / `agent_queue` / `agent_tool_tails`，
+* 你自己的集合照常在同一个 db 里，互不干扰。
 */
 function mongoPersistence(db) {
 	return {
 		ledger: createLedgerStore(db),
 		decisions: createDecisionStore(db),
-		queue: createQueueStore(db)
+		queue: createQueueStore(db),
+		tails: createToolTailStore(db)
 	};
 }
 //#endregion
 exports.DECISIONS_COLLECTION = DECISIONS_COLLECTION;
+exports.DEFAULT_HEARTBEAT_MS = DEFAULT_HEARTBEAT_MS;
+exports.DEFAULT_TAKEOVER_MS = DEFAULT_TAKEOVER_MS;
+exports.LEASES_COLLECTION = LEASES_COLLECTION;
 exports.LEDGER_COLLECTION = LEDGER_COLLECTION;
+exports.NODES_COLLECTION = NODES_COLLECTION;
 exports.QUEUE_COLLECTION = QUEUE_COLLECTION;
 exports.RUNKO_PERSIST_MONGO_VERSION = RUNKO_PERSIST_MONGO_VERSION;
+exports.TAILS_COLLECTION = TAILS_COLLECTION;
 exports.migrate = migrate;
+exports.mongoArbitration = mongoArbitration;
+exports.mongoNodeRegistry = mongoNodeRegistry;
 exports.mongoPersistence = mongoPersistence;