@marktrue/dsh-mobile-remote 3.2.1-rc.1 → 3.2.2-alpha.1

package/lib/index.js

@@ -277,6 +277,30 @@ export const Config = z.object({
 	approvalMode: z
 		.union([z.const("both"), z.const("mobile"), z.const("desktop")])
 		.default("both"),
+	/**
+	 * 手机离线时仍由手机侧接管审批/问询的等待上限（毫秒；0 = 关闭，恢复 v3.2.0 的
+	 * "离线一律交桌面 GUI"行为）。默认 5 分钟。
+	 *
+	 * 为什么需要（v3.2.x 跑在 DSH 0.2.x 上的实测缺陷）：$events 通道不可用时 approvalMode
+	 * 降级为 mobile 语义，而手机离线时 answerer 直接 next() 把审批让给桌面；人不在电脑前
+	 * 时桌面无人应答，内核 approval promise 永久悬挂——会话一直 running、手机端既无卡片
+	 * 也无待办、连"停止"都因网关签名变化而 400。开启本项后离线也建条目并写回放帧，打开
+	 * App 时卡片会被补发；超过上限则 fail-close 成 unavailable，让内核继续走。
+	 */
+	offlineHoldMs: z.number().min(0).max(3_600_000).default(300_000),
+	/**
+	 * 手机离线时是否**同时**让桌面 GUI 弹卡（默认 true）。
+	 * 关掉后回到"离线即由手机独占、桌面不弹"；需要在家用桌面审批时保持默认。
+	 */
+	offlineAlsoDesktop: z.boolean().default(true),
+	/**
+	 * 审批/问询推送的宽限期（毫秒，0 = 立即推送）。默认 5000。
+	 *
+	 * 审批/问询到达时先挂起这么久再决定要不要推送：期间条目若被结算（桌面先答、另一端
+	 * 已处理、自动批准），整条通知都不再发出。否则"人就坐在电脑前秒点一下"，手机照样
+	 * 会响一次 —— 纯噪音。与 zen-remote 的同名策略一致（它的默认值也是 5 秒）。
+	 */
+	pushApprovalGraceMs: z.number().min(0).max(60_000).default(5_000),
 });
 
 /**
@@ -1300,6 +1324,36 @@ export const capabilityState = (service, predicate) => {
 	}
 };
 
+/**
+ * 二维码地址排序（issue #49）。
+ *
+ * 默认保持「局域网私有地址优先」：在家扫码必须给手机可达的局域网地址，组网地址
+ * （Tailscale CGNAT 100.64/10）排在其后，避免「桌面有 Tailscale、手机没登录 → 扫到黑洞」。
+ *
+ * 例外：**当前没有任何局域网私有地址**时，把 Tailscale 提到最前。这类机器（校园网 / 热点 /
+ * 只剩虚拟网卡）若不这样排，唯一可用的组网地址会被「其他」段压到后面，二维码首选变成不可达地址。
+ * 两种情形都按「手机能否直接到达」取最优，而不是按网卡枚举顺序。
+ *
+ * 排序：0 = 10./192.168.x；1 = 172.16-31；2 = 100.64/10；3 = 其他。
+ */
+export const orderQrAddresses = (ips) => {
+	const rankOf = (ip) => {
+		const o = String(ip).split(".").map(Number);
+		if (o.length !== 4 || o.some((n) => !Number.isFinite(n))) return 3;
+		if (o[0] === 10 || (o[0] === 192 && o[1] === 168)) return 0;
+		if (o[0] === 172 && o[1] >= 16 && o[1] <= 31) return 1;
+		if (o[0] === 100 && o[1] >= 64 && o[1] <= 127) return 2;
+		return 3;
+	};
+	const hasLanPrivate = ips.some((ip) => {
+		const rank = rankOf(ip);
+		return rank === 0 || rank === 1;
+	});
+	// 没有局域网私有地址时，把 CGNAT 从 2 提到 0（其余保持原相对次序）
+	const adjusted = (ip) => (rankOf(ip) === 2 && !hasLanPrivate ? 0 : rankOf(ip));
+	return [...ips].sort((a, b) => adjusted(a) - adjusted(b));
+};
+
 /** 从 ContentBlock[] 提取纯文本（默认过滤 tool-call；user 消息的 image 保留占位）。 */
 export function blocksToText(blocks, { includeToolCalls = false, imagePlaceholder = true } = {}) {
 	let out = "";
@@ -3329,6 +3383,23 @@ export function apply(ctx, config, runtime = {}) {
 		});
 		return true;
 	};
+	/**
+	 * 带宽限的待答通知：宽限期内条目已被结算就整条跳过。
+	 * @param isPending 该条目是否仍挂着（按 phoneId 查 pending 表）
+	 * @param fire 真正发通知的动作（notifyAsk / notifyQuestion）
+	 */
+	const notifyAskDeferred = (sessionId, isPending, fire) => {
+		if (APPROVAL_PUSH_GRACE_MS <= 0) return fire();
+		const timer = setTimeout(() => {
+			if (typeof isPending === "function" && !isPending()) {
+				ctx.logger.info?.("mobile-remote: 待答已在 " + APPROVAL_PUSH_GRACE_MS + "ms 内结算，跳过通知（" + sessionId + "）");
+				return;
+			}
+			fire();
+		}, APPROVAL_PUSH_GRACE_MS);
+		timer.unref?.();
+		return true;
+	};
 	const pendingEpochs = new Map(); // sessionId -> 自增序号（review M1：取消/重 arm 后旧回调失效）
 	const bumpEpoch = (sessionId) => {
 		pendingEpochs.set(sessionId, (pendingEpochs.get(sessionId) ?? 0) + 1);
@@ -3472,25 +3543,10 @@ export function apply(ctx, config, runtime = {}) {
 				return true;
 			})
 			.map(({ iface }) => iface.address);
