@steve02081504/fount-p2p 0.0.44 → 0.0.48

package/discovery/nostr/session.mjs

@@ -16,6 +16,24 @@ const NOSTR_PUBLISH_OK_TIMEOUT_MS = 3_000
 const NOSTR_RECONNECT_DELAY_MS = 500
 /** 无 sub/publish 工作时共享 relay 空闲回收延迟（给连续 send 复用窗口）。 */
 const NOSTR_IDLE_DROP_MS = 2_000
+/**
+ * 已入队 publish 的等待上限（从入队起算，覆盖多次「连不上 → 退避重连」）。
+ * 连接超时 2s + 重连间隔 0.5s ≈ 2.5s/轮，20s 约等于 8 轮；连不上的 relay 必须结算，
+ * 否则请求永久留在 pendingPublishes 里（见 fount-p2p#37）。
+ */
+export const NOSTR_QUEUED_PUBLISH_DEADLINE_MS = 20_000
+
+/** 测试可缩短的入队 publish 等待上限。 */
+let queuedPublishDeadlineMs = NOSTR_QUEUED_PUBLISH_DEADLINE_MS
+
+/**
+ * 覆盖入队 publish 等待上限（测试用；传 null 恢复默认）。
+ * @param {number | null} value 毫秒上限；null 恢复默认
+ * @returns {void}
+ */
+export function setQueuedPublishDeadlineMsForTests(value) {
+	queuedPublishDeadlineMs = value == null ? NOSTR_QUEUED_PUBLISH_DEADLINE_MS : value
+}
 
 /**
  * @param {string[] | undefined | null} urls 原始列表
@@ -216,6 +234,7 @@ function publishEventOnRelay(ws, relayUrl, event, signal, isCurrent) {
  *   attempt: number,
  *   onAbort: (() => void) | null,
  *   removeAbort: (() => void) | null,
+ *   deadline: ReturnType<typeof setTimeout> | null,
  *   resolve: (ok: boolean) => void,
  *   reject: (err: Error) => void,
  * }} NostrPublishRequest
@@ -326,7 +345,7 @@ function attachSharedRelaySocket(relayUrl, session, ws) {
 		if (session.inflightPublishes.length) {
 			session.pendingPublishes.push(...session.inflightPublishes)
 			for (const publishRequest of session.inflightPublishes)
-				attachQueuedAbort(session, publishRequest)
+				attachQueuedAbort(relayUrl, session, publishRequest)
 			session.inflightPublishes = []
 		}
 		if (!hasPendingWork(session)) {
@@ -465,6 +484,8 @@ function flushPendingPublishes(relayUrl, session, socket) {
 		publishRequest.removeAbort?.()
 		publishRequest.onAbort = null
 		publishRequest.removeAbort = null
+		// 请求已进入实际发送：等待上限改由本次 send 的 OK 超时负责。
+		clearQueuedDeadline(publishRequest)
 		const attempt = ++publishRequest.attempt
 		session.inflightPublishes.push(publishRequest)
 		void publishEventOnRelay(socket, relayUrl, publishRequest.event, publishRequest.signal, () => publishRequest.attempt === attempt)
@@ -475,23 +496,83 @@ function flushPendingPublishes(relayUrl, session, socket) {
 	}
 }
 
+/**
+ * 清除待发请求的等待上限定时器。
+ * @param {NostrPublishRequest} publishRequest 待发请求
+ * @returns {void}
+ */
+function clearQueuedDeadline(publishRequest) {
+	if (!publishRequest.deadline) return
+	clearTimeout(publishRequest.deadline)
+	publishRequest.deadline = null
+}
+
+/**
+ * 把一个尚未发出的 publish 移出队列并清掉它的等待上限。
+ * 队列已在别处清空（已 flush 到 socket / 已 abort）时返回 false。
+ * @param {string} relayUrl 中继 URL
+ * @param {SharedRelaySession} session 会话
+ * @param {NostrPublishRequest} publishRequest 待发请求
+ * @returns {boolean} 是否确实已出队
+ */
+function dequeueQueuedPublish(relayUrl, session, publishRequest) {
+	const pendingIndex = session.pendingPublishes.indexOf(publishRequest)
+	if (pendingIndex < 0) return false
+	clearQueuedDeadline(publishRequest)
+	publishRequest.removeAbort?.()
+	publishRequest.onAbort = null
+	publishRequest.removeAbort = null
+	session.pendingPublishes.splice(pendingIndex, 1)
+	// 这条 relay 已无任何工作：立刻回收，别把连不上的 socket / 重连循环留在进程里。
+	if (!hasPendingWork(session)) {
+		sharedRelaySessions.delete(relayUrl)
+		clearSharedRelayReconnect(session)
+		if (session.ws) dropWebSocket(session.ws)
+		session.ws = null
+	}
+	return true
+}
+
+/**
+ * 为队列中的 publish 挂上等待上限：从入队起算，超时即 reject 并出队。
+ * 只覆盖「尚未拿到可用 socket」的阶段；已 flush 到 open socket 的请求由 publishEventOnRelay 的 OK 超时负责。
+ * 定时器跨断线重发保留（请求在 pending ↔ inflight 间移动时不重置），故僵尸请求的总等待有界。
+ * @param {string} relayUrl 中继 URL
+ * @param {SharedRelaySession} session 会话
+ * @param {NostrPublishRequest} publishRequest 待发请求
+ * @returns {void}
+ */
+function attachQueuedDeadline(relayUrl, session, publishRequest) {
+	clearQueuedDeadline(publishRequest)
+	if (queuedPublishDeadlineMs <= 0) return
+	const timer = setTimeout(() => {
+		publishRequest.deadline = null
+		if (!dequeueQueuedPublish(relayUrl, session, publishRequest)) return
+		nodeDebug('p2p:nostr publish deadline', {
+			url: relayUrl,
+			err: `nostr: connect timeout for ${relayUrl}`,
+		})
+		publishRequest.reject(new Error(`nostr: connect timeout for ${relayUrl}`))
+	}, queuedPublishDeadlineMs)
+	timer.unref?.()
+	publishRequest.deadline = timer
+}
+
 /**
  * 为队列中的 publish 挂上 abort 处理：先移除监听器（释放 signal 对回调/event/session 的引用），
  * 再从队列删除并 reject。
+ * @param {string} relayUrl 中继 URL
  * @param {SharedRelaySession} session 会话
  * @param {SharedRelaySession['pendingPublishes'][number]} publishRequest 待发请求
  * @returns {void}
  */
