@steve02081504/fount-p2p 0.0.44 → 0.0.48

package/node/verification.mjs

@@ -0,0 +1,163 @@
+import { randomBytes } from 'node:crypto'
+
+import { isHex64 } from '../core/hexIds.mjs'
+import { sendToNodeLink } from '../transport/link_registry.mjs'
+import { attachNodeScopeFeature } from '../transport/node_scope/features.mjs'
+
+import { getNodeHash } from './identity.mjs'
+
+const MAX_TIMEOUT = 30 * 60 * 1000
+
+/**
+ * @typedef {{ challenge: string, requesterNodeHash: string, expiresAt: number }} NetworkChallenge 挑战
+ */
+
+/**
+ * 创建有界的挑战服务；发送方身份一律取自已认证的网络入口，不信任载荷自称。
+ * @param {{nodeHash: string, send: (peer: string, action: string, payload: object) => Promise<boolean>, now?: () => number}} options 依赖
+ * @returns {object} 挑战服务
+ */
+export function createNetworkVerificationService({ nodeHash, send, now = Date.now }) {
+	const requests = new Map()
+	const proofs = new Map()
+	/**
+	 * 清理已过期的挑战记录。
+	 * @returns {void} 无返回值
+	 */
+	function prune() {
+		for (const [id, entry] of requests) if (entry.expiresAt + 60000 < now()) requests.delete(id)
+	}
+	/**
+	 * 取挑战快照，并把已过期的 pending 收敛为 failed。
+	 * @param {object} entry 挑战状态
+	 * @returns {object} 快照
+	 */
+	function snapshot(entry) {
+		if (entry.status === 'pending' && now() >= entry.expiresAt) entry.status = 'failed', entry.reason = 'timeout'
+		return { ...entry }
+	}
+	return {
+		/**
+		 * 新建一个挑战：限幅超时、限制在途数量，返回待验证快照。
+		 * @param {{ timeoutMs?: number }} [options] 超时选项
+		 * @returns {object} 待验证快照
+		 */
+		create({ timeoutMs = 300000 } = {}) {
+			if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_TIMEOUT) throw new Error('invalid timeoutMs')
+			prune()
+			if (requests.size >= 1024) throw new Error('too many verification requests')
+			const challenge = randomBytes(32).toString('hex')
+			const entry = { challenge, requesterNodeHash: nodeHash, expiresAt: now() + timeoutMs, status: 'pending' }
+			requests.set(challenge, entry)
+			return snapshot(entry)
+		},
+		/**
+		 * 按挑战串读取快照；不存在返回 null。
+		 * @param {string} challenge 挑战串
+		 * @returns {object|null} 快照
+		 */
+		get(challenge) {
+			prune()
+			const entry = requests.get(challenge)
+			return entry ? snapshot(entry) : null
+		},
+		/**
+		 * 处理入站 verification_claim / verification_receipt 动作。
+		 * @param {string} action 网络动作
+		 * @param {object} payload 网络载荷
+		 * @param {string} sender 已认证身份
+		 */
+		async receive(action, payload, sender) {
+			if (!isHex64(sender) || !isHex64(payload?.challenge)) return
+			if (action === 'verification_claim') {
+				const entry = requests.get(payload.challenge)
+				if (!entry || now() >= entry.expiresAt || snapshot(entry).status === 'failed' || entry.expiresAt !== payload.expiresAt) return
+				if (entry.status === 'verified' && entry.nodeHash !== sender) return
+				entry.status = 'verified'
+				entry.nodeHash = sender
+				await send(sender, 'verification_receipt', { challenge: entry.challenge, expiresAt: entry.expiresAt })
+			}
+			if (action === 'verification_receipt') {
+				const proof = proofs.get(payload.challenge)
+				if (proof && proof.requesterNodeHash === sender && proof.expiresAt === payload.expiresAt && now() < proof.expiresAt)
+					proof.resolve({ status: 'verified', nodeHash })
+			}
+		},
+		/**
+		 * 向请求方发起验证并等待回执（去重、并发上限、超时收敛为 failed）。
+		 * @param {NetworkChallenge} request 挑战请求
+		 * @returns {Promise<object>} 验证结果
+		 */
+		async prove({ requesterNodeHash, challenge, expiresAt }) {
+			if (!isHex64(requesterNodeHash) || !isHex64(challenge) || !Number.isSafeInteger(expiresAt) || expiresAt <= now() || expiresAt > now() + MAX_TIMEOUT)
+				return { status: 'failed', reason: 'invalid challenge' }
+			if (proofs.has(challenge)) {
+				const existing = proofs.get(challenge)
+				if (existing.requesterNodeHash !== requesterNodeHash || existing.expiresAt !== expiresAt) return { status: 'failed', reason: 'challenge mismatch' }
+				return existing.promise
+			}
+			if (proofs.size >= 64) return { status: 'failed', reason: 'busy' }
+			let resolve
+			const promise = new Promise(done => { resolve = done })
+			proofs.set(challenge, { requesterNodeHash, expiresAt, resolve, promise })
+			const timer = setTimeout(() => resolve({ status: 'failed', reason: 'timeout' }), Math.min(expiresAt - now(), 15000))
+			try {
+				void send(requesterNodeHash, 'verification_claim', { challenge, expiresAt }).then(sent => {
+					if (!sent) resolve({ status: 'failed', reason: 'unreachable' })
+				}, () => resolve({ status: 'failed', reason: 'unreachable' }))
+				return await promise
+			}
+			finally { clearTimeout(timer); proofs.delete(challenge) }
+		},
+	}
+}
+
+let service
+/**
+ * 把验证动作挂到正在运行的节点的 node scope 上。
+ * @returns {() => void} 卸载 dispose
+ */
+export function attachNetworkVerification() {
+	return attachNodeScopeFeature('verification', wire => {
+		const current = getNetworkVerificationService()
+		const disposers = ['verification_claim', 'verification_receipt'].map(action => wire.on(action, (payload, sender) => {
+			void current.receive(action, payload, sender).catch(() => {})
+		}))
+		return () => { for (const dispose of disposers) dispose(); service = null }
+	})
+}
+
+/**
+ * 取当前节点的验证服务（懒创建单例）。
+ * @returns {ReturnType<typeof createNetworkVerificationService>} 验证服务
+ */
+export function getNetworkVerificationService() {
+	if (!service) service = createNetworkVerificationService({ nodeHash: getNodeHash(), send: sendVerificationEnvelope })
+	return service
+}
+
+/**
+ * 经已认证链路投递验证消息；请求方就是本节点时直接走本地入口。
+ * @param {string} peer 目标身份
+ * @param {string} action 网络动作
+ * @param {object} payload 网络载荷
+ * @returns {Promise<boolean>} 是否已投递
+ */
+async function sendVerificationEnvelope(peer, action, payload) {
+	if (peer === getNodeHash()) {
+		await getNetworkVerificationService().receive(action, payload, peer)
+		return true
+	}
+	return await sendToNodeLink(peer, { scope: 'node', action, payload })
+}
+
+/**
+ * 单次自证：证明本节点可达请求方并收到其回执。
+ * @param {NetworkChallenge} request 挑战请求
+ * @returns {Promise<object>} 验证结果
+ */
+export async function proveNetworkVerification(request) {
+	const dispose = attachNetworkVerification()
+	try { return await getNetworkVerificationService().prove(request) }
+	finally { dispose() }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@steve02081504/fount-p2p",
-	"version": "0.0.44",
+	"version": "0.0.48",
 	"description": "fount federation P2P layer — link, trust graph, mailbox, DAG, EVFS.",
 	"keywords": [
 		"network",
@@ -25,7 +25,9 @@
 		"test:fount": "deno test -A --config deno.json test/fount/",
 		"test:live": "node --test --test-concurrency=1 --test-force-exit test/live/*.test.mjs",
 		"test:sim": "node --test --test-concurrency=1 --test-force-exit sim/test/*.test.mjs",
-		"test:frontend": "node --test --test-concurrency=1 --test-force-exit test/frontend/*.test.mjs"
+		"test:frontend": "node --test --test-concurrency=1 --test-force-exit test/frontend/*.test.mjs",
+		"test:checks": "node --test --test-concurrency=1 --test-force-exit test/pure/text_lf.test.mjs test/pure/jsdoc_no_english.test.mjs test/pure/agents_md_english.test.mjs",
+		"check:text_lf:fix": "node scripts/checks/text_lf.mjs --fix .."
 	},
 	"bin": {
 		"fount-p2p": "infra/cli.mjs"

package/sim/AGENTS.md

@@ -15,7 +15,7 @@ In-process co-evolution of **tunables** (`*.tunables.json`) against an **attack
 - **`PARAM_SPACE` ↔ defaults:** every `PARAM_SPACE` key must exist in `loadDefaultTunables()`; clear both sides when deleting a key.
 - **`socialRepHideThreshold`:** hide when `score < threshold`. Default `0` (suppress negatives only). Raise the threshold to raise `falsePositiveRate` — never use a negative threshold for "stricter".
 - **Heuristic proxy** (not the real path): `model.mjs`, `discovery.mjs`, `transport.mjs`, `integrity.mjs` — analytical "params → defense" only.
-- **Mesh-first:** explore slots and cold-start join are mandatory; fanout/trust stay separate from link presence. Policy: [docs/mesh.md](../docs/mesh.md). Wiring: [cold_start.md](cold_start.md).
+- **Mesh-first:** explore slots and cold-start join are mandatory; fanout/trust stay separate from link presence. Policy: [docs/mesh.md](../docs/mesh.md). Wiring: [docs/cold_start.md](docs/cold_start.md).
 
 ## Anti-drift
 

package/sim/{cold_start.md → docs/cold_start.md}

@@ -1,6 +1,6 @@
 # Sim cold-start (K = 0)
 
-Mesh policy: [docs/mesh.md](../docs/mesh.md). Day-to-day sim rules: [AGENTS.md](AGENTS.md).
+Mesh policy: [mesh.md](../../docs/mesh.md). Day-to-day sim rules: [AGENTS.md](../AGENTS.md).
 
 When the observer has no acquaintances (`trustedPeers=[]`), the sim must still join via discovery explore slots — not idle.
 

package/timeline/prune.mjs

@@ -1,13 +1,14 @@
-import { mkdir } from 'node:fs/promises'
-import { dirname } from 'node:path'
-
 import { topologicalCanonicalOrder } from '../dag/index.mjs'
-import { readJsonl, writeJsonlSynced } from '../dag/storage.mjs'
+import { jsonlMutexKey, readJsonlEntries, writeJsonlLines } from '../dag/storage.mjs'
 import { invalidateTopologicalOrderMemo } from '../federation/topo_order_memo.mjs'
 import { descendantClosureFromTip } from '../governance/branch.mjs'
+import { withAsyncMutex } from '../utils/async_mutex.mjs'
 
 /**
  * 将 events.jsonl 裁剪为 checkpoint 起后代闭包（连通子图，非拓扑下标切片）。
+ *
+ * 整个读-算-写在 `jsonlMutexKey(eventsFilePath)` 锁内完成，避免与并发 append 竞态；
+ * 写回的是保留行的原始字节（非 sanitize 后的重序列化），保持无损失。
  * @param {string} eventsFilePath events.jsonl 路径
  * @param {object | null} checkpoint 含 checkpoint_event_id 的快照
  * @param {(row: object) => object} [sanitize] 行规范化
@@ -16,24 +17,27 @@ import { descendantClosureFromTip } from '../governance/branch.mjs'
 export async function pruneEventsJsonlAfterCheckpoint(eventsFilePath, checkpoint, sanitize = row => row) {
 	const tipId = checkpoint?.checkpoint_event_id
 	if (!tipId) return { pruned: false, kept: 0, dropped: 0 }
-	const events = await readJsonl(eventsFilePath, { sanitize })
-	if (!events.length) return { pruned: false, kept: 0, dropped: 0 }
-	const byId = new Map(events.map(dagEvent => [dagEvent.id, dagEvent]))
-	if (!byId.has(tipId)) return { pruned: false, kept: events.length, dropped: 0 }
+	return withAsyncMutex(jsonlMutexKey(eventsFilePath), async () => {
+		const entries = await readJsonlEntries(eventsFilePath, { sanitize })
+		if (!entries.length) return { pruned: false, kept: 0, dropped: 0 }
+		const byId = new Map(entries.map(entry => [entry.row.id, entry.row]))
+		const rawById = new Map(entries.map(entry => [entry.row.id, entry.raw]))
+		if (!byId.has(tipId)) return { pruned: false, kept: entries.length, dropped: 0 }
 
-	const keepIds = descendantClosureFromTip(tipId, byId)
-	const order = topologicalCanonicalOrder(events.map(dagEvent => ({
-		id: dagEvent.id,
-		prev_event_ids: dagEvent.prev_event_ids,
-		hlc: dagEvent.hlc,
-		node_id: dagEvent.node_id,
-		sender: dagEvent.sender,
-	})))
-	const kept = order.map(id => byId.get(id)).filter(ev => ev && keepIds.has(ev.id))
-	const dropped = events.length - kept.length
-	if (dropped <= 0) return { pruned: false, kept: kept.length, dropped: 0 }
-	await mkdir(dirname(eventsFilePath), { recursive: true })
-	await writeJsonlSynced(eventsFilePath, kept)
-	invalidateTopologicalOrderMemo(eventsFilePath)
-	return { pruned: true, kept: kept.length, dropped }
+		const keepIds = descendantClosureFromTip(tipId, byId)
+		const order = topologicalCanonicalOrder(entries.map(entry => ({
+			id: entry.row.id,
+			prev_event_ids: entry.row.prev_event_ids,
+			hlc: entry.row.hlc,
+			node_id: entry.row.node_id,
+			sender: entry.row.sender,
+		})))
+		const keptIds = order.filter(id => keepIds.has(id))
+		const dropped = entries.length - keptIds.length
+		if (dropped <= 0) return { pruned: false, kept: keptIds.length, dropped: 0 }
+		const keptRaws = keptIds.map(id => rawById.get(id)).filter(raw => raw !== undefined)
+		await writeJsonlLines(eventsFilePath, keptRaws)
+		invalidateTopologicalOrderMemo(eventsFilePath)
+		return { pruned: true, kept: keptIds.length, dropped }
+	})
 }

package/timeline/retention.mjs

@@ -1,13 +1,13 @@
-import { mkdir } from 'node:fs/promises'
-import { dirname } from 'node:path'
-
 import { topologicalCanonicalOrder } from '../dag/index.mjs'
-import { readJsonl, writeJsonlSynced } from '../dag/storage.mjs'
+import { jsonlMutexKey, readJsonlEntries, writeJsonlLines } from '../dag/storage.mjs'
 import { invalidateTopologicalOrderMemo } from '../federation/topo_order_memo.mjs'
 import { computeDagTipIdsFromEvents, selectConsensusBranchTip } from '../governance/branch.mjs'
 import { computeRetentionKeepIds } from '../node/retention_policy.mjs'
+import { withAsyncMutex } from '../utils/async_mutex.mjs'
 
 /**
+ * 整个读-算-写在 `jsonlMutexKey(eventsFilePath)` 锁内完成，避免与并发 append 竞态；
+ * 写回的是保留行的原始字节（非 sanitize 后的重序列化），保持无损失。
  * @param {string} eventsFilePath events.jsonl 路径
  * @param {object | null} checkpointHint 检查点提示
  * @param {{ maxDepth: number, maxMs: number, anchorTypes: Set<string> }} policy 保留策略
@@ -20,35 +20,39 @@ export async function enforceTimelineEventRetention(
 	policy,
 	sanitize = row => row,
 ) {
-	const events = await readJsonl(eventsFilePath, { sanitize })
-	if (!events.length) return { pruned: false, kept: 0, dropped: 0 }
-	const maxDepth = Math.max(256, Number(policy.maxDepth) || 200_000)
-	const maxMs = Math.max(3_600_000, Number(policy.maxMs) || 365 * 24 * 3600 * 1000)
-	const cutoffWall = Date.now() - maxMs
-	const byId = new Map(events.map(e => [e.id, e]))
-	const order = topologicalCanonicalOrder(events.map(e => ({
-		id: e.id,
-		prev_event_ids: e.prev_event_ids,
-		hlc: e.hlc,
-		node_id: e.node_id,
-		sender: e.sender,
-	})))
-	const tips = computeDagTipIdsFromEvents(events)
-	const branchTipId = selectConsensusBranchTip(tips, byId)
-	const checkpointTipId = checkpointHint?.checkpoint_event_id || null
-	const keepIds = computeRetentionKeepIds(order, byId, {
-		maxDepth,
-		cutoffWall,
-		anchorTypes: policy.anchorTypes,
-		checkpointTipId,
-		branchTipId,
+	return withAsyncMutex(jsonlMutexKey(eventsFilePath), async () => {
+		const entries = await readJsonlEntries(eventsFilePath, { sanitize })
+		if (!entries.length) return { pruned: false, kept: 0, dropped: 0 }
+		const maxDepth = Math.max(256, Number(policy.maxDepth) || 200_000)
+		const maxMs = Math.max(3_600_000, Number(policy.maxMs) || 365 * 24 * 3600 * 1000)
+		const cutoffWall = Date.now() - maxMs
+		const events = entries.map(entry => entry.row)
+		const rawById = new Map(entries.map(entry => [entry.row.id, entry.raw]))
+		const byId = new Map(events.map(e => [e.id, e]))
+		const order = topologicalCanonicalOrder(events.map(e => ({
+			id: e.id,
+			prev_event_ids: e.prev_event_ids,
+			hlc: e.hlc,
+			node_id: e.node_id,
+			sender: e.sender,
+		})))
+		const tips = computeDagTipIdsFromEvents(events)
+		const branchTipId = selectConsensusBranchTip(tips, byId)
+		const checkpointTipId = checkpointHint?.checkpoint_event_id || null
+		const keepIds = computeRetentionKeepIds(order, byId, {
+			maxDepth,
+			cutoffWall,
+			anchorTypes: policy.anchorTypes,
+			checkpointTipId,
+			branchTipId,
+		})
+		if (keepIds.size >= events.length) return { pruned: false, kept: events.length, dropped: 0 }
+		const keptIds = order.filter(id => keepIds.has(id))
+		const dropped = events.length - keptIds.length
+		if (dropped <= 0) return { pruned: false, kept: keptIds.length, dropped: 0 }
+		const keptRaws = keptIds.map(id => rawById.get(id)).filter(raw => raw !== undefined)
+		await writeJsonlLines(eventsFilePath, keptRaws)
+		invalidateTopologicalOrderMemo(eventsFilePath)
+		return { pruned: true, kept: keptIds.length, dropped }
 	})
-	if (keepIds.size >= events.length) return { pruned: false, kept: events.length, dropped: 0 }
-	const kept = order.map(id => byId.get(id)).filter(ev => ev && keepIds.has(ev.id))
-	const dropped = events.length - kept.length
-	if (dropped <= 0) return { pruned: false, kept: kept.length, dropped: 0 }
-	await mkdir(dirname(eventsFilePath), { recursive: true })
-	await writeJsonlSynced(eventsFilePath, kept)
-	invalidateTopologicalOrderMemo(eventsFilePath)
-	return { pruned: true, kept: kept.length, dropped }
 }

package/transport/link_registry.mjs

@@ -25,6 +25,24 @@ import { createRuntimeBootstrap } from './runtime_bootstrap.mjs'
 const DIAL_COOLDOWN_BASE_MS = ms('30s')
 /** dial 冷却上限。 */
 const DIAL_COOLDOWN_MAX_MS = ms('10m')
+/**
+ * 单次确保直连的整体上限：覆盖全部 provider 尝试（含 offer/answer 握手）后必须结算。
+ * 必须大于 nostr 入队 publish 等待上限，让「relay 连不上」走 provider 自身的失败路径，
+ * 而不是在这里被掐断（否则拿不到 provider 级诊断）。见 fount-p2p#37。
+ */
+export const LINK_DIAL_DEADLINE_MS = ms('90s')
+
+/** 测试可缩短的单次直连上限。 */
+let dialDeadlineMs = LINK_DIAL_DEADLINE_MS
+
+/**
+ * 覆盖单次直连上限（测试用；传 null 恢复默认）。
+ * @param {number | null} value 毫秒上限；null 恢复默认
+ * @returns {void}
+ */
+export function setLinkDialDeadlineMsForTests(value) {
+	dialDeadlineMs = value == null ? LINK_DIAL_DEADLINE_MS : value
+}
 
 /**
  * 解析或从节点种子推导本地身份。
@@ -263,8 +281,58 @@ export function createLinkRegistry(options = {}) {
 		return links.get(remoteNodeHash) ?? null
 	}
 
+	/**
+	 * 记一次 dial 失败并进入指数退避。
+	 * @param {string} normalized 远端节点 64 hex
+	 * @returns {number} 本次冷却毫秒
+	 */
+	function noteDialFailure(normalized) {
+		const failures = (dialCooldown.get(normalized)?.failures || 0) + 1
+		const delay = Math.min(DIAL_COOLDOWN_MAX_MS, DIAL_COOLDOWN_BASE_MS * (2 ** Math.min(failures - 1, 5)))
+		dialCooldown.touch(normalized, { until: Date.now() + delay, failures })
+		return delay
+	}
+
+	/**
+	 * 为一个已登记的直连尝试套上整体上限：超时即返回 null（调用方不再等），
+	 * 后台尝试照旧收敛，成功仍会注册链路。
+	 *
+	 * 超时后立刻从 inflights 摘除，后续 dial 走新尝试而不是复用这个卡住的 promise。
+	 * @param {string} normalized 远端节点 64 hex
+	 * @param {Promise<object | null>} task 进行中的 dial
+	 * @returns {Promise<object | null>} dial 结果；超时 null
+	 */
+	async function awaitDialAttempt(normalized, task) {
+		if (dialDeadlineMs <= 0) return await task
+		/** @type {boolean} */
+		let expired = false
+		/** @type {ReturnType<typeof setTimeout> | null} */
+		let timer = null
+		const timeout = new Promise(resolve => {
+			timer = setTimeout(() => {
+				expired = true
+				resolve(null)
+			}, dialDeadlineMs)
+			timer.unref?.()
+		})
+		const link = await Promise.race([task, timeout])
+		if (timer) clearTimeout(timer)
+		if (!expired) return link
+		// 超时：调用方不再等，但后台尝试仍会自行收敛（成功照样注册链路，失败自己记冷却）。
+		if (inflights.get(normalized) === task) inflights.delete(normalized)
+		const cooldownMs = noteDialFailure(normalized)
+		nodeDebug('p2p:dial deadline', {
+			peer: shortHash(normalized),
+			deadlineMs: dialDeadlineMs,
+			cooldownMs,
+		})
+		return null
+	}
+
 	/**
 	 * 按 level 降序尝试各 LinkProvider，不可用/不可达/失败则回落。
+	 * 整体有 LINK_DIAL_DEADLINE_MS 上限：卡住的 provider 既不能让调用方永久等待，
+	 * 也不能把坏 promise 留在 inflights 里毒化后续 dial。
 	 * @param {string} remoteNodeHash 远端节点 64 hex
 	 * @returns {Promise<object | null>} 链路实例；失败时 null
 	 */
@@ -274,7 +342,7 @@ export function createLinkRegistry(options = {}) {
 		const normalized = remoteNodeHash
 		if (!normalized || normalized === localIdentity.nodeHash) return null
 		if (links.has(normalized)) return links.get(normalized)
-		if (inflights.has(normalized)) return await inflights.get(normalized)
+		if (inflights.has(normalized)) return await awaitDialAttempt(normalized, inflights.get(normalized))
 		const cool = dialCooldown.get(normalized)
 		const now = Date.now()
 		if (cool) {
@@ -335,14 +403,12 @@ export function createLinkRegistry(options = {}) {
 					})
 				}
 
-			const failures = (cool?.failures || 0) + 1
-			const delay = Math.min(DIAL_COOLDOWN_MAX_MS, DIAL_COOLDOWN_BASE_MS * (2 ** Math.min(failures - 1, 5)))
-			dialCooldown.touch(normalized, { until: Date.now() + delay, failures })
-			nodeDebug('p2p:dial exhausted', { peer: shortHash(normalized), cooldownMs: delay, failures })
+			const cooldownMs = noteDialFailure(normalized)
+			nodeDebug('p2p:dial exhausted', { peer: shortHash(normalized), cooldownMs })
 			return null
 		})().finally(() => inflights.delete(normalized))
 		inflights.set(normalized, task)