-	/** 地址排序（二维码首选/自动收集顺序）：
-	 *  0 = 家庭局域网常见段（192.168.x / 10.x）——二维码首选，保证在家扫码即连
-	 *  1 = 组网常见段（172.16-31，蒲公英/ZeroTier 等虚拟网）
-	 *  2 = Tailscale CGNAT（100.64/10）
-	 *  3 = 其他。
-	 *  原理：在家扫码时必须给手机可达的局域网地址；组网地址靠连接后自动收集，
-	 *  避免"扫到组网 IP 而手机组网未开 → 黑洞"的连环故障。 */
-	const privateFirst = (ips) =>
-		[...ips].sort((a, b) => {
-			const rank = (ip) => {
-				const o = ip.split(".").map(Number);
-				if (o.length !== 4) return 3;
-				if (o[0] === 10 || (o[0] === 192 && o[1] === 168)) return 0;
-				if (o[0] === 172 && o[1] >= 16 && o[1] <= 31) return 1;
-				if (o[0] === 100 && o[1] >= 64 && o[1] <= 127) return 2;
-				return 3;
-			};
-			return rank(a) - rank(b);
-		});
+	/** 地址排序（二维码首选/自动收集顺序）见 `orderQrAddresses`（issue #49）：
+	 *  默认局域网私有地址优先；只有当机器上没有任何局域网私有地址时，才把
+	 *  Tailscale CGNAT 提到最前，避免二维码首选到不可达地址。 */
+	const privateFirst = (ips) => orderQrAddresses(ips);
 	/** Host 校验白名单（与 dsh /api 信任围栏同思路，阻断 DNS 重绑定）。
 	 *  = 回环（含 IPv6 ::1）+ 本机全部 internal IPv4（含 Tailscale/ZeroTier/WireGuard 虚拟网段）+ 显式配置的 `trustedHosts`（内网穿透中转）。 */
 	const trustedHosts = () => new Set([
@@ -4951,45 +5007,46 @@ export function apply(ctx, config, runtime = {}) {
 	/** v3.1.2：session/control（baseline）中取某会话的投影值（modelSelection/imageLimits 等）。 */
 	const projectionOf = (control, sessionId) =>
 		control?.type === "baseline" ? control.value?.projections?.[sessionId]?.values : undefined;
-	// ── 进程内 Peer（issue #34 / DSH 0.2.1-rc.2）──
-	// 网关不再为缺失的 peer 兜底，凡是走 `typertGateway` 的进程内调用都必须显式带上。
-	// 必须是**插件级单例**：`$events` 开流与其 `$events/result` 结算由宿主按 Peer 身份匹配
-	// （`dispatchRpc` 校验 `client.peer !== peer`），每次新建会在结算处被拒。
-	// 0.2.0 及更早没有 `connection.createPeer` → 保持 undefined（网关自带 operator Peer 兜底）。
-	// 惰性创建：`connection` 可能晚于插件挂载（实测宿主 0.2.1 首次取到 undefined），
-	// 首次取不到就留给调用方的既有重试/重连，下一次再建。
-	let inProcessPeer;
-	let peerFailureLogged = false;
-	const hostPeer = () => {
-		if (inProcessPeer) {
-			// 已缓存的 Peer 若 signal 已 abort，说明持有它的作用域已销毁（插件卸载，或宿主
-			// 未来把 createPeer 纳入 connection 作用域后 connection 重启）——宿主随后会以
-			// gateway/peer-disposed 拒绝一切调用。发现即重建，避免 `$events` 重连与 RPC 在
-			// **永久失败**里循环且无从恢复。（0.2.1 实测：Peer 随**读取 `ctx.connection` 的
-			// Context** 释放，而非 connection 提供者；本守卫是纵深防御。）
-			if (inProcessPeer.signal?.aborted !== true) return inProcessPeer;
-			inProcessPeer = undefined;
-		}
+	/**
+	 * 0.2.x（实测 0.2.1-rc.2）把 typertGateway 入口从"对象选项"改成位置参数：
+	 *   invokeRpc(endpoint, payload, signal, peer)
+	 *   dispatchRpc(endpoint, payload, signal, peer)
+	 *   openWireStream(endpoint, payload, uplink, peer, signal, control, uplinkWindow)
+	 * 并且 0.2.1 起每次调用都要带一个 **活着的** Peer 身份（内部读 `peer.signal` / `peer.principal`）：
+	 * 网关注册的进程内入口是 `connection.createPeer({ principal, interactions })`。
+	 * 0.2.0 仍由网关 `operatorPeer` 兜底，0.1.x 是两参形态，两代都不消费本插件持有的 Peer。
+	 */
+	let cachedOwnerPeer = null;
+	/**
+	 * 取本次调用使用的 Peer（**插件级单例**）。0.2.1-alpha.3 起网关不再有隐式 operator 兜底，
+	 * 而 $events/result 必须由**打开 $events 的同一个 Peer** 应答（宿主按对象身份匹配），
+	 * 所以这里按"存活"缓存，不能每次新建。没有 createPeer 的宿主（0.2.0 及更早）返回
+	 * undefined，交给网关自己的兜底——**不伪造 Peer**：身份不匹配会让结算被静默拒绝。
+	 */
+	const gatewayPeer = () => {
 		let connection;
 		try {
 			connection = ctx.get("connection");
-			inProcessPeer = createInProcessPeer(connection) ?? undefined;
-		} catch (err) {
-			inProcessPeer = undefined;
-			if (!peerFailureLogged) {
-				peerFailureLogged = true;
-				ctx.logger.warn?.(`mobile-remote: 进程内 Peer 创建失败（${err?.message ?? err}）——0.2.1+ 的网关调用会失败；诊断 gateway.eventsPeer 可归因`);
-			}
+		} catch {
+			connection = void 0;
 		}
-		if (inProcessPeer === undefined && typeof connection?.createPeer === "function" && !peerFailureLogged) {
-			peerFailureLogged = true;
-			ctx.logger.warn?.("mobile-remote: connection.createPeer 未返回 Peer——RPC 与 $events 双端审批会失败；诊断 gateway.eventsPeer 可归因");
+		if (typeof connection?.createPeer !== "function") return undefined;
+		const live = cachedOwnerPeer !== null
+			&& !(cachedOwnerPeer.signal instanceof AbortSignal && cachedOwnerPeer.signal.aborted);
+		if (live) return cachedOwnerPeer;
+		try {
+			cachedOwnerPeer = connection.createPeer({ principal: { kind: "owner" }, interactions: "answer" });
+			return cachedOwnerPeer;
+		} catch (err) {
+			cachedOwnerPeer = null;
+			ctx.logger.warn?.(`mobile-remote: connection.createPeer 失败（${err?.message ?? err}）——0.2.1+ 的网关调用会失败；诊断 gateway.eventsPeer 可归因`);
+			return undefined;
 		}
-		return inProcessPeer;
 	};
+	// 卸载时释放 Peer scope，避免随重连/重载累积
 	ctx.effect(() => () => {
-		const peer = inProcessPeer;
-		inProcessPeer = undefined;
+		const peer = cachedOwnerPeer;
+		cachedOwnerPeer = null;
 		try {
 			Promise.resolve(peer?.dispose?.()).catch(() => {});
 		} catch { /* 卸载期忽略 */ }
@@ -5006,19 +5063,25 @@ export function apply(ctx, config, runtime = {}) {
 			gateway = void 0;
 		}
 		if (gateway && typeof gateway.invokeRpc === "function") {
+			// 0.2.x 位置参数形态形参 ≥3；0.1.x 是 (endpoint, options) 两参
+			const modernGateway = gateway.invokeRpc.length >= 3;
+			const peer = modernGateway ? gatewayPeer() : void 0;
 			const endpoint = RPC_ENDPOINT_RENAMES[method] ?? method.replace(".", "/");
 			const adapted = RPC_PAYLOAD_ADAPTER[method]?.(payload) ?? { request: payload };
 			if (RPC_STREAM_METHODS.has(method)) {
 				// 基线流（session/control 等）：首帧即基线快照，取完即断
 				const [namespace, name] = endpoint.split("/");
 				const abort = new AbortController();
-				const stream = await gateway.stream({ namespace, method: name, args: adapted, signal: abort.signal, peer: hostPeer() });
+				const request = { namespace, method: name, args: adapted, signal: abort.signal };
+				const stream = await gateway.stream(modernGateway ? { ...request, peer } : request);
 				const iter = stream[Symbol.asyncIterator]();
 				const first = await iter.next();
 				abort.abort();
 				return first?.value;
 			}
-			const full = await gateway.invokeRpc(endpoint, { args: adapted }, undefined, hostPeer());
+			const full = modernGateway
+				? await gateway.invokeRpc(endpoint, { args: adapted }, peer?.signal, peer)
+				: await gateway.invokeRpc(endpoint, { args: adapted });
 			if (full?.ok === true) return full.value;
 			const e = new Error(full?.error?.message ?? `${method} failed`);
 			e.status = 400;
@@ -7541,7 +7604,14 @@ export function apply(ctx, config, runtime = {}) {
 				if (!gatewaySvc) return { state: "missing" };
 				if (!wireStreamTakesControl(gatewaySvc)) return { state: "ok" };
 				if (peerSource === "operatorPeer") return { state: "ok" };
-				return hostPeer() ? { state: "ok" } : { state: "drift", reason: "gateway-peer-source-missing" };
+				if (peerSource === "createPeer") {
+					// 必须真的造出来才算 ok：createPeer 抛错时网关调用同样必失败
+					const peer = gatewayPeer();
+					return peer && peer === cachedOwnerPeer
+						? { state: "ok" }
+						: { state: "drift", reason: "gateway-peer-source-missing" };
+				}
+				return { state: "drift", reason: "gateway-peer-source-missing" };
 			})();
 			// issue #30 评审 WARNING 3：`settings.read` **不能只看方法是否存在**。严格读取器已经能识别
 			// "get()/describe() 抛错、describe 返回非数组、已认识命名空间的描述符缺 value"，真实读取会
@@ -7897,14 +7967,16 @@ export function apply(ctx, config, runtime = {}) {
 			const sessions = ctx.get("sessions");
 			const subagentsSvc = ctx.get("subagents");
 			const agent = agents?.get(parentSessionId);
-			// issue #20：与 /sessions 同一条全量枚举路径，持久化回退也接入请求取消。
+			// issue #20：与 /sessions 同一条全量枚举路径，宿主目录与持久化回退都接入请求取消。
 			const signal = requestAbort(res);
 			const parent = sessions?.get?.(parentSessionId);
 			const hasCatalog = typeof subagentsSvc?.listChildren === "function";
-			// 目录来源按优先级取，必须同时保留 host catalog 的已释放条目与休眠父会话回退：
-			//   ① host subagents.listChildren：两代都有，包含已释放子代理和 mode/label 元数据；
-			//   ② listPersistedSubagents：宿主目录不可用时，支持父会话休眠/归档及信号取消；
-			//   ③ live sessions registry：仅作不完整兜底，并显式标记 catalogDegraded。
+			// 目录来源按优先级取——**两边能力都要保留**（issue #14/#17/#21）：
+			//   ① 宿主持久目录 `subagents.listChildren`：包含已释放子代理和 mode/label 元数据，
+			//      不要求父会话有活跃 Agent；
+			//   ② 持久化枚举 `listPersistedSubagents`：目录不可用时保留休眠/归档父会话能力；
+			//   ③ 会话注册表派生：不完整兜底，必须标注 catalogDegraded。
+			// 状态另取自活 agent（AgentStatus = idle | running）；目录条目本身不带状态。
 			let catalogRows = null;
 			let catalogDegraded = false;
 			if (hasCatalog) {
@@ -7918,17 +7990,19 @@ export function apply(ctx, config, runtime = {}) {
 				}
 			}
 			if (catalogRows === null) {
+				// 取消在途请求时不再启动持久化枚举，也不向已关闭的 socket 写响应。
 				if (signal.aborted) return;
 				const persisted = await listPersistedSubagents(parentSessionId, signal);
 				if (signal.aborted) return;
+				// issue #20 第 2 步：枚举预算耗尽时返回 { timedOut: true }；必须与 null 分开，
+				// 否则超时会被误报为 404 session-not-found。
 				if (persisted?.timedOut) return error(res, 504, "subagents-timeout");
 				if (persisted === null) {
 					// 持久层不可读（宿主无 sessionQuery）→ 留给 ③ 兜底
 				} else if (!persisted.parentExists) {
-					return error(res, 404, "session-not-found"); // 会话确实不存在
+					return error(res, 404, "session-not-found"); // 会话确实不存在（与 develop 语义一致）
 				} else {
-					// 刻意**不取**其 `status`：那条路径写死 "inactive"，会盖掉活注册表的真实状态；
-					// 标题由 ② 带出（title），在下方映射里优先于继承来的父标题。
+					// 刻意**不取**其 `status`：那条路径写死 "inactive"，会盖掉注册表的真实状态
 					catalogRows = persisted.entries.map((entry) => ({
 						id: entry.id,
 						title: entry.title,
@@ -7945,6 +8019,7 @@ export function apply(ctx, config, runtime = {}) {
 				catalogDegraded = true;
 			}
 			if (catalogRows === null) return error(res, 404, "session-not-found");
+
 			// 排序与 issue #17 对齐：createdAt 降序（最新派生在最上），等值按 id 升序。
 			const rows = catalogRows.map((row) => {
 				const id = typeof row?.id === "string" && row.id !== "" ? row.id : "";
@@ -7957,6 +8032,7 @@ export function apply(ctx, config, runtime = {}) {
 				// 已完成轮次的事件前缀（含父的 `session/title`），而 sessionTitleOf 从整个快照反查
 				// 标题、不区分继承事件与子代理自身事件——直接用它会让多个不同委派标签的 fork
 				// 全部显示父标题，丢掉任务辨识信息。
+				// 标题优先级：catalog 的 label → ② 带来的 title → 子会话自身标题 → 短码
 				const label = typeof row?.label === "string" && row.label !== "" ? row.label : undefined;
 				const rowTitle = typeof row?.title === "string" && row.title !== "" ? row.title : undefined;
 				const liveTitle = sessionTitleOf(session);
@@ -7964,8 +8040,8 @@ export function apply(ctx, config, runtime = {}) {
 			}).filter((row) => row.id !== "");
 			// issue #30 评审 WARNING 1：目录条目的 `label` 可省略，而**已释放**的子代理不在 live
 			// 注册表里（拿不到会话快照标题）。三个来源都拿不到时必须按需**补读持久标题**，
-			// 否则会退化成短 ID——而基线在父会话不活跃时一直走持久枚举、是能拿到标题的，属新回归。
-			// 只对需要的条目批量读一次；复用 /sessions 的 revision cache、取消与标题预算。
+			// 否则会退化成短 ID——基线在父会话不活跃时也能取得标题，不能丢掉该能力。
+			// 只补读缺少 label/目录标题/live 标题的条目；复用 /sessions 的 revision cache、取消和预算。
 			const needPersistedTitle = rows.filter((row) => !row.label && !row.rowTitle && !row.liveTitle).map((row) => row.id);
 			const titleBudgetStartedAt = performance.now();
 			const persistedTitleMap = needPersistedTitle.length > 0
@@ -7975,8 +8051,8 @@ export function apply(ctx, config, runtime = {}) {
 			const entries = rows
 				.map((row) => ({
 					id: row.id,
-					// issue #30 评审 WARNING 2：目录的 `mode: "unknown"` 是宿主明确判定的**不受支持
-					// 的历史条目**（宿主 `listDescendants` 映射为 diagnostic/unsupported），不能伪装成
+					// issue #30 评审 WARNING 2：目录 `mode: "unknown"` 是宿主明确判定的**不受支持
+					// 条目**（宿主 `listDescendants` 映射为 diagnostic/unsupported），不能伪装成
 					// 普通闲置子代理——否则消费者无法区分"不受支持"与"正常闲置"，等于删掉 RPC 时
 					// 顺带静默删掉既有诊断语义（docs/03-api 承诺 `status` 可为 diagnostic reason）。
 					kind: row.mode === "unknown" ? "diagnostic" : "child",
@@ -7995,6 +8071,7 @@ export function apply(ctx, config, runtime = {}) {
 					if (ta !== tb) return tb - ta;
 					return String(a.id).localeCompare(String(b.id));
 				});
+			// issue #20：客户端在扫描期间已经走了，不再写响应。
 			if (signal.aborted) return;
 			sendJson(res, 200, {
 				ok: true,
@@ -8219,6 +8296,12 @@ export function apply(ctx, config, runtime = {}) {
 	const approvalMode = config.approvalMode ?? "both";
 	/** 手机待办超时 fail-close（沿用 v3.1.2 的 120s；超时前另一端先答则本端直接收卡）。 */
 	const PENDING_TIMEOUT_MS = 120_000;
+	/** 手机离线时仍接管审批/问询的等待上限（修复：离线交桌面导致内核悬挂）。 */
+	const OFFLINE_HOLD_MS = Math.max(0, Number(config.offlineHoldMs ?? 300_000) || 0);
+	/** 审批/问询推送的宽限期（0 = 立即推）。 */
+	const APPROVAL_PUSH_GRACE_MS = Math.max(0, Number(config.pushApprovalGraceMs ?? 5_000) || 0);
+	/** 手机离线时是否同时放行桌面 GUI（双端呈现，先答者生效）。 */
+	const offlineAlsoDesktop = config.offlineAlsoDesktop !== false;
 	const pendingApprovals = new Map(); // phoneApprovalId -> { phoneId, sessionId, rpcId, timer, settle(outcome) }
 	const pendingQuestions = new Map(); // phoneQuestionId -> { phoneId, sessionId, rpcId, timer, settle(value) }
 	/**
@@ -8239,7 +8322,7 @@ export function apply(ctx, config, runtime = {}) {
 		for (const key of askReplayKeys(prefix, entry)) pendingFrames.delete(key);
 	};
 	/** $events 进程内客户端就绪态（both 双端呈现的传输前提；事件按发生时刻实时判定）。 */
-	const eventsState = { ready: false, clientId: "" };
+	const eventsState = { ready: false, clientId: "", peer: null };
 	let eventsAbort = null; // AbortController：插件卸载时断开 $events 流
 	const eventsCapable = () => eventsState.ready && eventsAbort !== null && !eventsAbort.signal.aborted;
 	/**
@@ -8261,9 +8344,10 @@ export function apply(ctx, config, runtime = {}) {
 		try {
 			const gateway = ctx.get("typertGateway");
 			if (!gateway || typeof gateway.dispatchRpc !== "function" || !eventsState.clientId) return false;
-			const full = await gateway.dispatchRpc("$events/result", {
-				args: { clientId: eventsState.clientId, eventId, outcome: { kind: "result", value } },
-			}, undefined, hostPeer());
+			const args = { clientId: eventsState.clientId, eventId, outcome: { kind: "result", value } };
+			const full = gateway.dispatchRpc.length >= 3
+				? await gateway.dispatchRpc("$events/result", { args }, void 0, eventsState.peer)
+				: await gateway.dispatchRpc("$events/result", { args });
 			if (full?.ok !== true) {
 				ctx.logger.warn?.(`mobile-remote: $events/result 结算失败（${eventId} → ${full?.error?.code ?? "unknown"}）`);
 				return false;
@@ -8292,9 +8376,10 @@ export function apply(ctx, config, runtime = {}) {
 		try {
 			const gateway = ctx.get("typertGateway");
 			if (!gateway || typeof gateway.dispatchRpc !== "function" || !eventsState.clientId) return false;
-			const full = await gateway.dispatchRpc("$events/result", {
-				args: { clientId: eventsState.clientId, eventId, outcome: { kind: "rejected", error: { name, message, code } } },
-			}, undefined, hostPeer());
+			const args = { clientId: eventsState.clientId, eventId, outcome: { kind: "rejected", error: { name, message, code } } };
+			const full = gateway.dispatchRpc.length >= 3
+				? await gateway.dispatchRpc("$events/result", { args }, void 0, eventsState.peer)
+				: await gateway.dispatchRpc("$events/result", { args });
 			if (full?.ok !== true) {
 				ctx.logger.warn?.(`mobile-remote: $events/result 拒绝回执失败（${eventId} → ${full?.error?.code ?? "unknown"}）`);
 				return false;
@@ -8340,7 +8425,7 @@ export function apply(ctx, config, runtime = {}) {
 		return true;
 	};
 	const armTimeout = (entry, onFire) => {
-		const timer = setTimeout(onFire, PENDING_TIMEOUT_MS);
+		const timer = setTimeout(onFire, entry.holdMs ?? PENDING_TIMEOUT_MS);
 		timer.unref?.();
 		entry.timer = timer;
 	};
@@ -8374,56 +8459,64 @@ export function apply(ctx, config, runtime = {}) {
 		const phoneKey = `${sessionId}:${typeof req?.callId === "string" && req.callId !== ""
 			? req.callId
 			: Date.now().toString(36)}`;
-		ctx.logger.info?.(`mobile-remote: approval/request 手机接管（${sessionId} tool=${req?.toolName}）`);
-		return new Promise((resolve) => {
-			const entry = { phoneId: phoneKey, sessionId, rpcId: phoneKey, timer: null, settle: resolve };
-			pendingApprovals.set(phoneKey, entry);
-			armTimeout(entry, () => {
-				// 手机无响应：fail-close（与内核 unavailable 语义一致），不悬挂工具调用
-				ctx.logger.warn?.(`mobile-remote: approval/request 手机超时未应答 → unavailable（${phoneKey}）`);
-				finishApproval(entry, "unavailable");
-			});
-			const requested = {
-				type: "approval/requested", rpcId: entry.rpcId, sessionId, approvalId: phoneKey,
-				toolName: req?.toolName, callId: req?.callId, reason: req?.reason,
-			};
-			// v3.1.4（issue #14）：接管期间手机断线重连也能拿回卡片（与 $events 路径同一契约）
-			putAskReplay("a", entry, requested);
-			broadcast({ type: "mobile/frame", frame: requested });
-			notifyAsk(sessionId, req);
+		const phoneOnline = connections.size > 0;
+		const holdMs = phoneOnline ? PENDING_TIMEOUT_MS : OFFLINE_HOLD_MS;
+		ctx.logger.info?.(`mobile-remote: approval/request 手机接管（${sessionId} tool=${req?.toolName}${phoneOnline ? "" : `，手机离线，最多等待 ${Math.round(holdMs / 1000)}s`}）`);
+		// v3.3.0：改为先建 Promise 再建条目，便于双端竞速时由调用方拿到 entry 收卡
+		let resolveHeld;
+		const held = new Promise((resolve) => { resolveHeld = resolve; });
+		const entry = { phoneId: phoneKey, sessionId, rpcId: phoneKey, timer: null, holdMs, settle: resolveHeld };
+		pendingApprovals.set(phoneKey, entry);
+		armTimeout(entry, () => {
+			// 手机无响应：fail-close（与内核 unavailable 语义一致），不悬挂工具调用
+			ctx.logger.warn?.(`mobile-remote: approval/request 手机超时未应答 → unavailable（${phoneKey}）`);
+			finishApproval(entry, "unavailable");
 		});
+		const requested = {
+			type: "approval/requested", rpcId: entry.rpcId, sessionId, approvalId: phoneKey,
+			toolName: req?.toolName, callId: req?.callId, reason: req?.reason,
+		};
+		// v3.1.4（issue #14）：接管期间手机断线重连也能拿回卡片（与 $events 路径同一契约）
+		putAskReplay("a", entry, requested);
+		broadcast({ type: "mobile/frame", frame: requested });
+		notifyAskDeferred(sessionId, () => pendingApprovals.has(phoneKey), () => notifyAsk(sessionId, req));
+		return { held, entry };
 	};
 	const holdQuestion = (req, sessionId) => {
 		const phoneKey = `${sessionId}:${Date.now().toString(36)}`;
-		ctx.logger.info?.(`mobile-remote: user-questions/request 手机接管（${sessionId}）`);
+		const phoneOnline = connections.size > 0;
+		const holdMs = phoneOnline ? PENDING_TIMEOUT_MS : OFFLINE_HOLD_MS;
+		ctx.logger.info?.(`mobile-remote: user-questions/request 手机接管（${sessionId}${phoneOnline ? "" : `，手机离线，最多等待 ${Math.round(holdMs / 1000)}s`}）`);
 		// v3.1.5（PR #11 P0）：rpcId = phoneKey（见 holdApproval 同名说明）；
 		// 同时补 reject —— 取消/超时走 UserQuestionError 拒绝，不再 resolve(null)
 		// （null 会让内核 dsh-tool-ask-user 读 .answers 抛 TypeError）。
-		return new Promise((resolve, reject) => {
-			const entry = {
-				phoneId: phoneKey, sessionId, rpcId: phoneKey, timer: null,
-				// questions 必须随条目保存：/respond 的答案校验（validateQuestionAnswers）
-				// 要拿原始提问核对选项/单选多选，缺失会让所有应答被判非法 400
-				questions: Array.isArray(req?.questions) ? req.questions : [],
-				settle: (value) => { resolve(value); return true; },
-				reject: (reason) => { reject(reason); return true; },
-			};
-			pendingQuestions.set(phoneKey, entry);
-			armTimeout(entry, () => {
-				ctx.logger.warn?.(`mobile-remote: user-questions/request 手机超时未应答 → 取消（${phoneKey}）`);
-				finishQuestion(entry, questionCancelledError("ask_user_question timed out before the user answered"), { reject: true });
-			});
-			const requested = {
-				type: "question/requested", rpcId: entry.rpcId, sessionId, questionId: phoneKey,
-				// 内核瀑布值为顶层 questions（userQuestions.ask 传 {questions, agent, signal}，
-				// GUI 端 $on 同样读 request.questions）；v3.1.2 误用 req.request.questions
-				// → 手机端广播空问题列表（手机问询不可用的遗留根因之一，真机验证发现）
-				questions: req?.questions ?? [],
-			};
-			putAskReplay("q", entry, requested); // v3.1.4：同上，断线重连可回放
-			broadcast({ type: "mobile/frame", frame: requested });
-			notifyQuestion(sessionId);
+		let resolveHeld;
+		let rejectHeld;
+		const held = new Promise((resolve, reject) => { resolveHeld = resolve; rejectHeld = reject; });
+		const entry = {
+			phoneId: phoneKey, sessionId, rpcId: phoneKey, timer: null, holdMs,
+			// questions 必须随条目保存：/respond 的答案校验（validateQuestionAnswers）
+			// 要拿原始提问核对选项/单选多选，缺失会让所有应答被判非法 400
+			questions: Array.isArray(req?.questions) ? req.questions : [],
+			settle: (value) => { resolveHeld(value); return true; },
+			reject: (reason) => { rejectHeld(reason); return true; },
+		};
+		pendingQuestions.set(phoneKey, entry);
+		armTimeout(entry, () => {
+			ctx.logger.warn?.(`mobile-remote: user-questions/request 手机超时未应答 → 取消（${phoneKey}）`);
+			finishQuestion(entry, questionCancelledError("ask_user_question timed out before the user answered"), { reject: true });
 		});
+		const requested = {
+			type: "question/requested", rpcId: entry.rpcId, sessionId, questionId: phoneKey,
+			// 内核瀑布值为顶层 questions（userQuestions.ask 传 {questions, agent, signal}，
+			// GUI 端 $on 同样读 request.questions）；v3.1.2 误用 req.request.questions
+			// → 手机端广播空问题列表（手机问询不可用的遗留根因之一，真机验证发现）
+			questions: req?.questions ?? [],
+		};
+		putAskReplay("q", entry, requested); // v3.1.4：同上，断线重连可回放
+		broadcast({ type: "mobile/frame", frame: requested });
+		notifyAskDeferred(sessionId, () => pendingQuestions.has(phoneKey), () => notifyQuestion(sessionId));
+		return { held, entry };
 	};
 
 	// $events 事件处理：瀑布经内核转发到达网关后才投给本客户端。
@@ -8472,8 +8565,9 @@ export function apply(ctx, config, runtime = {}) {
 				armOfflineReap(entry, "a");
 			}
 			broadcast({ type: "mobile/frame", frame: requested });
-			// 推送与手机是否在线无关：App 关闭时这是**唯一**的提醒通道（issue #14 Bug1）
-			notifyAsk(sessionId, request);
+			// 推送与手机是否在线无关：App 关闭时这是**唯一**的提醒通道（issue #14 Bug1）。
+			// 宽限期：桌面先答/自动批准时不该再响一次。
+			notifyAskDeferred(sessionId, () => pendingApprovals.has(phoneKey), () => notifyAsk(sessionId, request));
 			return;
 		}
 		if (frame.event === "user-questions/request") {
@@ -8509,7 +8603,7 @@ export function apply(ctx, config, runtime = {}) {
 				armOfflineReap(entry, "q");
 			}
 			broadcast({ type: "mobile/frame", frame: requested });
-			notifyQuestion(sessionId);
+			notifyAskDeferred(sessionId, () => pendingQuestions.has(phoneKey), () => notifyQuestion(sessionId));
 			return;
 		}
 	};
@@ -8590,16 +8684,15 @@ export function apply(ctx, config, runtime = {}) {
 				let everReady = false;
 				while (!controller.signal.aborted) {
 					try {
-						// v3.1.6(issue #19)：宿主 0.2.0 在途中插入了 uplink/peer，取消信号从第 3 位移到第 5 位。
-						// 传错位不会报参数错误：信号落进 uplink、真正的 signal 为 undefined，宿主在
-						// AbortSignal.any([undefined, …]) 处抛错并被本循环吞掉 —— 现象是
-						// approvalMode=both 的 $events 通道**永远不就绪**（静默降级为 mobile 语义）。
-						// issue #34：0.2.1 起第 4 位 peer 也不再可省（网关删除 operatorPeer 兜底）——
-						// 传插件级单例 Peer，与 $events/result 结算同源；首次取不到（connection 尚未
-						// 挂载）时传 undefined，由下面的有界重试等宿主就绪。
-						const stream = wireStreamTakesControl(gateway)
-							? await gateway.openWireStream("$events", { args: {} }, undefined, hostPeer(), controller.signal)
+						// 0.2.x：openWireStream(endpoint, payload, uplink, peer, signal, control, uplinkWindow)
+						// 旧宿主只有 (endpoint, payload, signal)。uplink 必须是异步迭代器
+						// （宿主会对它调用 return()），$events 分支里只被释放、不被消费。
+						const peer = gatewayPeer();
+						const emptyUplink = (async function* emptyUplink() {})();
+						const stream = gateway.openWireStream.length >= 6
+							? await gateway.openWireStream("$events", { args: {} }, emptyUplink, peer, controller.signal, new AbortController())
 							: await gateway.openWireStream("$events", { args: {} }, controller.signal);
+						eventsState.peer = peer;
 						for await (const frame of stream) {
 							try {
 								if (frame?.type === "ready" && typeof frame.clientId === "string" && frame.clientId !== "") {
@@ -8651,23 +8744,58 @@ export function apply(ctx, config, runtime = {}) {
 		// （这正是"两端都没弹卡、请求悬挂"的根因）。prepend:true 排在内核转发监听之前——
 		// 是否抢先消费即 issue #9 的开关点：mobile（含 both 降级）手机在线即接管；
 		// both 就绪 / desktop 一律 next() 放行内核转发（桌面弹卡），手机卡由 $events 补发。
+		// 双端策略：approvalMode=both → 始终两端同显、先答生效（$events 不可用时用 hold+next 竞速复现）；
+		// mobile → 手机在线即独占；离线时按 offlineAlsoDesktop 决定是否带桌面兜底。
+		const dualRoute = (hold, next, onDownstream) => {
+			const downstream = Promise.resolve().then(() => next());
+			return Promise.race([hold, downstream]).then(
+				(winner) => {
+					// 下游抢答但结果是 `unavailable`（没有任何桌面 $events 客户端 / 转发通道超时）：
+					// **不能**当成先答——手机侧卡片已经建好，用户可能正要作答。保留条目，
+					// 等手机 /respond 或 hold 自己的 fail-close 超时给出最终结果
+					// （真机验收 issue #46 时发现）。
+					if (winner === "unavailable") return hold;
+					// 真答复（桌面先答）/ 手机先答 / 取消：按先答生效，另一端收卡
+					onDownstream();
+					return winner;
+				},
+				(err) => {
+					onDownstream();
+					throw err;
+				},
+			);
+		};
 		const offApproval = ctx.on("approval/request", (req, next) => {
-			const mobileHold = approvalMode !== "desktop" && !eventsCapable() && connections.size > 0;
-			if (mobileHold) {
-				const sessionId = req?.agent?.session?.id ?? "";
-				if (sessionId) return holdApproval(req, sessionId);
-			}
-			ctx.logger.info?.("mobile-remote: approval/request 放行内核转发（桌面 GUI 弹卡）");
-			return next();
+			const phoneOnline = connections.size > 0;
+			const mobileHold = approvalMode !== "desktop" && !eventsCapable() && (phoneOnline || OFFLINE_HOLD_MS > 0);
+			const sessionId = mobileHold ? (req?.agent?.session?.id ?? "") : "";
+			if (!mobileHold || !sessionId) {
+				ctx.logger.info?.("mobile-remote: approval/request 放行内核转发（桌面 GUI 弹卡）");
+				return next();
+			}
+			const { held, entry } = holdApproval(req, sessionId);
+			// both 的语义就是「两端同显、先答生效」。$events 不可用时用 hold + next 竞速在本地复现；
+			// mobile 保持手机独占；离线场景由 offlineAlsoDesktop 决定是否带上桌面。
+			const wantDual = approvalMode === "both" || (!phoneOnline && offlineAlsoDesktop);
+			if (!wantDual) return held;
+			ctx.logger.info?.(`mobile-remote: approval/request 双端呈现（${phoneOnline ? "手机在线" : "手机离线，桌面兜底"}），先答生效`);
+			return dualRoute(held, next, () => finishApproval(entry, "cancelled"));
 		}, { prepend: true, global: true });
 		const offQuestion = ctx.on("user-questions/request", (req, next) => {
-			const mobileHold = approvalMode !== "desktop" && !eventsCapable() && connections.size > 0;
-			if (mobileHold) {
-				const sessionId = req?.agent?.session?.id ?? "";
-				if (sessionId) return holdQuestion(req, sessionId);
-			}
-			ctx.logger.info?.("mobile-remote: user-questions/request 放行内核转发（桌面 GUI 弹卡）");
-			return next();
+			const phoneOnline = connections.size > 0;
+			const mobileHold = approvalMode !== "desktop" && !eventsCapable() && (phoneOnline || OFFLINE_HOLD_MS > 0);
+			const sessionId = mobileHold ? (req?.agent?.session?.id ?? "") : "";
+			if (!mobileHold || !sessionId) {
+				ctx.logger.info?.("mobile-remote: user-questions/request 放行内核转发（桌面 GUI 弹卡）");
+				return next();
+			}
+			const { held, entry } = holdQuestion(req, sessionId);
+			const wantDual = approvalMode === "both" || (!phoneOnline && offlineAlsoDesktop);
+			if (!wantDual) return held;
+			ctx.logger.info?.(`mobile-remote: user-questions/request 双端呈现（${phoneOnline ? "手机在线" : "手机离线，桌面兜底"}），先答生效`);
+			// 桌面先答时 held 会被 reject：挂一个空 catch，避免"未处理的 rejection"
+			held.catch(() => void 0);
+			return dualRoute(held, next, () => finishQuestion(entry, questionCancelledError("another client answered the question"), { reject: true }));
 		}, { prepend: true, global: true });
 		return () => {
 			offApproval?.();
@@ -8676,6 +8804,7 @@ export function apply(ctx, config, runtime = {}) {
 			eventsAbort = null;
 			eventsState.ready = false;
 			eventsState.clientId = "";
+			eventsState.peer = null;
 			for (const entry of pendingApprovals.values()) if (entry.timer) clearTimeout(entry.timer);
 			for (const entry of pendingQuestions.values()) if (entry.timer) clearTimeout(entry.timer);
 			pendingApprovals.clear();