-function attachQueuedAbort(session, publishRequest) {
+function attachQueuedAbort(relayUrl, session, publishRequest) {
 	const { signal, reject } = publishRequest
 	/**
 	 * 处理 abort 事件
 	 */
 	publishRequest.onAbort = () => {
-		publishRequest.removeAbort?.()
-		const pendingIndex = session.pendingPublishes.indexOf(publishRequest)
-		if (pendingIndex < 0) return
-		session.pendingPublishes.splice(pendingIndex, 1)
+		if (!dequeueQueuedPublish(relayUrl, session, publishRequest)) return
 		reject(new Error('nostr: aborted'))
 	}
 	/**
@@ -525,7 +606,8 @@ function settleInflightPublish(relayUrl, session, publishRequest, attempt, settl
 
 /**
  * 通过共享 relay 会话发布 EVENT：复用已打开 socket，避免每次 send 重开一条连接（内存泄漏）。
- * 无现成连接时入队并触发连接，连上后由 flushPendingPublishes 统一派发。
+ * 无现成连接时入队并触发连接，连上后由 flushPendingPublishes 统一派发；
+ * 连不上的 relay 由入队等待上限（NOSTR_QUEUED_PUBLISH_DEADLINE_MS）reject，不会永久悬挂。
  * @param {string} relayUrl 中继 URL
  * @param {object} event 待发布事件
  * @param {AbortSignal} [signal] 取消信号
@@ -541,13 +623,15 @@ export function publishViaSharedRelay(relayUrl, event, signal, connectTarget) {
 		const session = acquireSharedRelay(relayUrl, connectTarget)
 		clearIdleDrop(session)
 		/** @type {SharedRelaySession['pendingPublishes'][number]} */
-		const publishRequest = { event, signal, attempt: 0, resolve, reject, onAbort: null, removeAbort: null }
-		attachQueuedAbort(session, publishRequest)
+		const publishRequest = { event, signal, attempt: 0, deadline: null, resolve, reject, onAbort: null, removeAbort: null }
+		attachQueuedAbort(relayUrl, session, publishRequest)
 		session.pendingPublishes.push(publishRequest)
-		if (session.ws?.readyState === WebSocket.OPEN)
+		if (session.ws?.readyState === WebSocket.OPEN) {
 			flushPendingPublishes(relayUrl, session, session.ws)
-		else
-			scheduleSharedRelayConnect(relayUrl, session)
+			return
+		}
+		attachQueuedDeadline(relayUrl, session, publishRequest)
+		scheduleSharedRelayConnect(relayUrl, session)
 	})
 }
 