-		return await task
+		return await awaitDialAttempt(normalized, task)
 	}
 
 	meshKeepalive = createMeshKeepalive({
@@ -387,9 +453,12 @@ export function createLinkRegistry(options = {}) {
 
 	/**
 	 * 启动 discovery/link runtime 并开启 mesh keepalive。
+	 * 顺带重启 peer health 订阅：`shutdown()` 会停掉它，重启运行时后必须重新挂上，
+	 * 否则 getPeerHealth / listPeerHealth 会永远为空（见 fount-p2p#38）。
 	 */
 	const ensureRuntimeWithMesh = async () => {
 		await bootstrap.ensureRuntime()
+		peerHealth.start()
 		meshKeepalive?.start()
 	}
 

package/transport/peer_health.mjs

@@ -19,6 +19,7 @@ import { emitSafe } from '../utils/emit_safe.mjs'
  *   getPeerHealth: (nodeHash: string) => PeerHealthEntry | null
  *   listPeerHealth: () => PeerHealthEntry[]
  *   onPeerHealth: (listener: (nodeHash: string, entry: PeerHealthEntry) => void) => () => void
+ *   start: () => void
  *   stop: () => void
  * }} peer health 聚合器
  */
@@ -29,6 +30,10 @@ export function createPeerHealthTracker(registry) {
 	const cleanups = new Map()
 	/** @type {Set<(nodeHash: string, entry: PeerHealthEntry) => void>} */
 	const listeners = new Set()
+	/** @type {(() => void) | null} registry link up 退订 */
+	let stopUp = null
+	/** @type {(() => void) | null} registry link down 退订 */
+	let stopDown = null
 
 	/**
 	 * 合并补丁并通知订阅方。
@@ -54,37 +59,48 @@ export function createPeerHealthTracker(registry) {
 		emitSafe(listeners, nodeHash, entry)
 	}
 
-	const stopUp = registry.onLinkUp?.((nodeHash, link) => {
-		if (!nodeHash) return
-		const stopRtt = link?.onRtt?.(() => {
-			const stats = link.stats?.() ?? {}
+	/**
+	 * 订阅 registry 的链路事件（幂等）。
+	 * `stop()` 之后可用它重新挂上监听：registry 的 link up/down 桶在 shutdown 时不会被清空，
+	 * 所以重启运行时后健康记录能自然恢复。
+	 * @returns {void}
+	 */
+	function start() {
+		if (stopUp) return
+		stopUp = registry.onLinkUp?.((nodeHash, link) => {
+			if (!nodeHash) return
+			const stopRtt = link?.onRtt?.(() => {
+				const stats = link.stats?.() ?? {}
+				update(nodeHash, {
+					rttMs: stats.rttMs ?? null,
+					avgRttMs: stats.avgRttMs ?? null,
+					lastSeenAt: Date.now(),
+				})
+			}) ?? null
+			const stopLinkDown = link?.onDown?.(() => {
+				cleanups.get(nodeHash)?.()
+				cleanups.delete(nodeHash)
+				update(nodeHash, { connected: false, lastSeenAt: Date.now() })
+			}) ?? null
 			update(nodeHash, {
-				rttMs: stats.rttMs ?? null,
-				avgRttMs: stats.avgRttMs ?? null,
+				connected: true,
+				source: link?.providerId ?? null,
 				lastSeenAt: Date.now(),
 			})
+			cleanups.set(nodeHash, () => {
+				stopRtt?.()
+				stopLinkDown?.()
+			})
 		}) ?? null
-		const stopDown = link?.onDown?.(() => {
+		stopDown = registry.onLinkDown?.(nodeHash => {
+			if (!nodeHash) return
 			cleanups.get(nodeHash)?.()
 			cleanups.delete(nodeHash)
 			update(nodeHash, { connected: false, lastSeenAt: Date.now() })
 		}) ?? null
-		update(nodeHash, {
-			connected: true,
-			source: link?.providerId ?? null,
-			lastSeenAt: Date.now(),
-		})
-		cleanups.set(nodeHash, () => {
-			stopRtt?.()
-			stopDown?.()
-		})
-	}) ?? null
-	const stopDown = registry.onLinkDown?.(nodeHash => {
-		if (!nodeHash) return
-		cleanups.get(nodeHash)?.()
-		cleanups.delete(nodeHash)
-		update(nodeHash, { connected: false, lastSeenAt: Date.now() })
-	}) ?? null
+	}
+
+	start()
 
 	return {
 		/**
@@ -108,17 +124,19 @@ export function createPeerHealthTracker(registry) {
 			listeners.add(listener)
 			return () => listeners.delete(listener)
 		},
+		start,
 		/**
-		 * 停止监听并清空聚合。
+		 * 停止监听并清空聚合（listen 订阅保留，listeners 订阅者保留）。
 		 * @returns {void}
 		 */
 		stop() {
 			stopUp?.()
 			stopDown?.()
+			stopUp = null
+			stopDown = null
 			for (const cleanup of cleanups.values()) cleanup()
 			cleanups.clear()
 			entries.clear()
-			listeners.clear()
 		},
 	}
 }