package/docs/nostr_relay_discovery.md

@@ -3,6 +3,7 @@
 Nostr is the fount-network fallback transport (`link` level −∞, discovery `priority` 100). This document covers the **relay pool**, NIP-66 discovery, health scoring, advert relay-field signing, and handshake routing. Top-level surface: [signaling.md](signaling.md) · [transports.md](transports.md) · [mesh.md](mesh.md).
 
 Source layout (`discovery/nostr/`):
+
 - `index.mjs` — provider (presence / signal / advert subscriptions)
 - `relays.mjs` — pool, health, NIP-66 discovery, normalization, persistence
 - `selection.mjs` — handshake routing, backoff, fanout
@@ -72,6 +73,7 @@ Lower is better. `recordProbeSuccess` / `recordProbeFailure` / `recordPublishRes
 ## Handshake routing (`selection.mjs`)
 
 `handshakeTargets(nodeHash, attempt)`:
+
 - **Round 0**: peer-claimed `listenRelays` top 4 by composite score (own health + peer rtt); else local `workingRelays` top 4; else pinned top 4.
 - **Round ≥1**: backoff `min(2000 · 2^(attempt−1), 60000)`; base on `lastGoodNostrRelays` (expanded via `expandFromHistory` ≤ 16), or weighted-random sample of `workingRelays` (weight `1/score`); round-0 core always included; fanout capped at `MAX_ROUTING_FANOUT` (64).
 - Retries ≤ `MAX_ROUTING_ATTEMPTS` (4).

package/docs/signaling.md

@@ -14,9 +14,20 @@ Internal WebRTC (`needsOfferAnswer`) glare and handshake. Shells use the fount-n
 
 Frames: `hello` then `auth`. On simultaneous dial, peer `auth` can arrive before peer `hello` — buffer it (`pendingAuth` in `link/pipe.mjs`); never drop.
 
-## Windows / `trickleIceOff`
+## ICE candidate gathering and the local-hostname ladder
 
-When set: send final offer/answer after ICE gathering, dedupe remote signals, queue remote ICE until both descriptions are ready.
+There is no `trickleIceOff` switch: candidates travel inside the description, because a peer must already hold the remote description before it accepts candidates. Every link therefore gathers locally first and then sends one offer/answer.
+
+`.local` (mDNS) host candidates are usually unresolvable for the peer, so the default policy drops them. When that leaves the local candidate set **empty**, the link cannot work no matter what the peer supports, so the initiator escalates to the next, more permissive policy and rebuilds the peer connection on that rung (`ICE_LOCAL_HOSTNAME_LADDER` in `node/signaling_config.mjs`; `iceLocalHostnameLadder` derives the rungs from the configured start):
+
+1. `drop` — solve the mDNS problem by not offering the candidate.
+2. `none` — offer everything and let the peer decide.
+
+This decision is driven purely by the observed candidate set, never by the platform, so any backend on any host follows the same path. `rewrite-loopback` is not part of the ladder (rewriting a candidate to `127.0.0.1` is only useful same-machine); it stays available as an explicit start and, when set, is used alone.
+
+Each rung is a **fresh link attempt** — new peer connection, new offer, new DTLS fingerprint — not a renegotiation of a live connection, so `pipe` fingerprint-binding semantics are unchanged. The offer carries the rung number; the responder rebuilds on that same rung and echoes it in the answer and never escalates on its own, which keeps convergence bounded. The whole ladder shares the `handshakeTimeoutMs` budget.
+
+Gathering itself is bounded by `collectIceGathering` (`link/providers/webrtc.mjs`): it finishes on `iceGatheringState === 'complete'`, on a quiet candidate stream after candidates arrived (`ICE_CANDIDATE_SETTLE_MS`), or after `ICE_GATHERING_STALL_MS` when nothing was gathered at all — the last case is logged, and DTLS/data-channel timeouts decide instead of a hard 10s failure. `handshakeTimeoutMs` stays the hard stop on every path, including the quiet-window wait. Server-side polyfills (`node-datachannel`) deliver candidates only through `icecandidate` events and `localDescription.sdp` carries no candidate lines, so progress is counted from events rather than by diffing SDP.
 
 ## Runtime channels
 
@@ -25,9 +36,10 @@ When set: send final offer/answer after ICE gathering, dedupe remote signals, qu
 `channels` selects which discovery/link media are active — `nostr`, `lan`, `bt`, `webrtc`. Semantics per channel key: `false` **disables**; any other value (`undefined`, `true`, or an object) **enables** — an object is merged over that channel's default config. Channels not mentioned keep their default enabled state.
 
 Channel → components:
+
 - `nostr` (nostr discovery + nostr link) — config `relay` **replaces** the default public relay list (do not merge defaults back in).
 - `lan` (lan discovery + lan_tcp link)
 - `bt` (bt discovery + ble_gatt link)
-- `webrtc` (webrtc link data-transport fallback) — config `iceLocalHostnamePolicy` (`none` / `rewrite-loopback` / `drop`, Windows defaults `drop`) and `trickleIceOff` (send final offer/answer after ICE gathering).
+- `webrtc` (webrtc link data-transport fallback) — config `iceLocalHostnamePolicy` is the ladder's **start** (`drop` by default; `none`, or `rewrite-loopback` for same-machine debugging).
 
 To run a node on only a few channels, use the `disableAllChannels` helper: `{ channels: disableAllChannels({ nostr: { relay: [...] } }) }` enables only `nostr` (with its per-channel relay) and disables the rest; use `true` to enable a channel with its default config (`disableAllChannels({ nostr: true, webrtc: true })`).

package/docs/transports.md

@@ -45,10 +45,20 @@ LinkHandle for upper layers: `ready` / `nodeHash` / `send` / `onEnvelope` / `onD
 
 Provider optional hooks (package-internal): `ensureListening`, `localEndpoint`, `canReach`, `caps.probe: 'sync' | 'native'` (`native` = skipped on ensureRuntime fast-listen). Discovery `connectToNode` / `sendNodeSignal` may return `false` when the path is unavailable; fan-out treats that as silent skip. Per-provider throw/false in discovery and link dial fallback are silent; only total failure of the abstraction surfaces to the caller.
 
-Each registry only calls `ensureListening` on **its own** `lan_tcp` / `ble_gatt` instances (unique registry ids like `lan_tcp:ab12cd34`). Never fan out listening to other registries' sockets.
+Each registry only owns its own `lan_tcp` / `ble_gatt` instances (unique registry ids like `lan_tcp:ab12cd34`), so those are listened to per registry. Every other **registered and enabled** provider (e.g. `nostr`, `webrtc`) is listened to by the registry that can see it: `ensureRuntime` and `reloadDiscoveryRelays` call `ensureListening` on any enabled provider that has no registered stop function yet. A provider registered later — notably the fresh instance `reconcileLinkProviders()` installs when a channel is toggled off and back on — must be picked up by that pass, otherwise it silently drops every inbound `link-open` (a missing listener is logged as `p2p:nostr link-open dropped — listener not attached`).
 
 Chain `providerId` on the LinkHandle stays the short name (`lan_tcp` / `ble_gatt` / `webrtc` / `nostr`) for scheduling/stats.
 
+## Bounded waits (no unbounded dial / publish)
+
+Nothing on the dial path may wait forever:
+
+- Intra-relay publish (`discovery/nostr/session.mjs`): a request queued behind a relay that never completes its WebSocket connect is rejected with a connect-stage error after `NOSTR_QUEUED_PUBLISH_DEADLINE_MS`, and the session is reclaimed. The EVent OK timeout only starts once a socket is open, so it cannot cover the connect stage.
+- Relay fan-out (`discovery/nostr/index.mjs` `publishEvent`): resolves as soon as **one** relay accepts; the remaining publishes keep running in the background but are bounded by the above.
+- One `ensureLinkToNode` (`transport/link_registry.mjs`): bounded by `LINK_DIAL_DEADLINE_MS` (larger than the publish deadline, so a dead relay normally fails through the provider's own error path). On timeout the in-flight promise is dropped from `inflights` so later dials start a fresh attempt instead of reusing a stuck one.
+
+`kotlin/` mirrors all three; there a connect coroutine holding `sessionMutex` must also be cancellable (see [kotlin/AGENTS.md](../../kotlin/AGENTS.md)).
+
 ## Level table
 
 | id | level |
@@ -81,6 +91,10 @@ Plain TCP on the LAN. Registry schedules listen in the background after `ensureR
 
 Discovery signal + dual DataChannel; DTLS fingerprint as handshake binding; `needsOfferAnswer` glare path. Soft-fail (`null`) continues to lower-level providers. Backend: `node-datachannel` when the native addon loads, else pure-JS `node-rtc-connection` (Android/Termux skips native). See [runtime.md](runtime.md).
 
+Every link gathers local ICE candidates first and then sends one offer/answer (there is no trickle mode: a peer must already hold the remote description before it accepts candidates). `collectIceGathering` (`link/providers/webrtc.mjs`) therefore does not wait for `iceGatheringState === 'complete'` alone — server-side polyfills leave the state at `gathering` when every relay times out or when the local-hostname policy drops all host candidates. It also finishes on a quiet candidate stream (`ICE_CANDIDATE_SETTLE_MS`) and gives up after `ICE_GATHERING_STALL_MS` when nothing was gathered, so DTLS/data-channel timeouts decide instead of a hard failure. `handshakeTimeoutMs` remains the hard stop on every path. Progress is counted from `icecandidate` events, not SDP diffs, because `localDescription.sdp` carries no candidate lines on those backends.
+
+When the configured local-hostname policy drains every candidate the link cannot work at all, so the initiator escalates through `ICE_LOCAL_HOSTNAME_LADDER` (`drop` → `none`) and rebuilds the peer connection per rung; the responder follows the rung named in the offer. Nothing here is platform-specific. Details: [signaling.md](signaling.md).
+
 ### `ble_gatt` (40)
 
 GATT write/notify; binding = shared `linkId`; needs BT peer hint (`peripheralId` in discovery meta); optional noble/bleno. Per-registry instance like `lan_tcp`; `isAvailable` / `canReach` gate dial. On Win32, scan-only stacks cannot accept inbound BLE links. One BLE adapter cannot host two independent peripherals in-process — production is one node per process. Hardware probe: [runtime.md](runtime.md).

package/federation/part_query/runtime.mjs

@@ -227,7 +227,7 @@ function mergeRowsWithSources(entries, maxHits, rowKey) {
 		try { return JSON.stringify(row) }
 		catch { return `\0${rows.length}` }
 	})
-	for (const entry of entries) {
+	for (const entry of entries)
 		for (const row of entry.rows || []) {
 			const key = keyOf(row)
 			if (!seen.has(key)) {
@@ -240,7 +240,7 @@ function mergeRowsWithSources(entries, maxHits, rowKey) {
 			}
 			if (entry.sourceNodeHash) sources.get(key).add(entry.sourceNodeHash)
 		}
-	}
+
 	return { rows, sources }
 }
 
@@ -325,10 +325,10 @@ function filterRowsBySource(rows, sources, rowKey, isSourceBlocked) {
 	return rows.filter(row => {
 		let key
 		if (rowKey) key = rowKey(row)
-		else {
+		else
 			try { key = JSON.stringify(row) }
 			catch { return true }
-		}
+
 		const set = sources.get(key)
 		if (!set || set.size === 0) return true
 		for (const source of set) if (!isSourceBlocked(source)) return true

package/index.mjs

@@ -37,6 +37,7 @@ import {
 	unlockReputationMax,
 } from './node/reputation_sync.mjs'
 import { getRoutingProfile, setRoutingProfile } from './node/routing_profile.mjs'
+import { attachNetworkVerification, createNetworkVerificationService, getNetworkVerificationService, proveNetworkVerification } from './node/verification.mjs'
 import { createGroupLinkSet } from './transport/group_link_set.mjs'
 import {
 	configureLinkRegistry,
@@ -62,12 +63,14 @@ import {
  * 包门面：节点、infra、mesh/registry、信誉同步、node-scope 等公开导出。
  */
 export {
+	attachNetworkVerification,
 	attachReputationSyncWire,
 	attachNodeScopeDefaultFeatures,
 	closeNode,
 	configureLinkRegistry,
 	configureNodeStorage,
 	createGroupLinkSet,
+	createNetworkVerificationService,
 	createScopedLinkRoom,
 	ensureChannelAvailable,
 	ensureLinkToNode,
@@ -76,6 +79,7 @@ export {
 	ensureOverlayRouter,
 	ensureUserRoom,
 	getLinkRegistry,
+	getNetworkVerificationService,
 	getNodeDir,
 	getNodeHash,
 	getNodePopulationEstimate,
@@ -93,6 +97,7 @@ export {
 	loadReputation,
 	lockReputationMax,
 	onPeerHealth,
+	proveNetworkVerification,
 	pullReputationFromNode,
 	registerDiscoveryProvider,
 	registerLinkProvider,

package/link/providers/ble_gatt.mjs

@@ -63,7 +63,7 @@ async function openGattPipe(options) {
 }
 
 /**
- * Central dial。
+ * central 角色主动拨号：按 peer hint 扫描外围设备并建立 GATT 链路。
  * @param {object} options dial 选项
  * @returns {Promise<import('./index.mjs').LinkHandle>} 已就绪的 link
  */
@@ -187,7 +187,7 @@ export function createBleGattLinkProvider() {
 			uuid: BLE_DATA_CHAR_UUID,
 			properties: ['write', 'writeWithoutResponse', 'notify'],
 			/**
-			 * stoprocent/bleno onWriteRequest(connection, data, offset, withoutResponse, callback)
+			 * peripheral 角色的写入回调（stoprocent/bleno onWriteRequest 签名）。
 			 * @param {*} _connection 连接句柄
 			 * @param {Buffer} data 写入
 			 * @param {number} _offset 偏移

package/link/providers/index.mjs

@@ -9,7 +9,8 @@
  *   onDown: (callback: (reason: string) => void) => () => void,
  *   close: (reason?: string) => Promise<void>,
  *   stats: () => object,
- * }} LinkHandle */
+ * }} LinkHandle
+ */
 
 /**
  * @typedef {{

package/link/providers/nostr/index.mjs

@@ -5,6 +5,7 @@ import { base64ToBytes, bytesToBase64 } from '../../../core/bytes_codec.mjs'
 import { isHex64 } from '../../../core/hexIds.mjs'
 import { getDiscoveryProvider, sendNodeSignalPacket } from '../../../discovery/index.mjs'
 import { NOSTR_SIGNAL_KIND, resolveNostrRelayUrls } from '../../../discovery/nostr/index.mjs'
+import { nodeDebug, shortHash } from '../../../node/log.mjs'
 import { ms } from '../../../utils/duration.mjs'
 import { createLruMap } from '../../../utils/lru.mjs'
 import { FRAME_HEADER_BYTES, maxFrameChunkBytesForPayload } from '../../frame.mjs'
@@ -12,9 +13,11 @@ import { asLinkHandle } from '../../pipe.mjs'
 import { LINK_LEVEL_NOSTR } from '../levels.mjs'
 import { createLinkIdBoundPipe } from '../link_id_pipe.mjs'
 
-/** 单包 payload（UTF-8 / base64）上限，避免撞 relay content 限制。
- *  默认兜底取 2026-08 本机对默认公共 relay 的 NIP-11 `max_message_length` 非零最小值（131072 = nostr.mom）。
- *  有 relay 信息时用实测非零最小值覆盖（见 refreshPayloadCap），无 relay / 未探测到时用此默认。 */
+/**
+ * 单包 payload（UTF-8 / base64）上限，避免撞 relay content 限制。
+ * 默认兜底取 2026-08 本机对默认公共 relay 的 NIP-11 `max_message_length` 非零最小值（131072 = nostr.mom）。
+ * 有 relay 信息时用实测非零最小值覆盖（见 refreshPayloadCap），无 relay / 未探测到时用此默认。
+ */
 export const MAX_LINK_PAYLOAD_CHARS = 131072
 
 /** relay info（NIP-11）单次探测超时。 */
@@ -52,8 +55,10 @@ export function estimateEventMessageBytes(packet) {
 	}])).length
 }
 
-/** relay cap 低于此字符数视为无法承载最小正 chunk（帧头 + 1 字节 chunk 的完整 EVENT 封装），从统一上限中剔除。
- *  这类 relay 即便能传也无法携带有效载荷（maxFrameChunkBytesForPayload 得 0），参与取最小值只会无谓拖低/毒化整条链路。 */
+/**
+ * relay cap 低于此字符数视为无法承载最小正 chunk（帧头 + 1 字节 chunk 的完整 EVENT 封装），从统一上限中剔除。
+ * 这类 relay 即便能传也无法携带有效载荷（maxFrameChunkBytesForPayload 得 0），参与取最小值只会无谓拖低/毒化整条链路。
+ */
 export const MIN_USABLE_RELAY_CAP_CHARS = estimateEventMessageBytes({
 	type: 'link',
 	op: 'b',
@@ -323,7 +328,15 @@ export function createNostrLinkProvider(options = {}) {
 		const op = String(packet.op || '')
 		if (op === 'open') {
 			if (sessions.has(linkId)) return
-			if (!onInbound || !localIdentity) return
+			if (!onInbound || !localIdentity) {
+				// 监听未挂上（例如通道关掉再打开后 registry 没重新 ensureListening）时入站包会被丢弃；
+				// 静默丢弃曾让「对端明明在线却始终握手超时」无法诊断（见 fount-p2p#38）。
+				nodeDebug('p2p:nostr link-open dropped — listener not attached', {
+					peer: shortHash(from),
+					linkId: shortHash(linkId),
+				})
+				return
+			}
 			await refreshPayloadCap(resolveRelayUrls())
 			if (sessions.has(linkId)) return
 			const pipe = openPipe({