@napuketto/loader 0.0.29 → 0.0.31

package/dist/host/self-host.cjs

@@ -24,9 +24,89 @@ let node_fs = require("node:fs");
 let node_path = require("node:path");
 let node_process = require("node:process");
 node_process = __toESM(node_process, 1);
+let node_child_process = require("node:child_process");
 let node_os = require("node:os");
 let zod = require("zod");
 let node_readline = require("node:readline");
+//#region src/pid-cmdline.ts
+/**
+* pid-cmdline.ts：跨进程命令行查询（instance-lock pid 复用根治，2026-09-10）。
+*
+* 背景（2026-09-08 实测事故）：锁内 pid 的持有者已死、pid 被 Windows 复用给
+* 无关进程时，process.kill(pid, 0) 探活成功 → 误判存活 → 新实例永久拒绝启动
+* （只能手动删锁恢复）。根治：探活通过后再查该 pid 当前的真实命令行，与锁内
+* cmdline 摘要比对——查不到（进程已退/查询失败）或不一致（pid 复用）均视为
+* 持有者已死，允许接管。误判方向取舍：误判「死亡」→ 双实例抢 QQ 原生锁，
+* 后启动者挂起退出（可恢复）；误判「存活」→ 永久锁死需人工干预——前者代价
+* 远低，故查询失败宁可接管。
+*
+* 平台实现：Windows 走 PowerShell Get-CimInstance Win32_Process 跨进程查询
+* （仅在启动判活时调用一次，冷启动 ~0.5-2s 可接受；wmic 在新 Win11 已移除，
+* 不可用）。Linux 走 /proc/<pid>/cmdline（\0 分隔）。其余平台（darwin 等）
+* 不支持——判活退回纯 pid 探测（旧行为）。
+*
+* 比对不要求逐字符相等：锁内摘要来自 process.execArgv/argv join，查询侧
+* 拿到的是操作系统记录的原始命令行，两者存在引号 / 大小写 / 路径分隔符差异
+* ——统一经 normalizeCmdline 规范化后比对。残余差异源（8.3 短路径、相对
+* 启动路径）极罕见，误判后果同上（可恢复），接受。
+*/
+/** 当前平台是否支持跨进程 cmdline 查询（不支持则判活退回纯 pid 探测）。 */
+const CMDLINE_PROBE_SUPPORTED = node_process.default.platform === "win32" || node_process.default.platform === "linux";
+/**
+* 查询指定 pid 的当前命令行。
+*
+* @returns 命令行原文；进程不存在 / 命令行不可得（权限、系统进程 null）/
+*          查询机制失败（超时、PowerShell 缺失）均返回 null（调用方视为持有者已死）
+*/
+function readCmdlineForPid(pid) {
+	if (node_process.default.platform === "win32") return readWindowsCmdline(pid);
+	if (node_process.default.platform === "linux") return readLinuxCmdline(pid);
+	return null;
+}
+/** Windows：PowerShell Get-CimInstance 查询（进程不存在时输出空 → null）。 */
+function readWindowsCmdline(pid) {
+	try {
+		const cmdline = (0, node_child_process.execFileSync)("powershell.exe", [
+			"-NoProfile",
+			"-NonInteractive",
+			"-ExecutionPolicy",
+			"Bypass",
+			"-Command",
+			`[Console]::OutputEncoding=[System.Text.Encoding]::UTF8;(Get-CimInstance Win32_Process -Filter 'ProcessId=${pid}').CommandLine`
+		], {
+			encoding: "utf-8",
+			timeout: 1e4,
+			windowsHide: true
+		}).trim();
+		return cmdline === "" ? null : cmdline;
+	} catch {
+		return null;
+	}
+}
+/** Linux：/proc/<pid>/cmdline（\0 分隔转空格；进程不存在抛错 → null）。 */
+function readLinuxCmdline(pid) {
+	try {
+		const cmdline = (0, node_fs.readFileSync)(`/proc/${pid}/cmdline`, "utf-8").replaceAll("\0", " ").trim();
+		return cmdline === "" ? null : cmdline;
+	} catch {
+		return null;
+	}
+}
+/**
+* 命令行规范化（比对用）：统一大小写 / 去引号 / 路径分隔符归一 / 折叠空白。
+* Windows 路径大小写不敏感，lowercase 安全。
+*/
+function normalizeCmdline(cmdline) {
+	return cmdline.toLowerCase().replaceAll("\"", "").replaceAll("\\", "/").replace(/\s+/g, " ").trim();
+}
+/**
+* 本进程命令行摘要（写锁用）：execArgv（node 选项）+ argv（脚本与参数），
+* 与操作系统记录的完整命令行结构一致（规范化后可比对）。
+*/
+function selfCmdline() {
+	return [...node_process.default.execArgv, ...node_process.default.argv].join(" ").trim();
+}
+//#endregion
 //#region src/instance-lock.ts
 /**
 * instance-lock.ts：单实例锁（2026-08-07 根治「多实例抢数据目录锁挂起」）
@@ -42,6 +122,12 @@ let node_readline = require("node:readline");
 *   - 锁存在但 PID 已死 → 崩溃残留，自动清理（rm + 重新获取）
 *   - 锁存在且 PID 存活 → 已被占用，拒绝启动（返回占用 PID 供提示）
 *
+* PID 复用根治（2026-09-10）：PID 探活通过后再比对锁内 cmdline 摘要与该
+* PID 当前真实命令行（pid-cmdline.ts）——查不到或不一致 → PID 已被无关
+* 进程复用（持有者已死），视为残留允许接管。旧锁（无 cmdline 字段）无法
+* 校验，保守维持「占用」判定（一次性过渡：新锁写入时自动带摘要）。详见
+* pid-cmdline.ts 头注释的误判代价取舍。
+*
 * 退出清理：进程正常退出时 releaseInstanceLock 删除锁文件；崩溃/强杀残留
 * 由下次启动的「PID 存活检测」兜底（PID 已死 → 残留视为过期）。
 *
@@ -85,6 +171,15 @@ function checkInstanceLock(dataDir) {
 		pid: null,
 		lockPath
 	};
+	const lockCmdline = typeof info.cmdline === "string" && info.cmdline !== "" ? info.cmdline : void 0;
+	if (lockCmdline !== void 0 && CMDLINE_PROBE_SUPPORTED) {
+		const current = readCmdlineForPid(info.pid);
+		if (current === null || normalizeCmdline(current) !== normalizeCmdline(lockCmdline)) return {
+			occupied: false,
+			pid: null,
+			lockPath
+		};
+	}
 	return {
 		occupied: true,
 		pid: info.pid,
@@ -101,10 +196,11 @@ function acquireInstanceLock(dataDir, cmdline) {
 		if (pid === node_process.default.pid) return true;
 		return false;
 	}
+	const effectiveCmdline = cmdline !== void 0 && cmdline !== "" ? cmdline : selfCmdline();
 	const info = {
 		pid: node_process.default.pid,
 		startedAt: Date.now(),
-		...cmdline !== void 0 && cmdline !== "" ? { cmdline } : {}
+		...effectiveCmdline !== "" ? { cmdline: effectiveCmdline } : {}
 	};
 	try {
 		(0, node_fs.rmSync)(lockPath, { force: true });
@@ -856,6 +952,7 @@ function attachIpcServices(actions, services) {
 	forwardChannel(services.friendChannel, stops);
 	return () => {
 		for (const stop of stops) stop();
+		for (const name of full.keys()) actions.delete(name);
 	};
 }
 //#endregion
@@ -950,6 +1047,7 @@ async function attachOb11IpcBridge(actions, services, deps = {}) {
 			msgChannel: services.channel,
 			groupChannel: services.groupChannel,
 			friendChannel: services.friendChannel,
+			buddyCacheEvents: services.buddyCache?.events,
 			logger: services.logger,
 			msgApi: services.msgApi,
 			groupApi: services.groupApi,
@@ -999,6 +1097,7 @@ async function attachOb11IpcBridge(actions, services, deps = {}) {
 		return () => {
 			broadcaster.unregister(bridgeAdapter);
 			ob11.unsubscribeOnly();
+			for (const name of ob11.registry.names) actions.delete(name);
 		};
 	} catch (err) {
 		log(`ipc-ob11: OB11 动作桥装配失败（降级纯 kernel 动作面）: ${errMsg(err)}`);
@@ -1166,13 +1265,23 @@ function loadProtocolSections(kernel, uin) {
 const BACKSLASH_RE = /\\/g;
 /** adapter 入口 index.mjs 后缀（子路径导出替换用）。 */
 const INDEX_MJS_RE = /index\.mjs$/;
-/** 装配 OB11 + Satori 适配器（登录成功后，非 IPC 模式）。 */
+/**
+* 装配 OB11 + Satori 适配器（登录成功后，非 IPC 模式）。
+*
+* 返回停止函数（ob11/satori 适配器 stop：传输关闭 + 订阅清理；装配跳过时
+* no-op）——startProtocols 存入 services.stopAdapters，供未来非 IPC 软重登
+* 清理（当前软重登仅 IPC 模式有触发通道，见 relogin.ts）。
+*
+* ⚠️ 装配失败**抛出**（2026-09-08 修复）：cli 模式跑宿主就是为了 OB11/Satori
+* 服务，此处吞错会让 startProtocols 误判成功、以假 ready 留驻（内部 catch
+* 曾把 protocols.ts「装配失败返回 null 判引导失败」的意图整个短路）。
+*/
 async function assembleOb11AndSatori(kernel, services, loginResult) {
 	const adapterEntry = env.NAPUTO_ADAPTER_ENTRY;
 	const networkEntry = env.NAPUTO_NETWORK_ENTRY;
 	if (!adapterEntry || !networkEntry) {
 		log("bootstrap: NAPUTO_ADAPTER_ENTRY/NETWORK_ENTRY 未设置，跳过协议装配");
-		return;
+		return async () => {};
 	}
 	try {
 		const network = await import(`file://${networkEntry.replace(BACKSLASH_RE, "/")}`);
@@ -1194,12 +1303,13 @@ async function assembleOb11AndSatori(kernel, services, loginResult) {
 		const wrapperExports = services.ctx.wrapper?.exports;
 		const qqRoot = kernel.resolveQqUserDataRoot?.(wrapperExports) ?? null;
 		const mediaBaseDir = qqRoot !== null ? kernel.resolveQqGlobalPath?.(qqRoot) : void 0;
-		await new adapter.NapukettoOneBot11Adapter({
+		const ob11 = new adapter.NapukettoOneBot11Adapter({
 			config: ob11Config,
 			broadcaster,
 			msgChannel: channel,
 			groupChannel: services.groupChannel,
 			friendChannel: services.friendChannel,
+			buddyCacheEvents: services.buddyCache?.events,
 			logger: services.logger,
 			msgApi: services.msgApi,
 			groupApi: services.groupApi,
@@ -1231,7 +1341,8 @@ async function assembleOb11AndSatori(kernel, services, loginResult) {
 				}
 			},
 			groupCache
-		}).start();
+		});
+		await ob11.start();
 		log("bootstrap: onebot11 adapter started");
 		const satoriCacheDir = typeof satoriSection["cacheDir"] === "string" && satoriSection["cacheDir"] !== "" ? satoriSection["cacheDir"] : (0, node_path.join)(env.NAPUTO_CFG_DIR || ".", "cache");
 		const satoriConfig = new adapterCore.ProtocolConfig({
@@ -1240,7 +1351,7 @@ async function assembleOb11AndSatori(kernel, services, loginResult) {
 			defaults: satoriAdapter.satoriConfigSchema.parse({}),
 			seed: satoriAdapter.satoriConfigSchema.parse(satoriSection)
 		});
-		await new satoriAdapter.NapukettoSatoriAdapter({
+		const satori = new satoriAdapter.NapukettoSatoriAdapter({
 			config: satoriConfig,
 			broadcaster,
 			msgChannel: channel,
@@ -1252,10 +1363,16 @@ async function assembleOb11AndSatori(kernel, services, loginResult) {
 			self: services.self,
 			cacheDir: satoriCacheDir,
 			groupCache
-		}).start();
+		});
+		await satori.start();
 		log("bootstrap: satori adapter started");
+		return async () => {
+			await ob11.stop();
+			await satori.stop();
+		};
 	} catch (e) {
 		log(`bootstrap: 协议装配失败: ${errMsg(e)}`);
+		throw e;
 	}
 }
 //#endregion
@@ -1299,9 +1416,11 @@ function formatMessageLog(kernel, msg) {
 }
 /**
 * 消息日志订阅（onRecvMsg 回调参数为消息数组——2026-08-07 运行时实证，遍历逐条打印）。
+* 返回退订函数（软重登重装配时清理旧订阅，2026-09-08）；通道返回面宽松
+* （EventChannelLike.on 返回 unknown），非函数时退化为 no-op。
 */
 function setupMsgLogging(kernel, channel, logger, colorize) {
-	channel.on("Msg/onRecvMsg", (msgs) => {
+	const off = channel.on("Msg/onRecvMsg", (msgs) => {
 		forEachRawMessage(msgs, (m) => {
 			try {
 				const { plain, colored } = formatMessageLog(kernel, m);
@@ -1314,6 +1433,7 @@ function setupMsgLogging(kernel, channel, logger, colorize) {
 			}
 		});
 	});
+	return typeof off === "function" ? off : () => {};
 }
 //#endregion
 //#region src/host/core/kernel-services.ts
@@ -1327,9 +1447,10 @@ function setupMsgLogging(kernel, channel, logger, colorize) {
 /** 登录成功后创建 kernel 业务服务（channel/bridge/cache/apis）。失败返回 null。 */
 async function createKernelServices(kernel, ctx, loginResult) {
 	const ipcMode = env.NAPUTO_IPC === "1";
+	const logFile = env.NAPUTO_CFG_DIR !== void 0 ? (0, node_path.join)(env.NAPUTO_CFG_DIR, "logs", "loader.log") : (0, node_path.join)((0, node_os.tmpdir)(), "napuketto-loader.log");
 	const logger = kernel.createLogger?.({
 		console: !ipcMode,
-		...ipcMode ? { file: env.NAPUTO_CFG_DIR !== void 0 ? (0, node_path.join)(env.NAPUTO_CFG_DIR, "logs", "loader.log") : (0, node_path.join)((0, node_os.tmpdir)(), "napuketto-loader.log") } : {},
+		file: logFile,
 		base: { name: "loader" }
 	});
 	const session = ctx.session;
@@ -1338,21 +1459,29 @@ async function createKernelServices(kernel, ctx, loginResult) {
 		return null;
 	}
 	const channel = new kernel.NTEventChannel("Msg");
-	new kernel.MsgBridge(session, channel).register();
-	setupMsgLogging(kernel, channel, logger, !ipcMode);
+	const bridge = new kernel.MsgBridge(session, channel);
+	bridge.register();
+	const offMsgLogging = setupMsgLogging(kernel, channel, logger, !ipcMode);
 	const groupApi = new kernel.GroupApi(session);
 	const util = ctx.exports?.NodeQQNTWrapperUtil;
 	const msgApi = new kernel.MsgApi(session, channel, util);
 	const friendApi = new kernel.FriendApi(session, { uidToUin: (uids) => groupApi.uidToUin(uids) });
 	const groupChannel = new kernel.NTEventChannel("Group");
-	new kernel.GroupBridge(session, groupChannel).register();
+	const groupBridge = new kernel.GroupBridge(session, groupChannel);
+	groupBridge.register();
 	const friendChannel = new kernel.NTEventChannel("Buddy");
-	new kernel.FriendBridge(session, friendChannel).register();
+	const friendBridge = new kernel.FriendBridge(session, friendChannel);
+	friendBridge.register();
 	const groupCache = new kernel.GroupCache({
 		channel: groupChannel,
 		groupApi
 	});
 	groupCache.register();
+	const buddyCache = new kernel.BuddyCache({
+		channel: friendChannel,
+		logger
+	});
+	buddyCache.register();
 	const groupNotifyApi = new kernel.GroupNotifyApi(session);
 	const ticketApi = new kernel.TicketApi(session);
 	return {
@@ -1366,6 +1495,7 @@ async function createKernelServices(kernel, ctx, loginResult) {
 		groupApi,
 		friendApi,
 		groupCache,
+		buddyCache,
 		groupNotifyApi,
 		ticketApi,
 		richMediaApi: new kernel.RichMediaApi(session),
@@ -1378,7 +1508,15 @@ async function createKernelServices(kernel, ctx, loginResult) {
 		},
 		session,
 		engine: ctx.engine,
-		util: ctx.exports?.NodeQQNTWrapperUtil
+		util: ctx.exports?.NodeQQNTWrapperUtil,
+		dispose: () => {
+			bridge.unregister();
+			groupBridge.unregister();
+			friendBridge.unregister();
+			groupCache.unregister();
+			buddyCache.unregister();
+			offMsgLogging();
+		}
 	};
 }
 //#endregion
@@ -1408,7 +1546,7 @@ async function startProtocols(kernel, ctx, loginResult) {
 		return services;
 	}
 	try {
-		await assembleOb11AndSatori(kernel, services, loginResult);
+		services.stopAdapters = await assembleOb11AndSatori(kernel, services, loginResult);
 	} catch (e) {
 		log(`bootstrap: 协议装配失败: ${errMsg(e)}`);
 		return null;
@@ -1416,6 +1554,156 @@ async function startProtocols(kernel, ctx, loginResult) {
 	return services;
 }
 //#endregion
+//#region src/host/core/relogin.ts
+/**
+* relogin.ts：登录控制相位机 + control login 指令处理（2026-09-08 A1/A2）。
+*
+* control login（koishi 面板「重新登录/扫码登录」→ IPC control login 指令）
+* 的成功结果按引导相位分派三条路径：
+*  ① login-race（初始登录竞速中）：结果经 preemptRef 接管引导链——快速登录
+*     风控挂起时强制扫码也能走完装配链（2026-09-08 T2 既有语义）。
+*  ② ready（引导已完成）：**软重登**——重装配（清理旧服务 + 用新结果重跑
+*     装配链），不再整进程重启；完成后重播 ready + logged_in。
+*  ③ assembling/aborted：迟到结果**不上报**（A1 修复）——引导失败进程将退出，
+*     无条件 sendLogin("logged_in") 会制造 failed→logged_in 的误导序列
+*     （koishi driver 收到 logged_in 但子进程无协议装配，上线后所有请求失败）；
+*     装配进行中的并发结果同样忽略（不干扰初次装配链）。
+*
+* 防重入（2026-09-08 拍板）：control login 全程互斥（claim/release）——在途
+* 登录/重装配期间的新指令直接忽略（仅留日志，不发登录消息，面板随首个流程
+* 的真实状态收敛）。
+*/
+/** 登录控制相位机（bootstrapWithCore 持有，handler 与引导链共享）。 */
+var LoginControl = class {
+	phase = "login-race";
+	claimed = false;
+	preempt;
+	constructor(preempt) {
+		this.preempt = preempt;
+	}
+	/** 当前相位。 */
+	get currentPhase() {
+		return this.phase;
+	}
+	/** 取走竞速抢占口（登录期 control login 成功接管引导链用）；竞速已结束返回 null。 */
+	takePreempt() {
+		const resolve = this.preempt.resolve;
+		if (resolve === null) return null;
+		this.preempt.resolve = null;
+		return resolve;
+	}
+	/** 竞速结束（初始登录 settle）：关抢占口，进入装配期。 */
+	beginAssembly() {
+		this.preempt.resolve = null;
+		this.phase = "assembling";
+	}
+	/** 装配完成：开启软重登窗口。 */
+	markReady() {
+		this.phase = "ready";
+	}
+	/** 引导失败（进程将退出）：关抢占口，迟到 control login 结果不再上报。 */
+	abort() {
+		this.preempt.resolve = null;
+		this.phase = "aborted";
+	}
+	/** control login 互斥（在途防重入）：同一时刻只允许一个 control login 流程。 */
+	claim() {
+		if (this.claimed) return false;
+		this.claimed = true;
+		return true;
+	}
+	/** 释放互斥（core.login settle 后调用，含软重登重装配完成）。 */
+	release() {
+		this.claimed = false;
+	}
+};
+/** 登录状态字面量（IPC login 消息，与 kernel LoginState 对齐）。 */
+const LOGIN_STATES = [
+	"idle",
+	"waiting_scan",
+	"scanned",
+	"logged_in",
+	"failed"
+];
+/** 宽松收窄（kernel onLoginProgress.state 是 string；bootstrap-core 登录回调共用）。 */
+function isLoginState(value) {
+	return LOGIN_STATES.includes(value);
+}
+/** ready 态软重登：重装配 → 成功重播 ready/logged_in，失败交失败处理。 */
+async function softReloginAndReport(loginResult, selfInfo, deps) {
+	if (!await deps.reassemble(loginResult)) {
+		(deps.onReassembleFailed ?? defaultReassembleFailed)();
+		return;
+	}
+	sendStatus("ready");
+	sendLogin("logged_in", selfInfo);
+}
+/** control login 成功结果按相位分派（抽取自 handler，控制认知复杂度）。 */
+async function dispatchLoginSuccess(result, control, deps) {
+	const selfInfo = {
+		uin: result.uin,
+		uid: result.uid,
+		nick: result.nick ?? ""
+	};
+	const preemptResolve = control.takePreempt();
+	if (preemptResolve !== null) {
+		sendLogin("logged_in", selfInfo);
+		preemptResolve(result);
+		return;
+	}
+	if (control.currentPhase === "ready") {
+		await softReloginAndReport(result, selfInfo, deps);
+		return;
+	}
+	log(`relogin: control login 成功但引导相位=${control.currentPhase}，忽略结果`);
+}
+/** 重装配失败默认处理：上报 failed + 退出进程（koishi driver 重启循环回收）。 */
+function defaultReassembleFailed() {
+	log("relogin: 软重登重装配失败，上报 failed 并退出（driver 重启循环接管）");
+	sendStatus("failed", "软重登重装配失败", {
+		code: "UNKNOWN",
+		message: "软重登重装配失败，详见 napuketto-boot.log"
+	});
+	node_process.default.exit(1);
+}
+/**
+* control login 指令 → 重新登录（qr=true 强制扫码跳过快速登录，uin 指定账号）。
+* 成功结果按 LoginControl 相位分派（登录期抢占 / ready 软重登 / 忽略迟到）。
+* 该 handler 仅在 IPC 模式经 startIpcServer 的 onLogin 注册（见 bootstrapWithCore），
+* 非 IPC 模式无 control 通道不会触达，故无条件走 JSON 行协议、无需再判 ipcMode。
+*/
+function createLoginControlHandler(core, Appid, control, deps) {
+	return (payload) => {
+		if (!control.claim()) {
+			log("relogin: control login 在途（登录/软重登进行中），忽略本次请求");
+			return;
+		}
+		const opts = {
+			appid: String(Appid),
+			initTimeoutMs: 2e4,
+			qrFallback: true,
+			...payload.uin !== void 0 ? { quickUin: payload.uin } : {},
+			...payload.qr === true ? { qrOnly: true } : {},
+			onLoginProgress: (progress) => {
+				if (progress.qr !== void 0) sendQr(progress.qr.pngBase64, progress.qr.qrcodeUrl);
+				if (isLoginState(progress.state)) sendLogin(progress.state, progress.selfInfo, progress.message);
+			}
+		};
+		core.login(opts).then(async (result) => {
+			if (result === null) {
+				sendLogin("failed", void 0, "登录返回空结果");
+				return;
+			}
+			await dispatchLoginSuccess(result, control, deps);
+		}).catch((err) => {
+			log(`bootstrap: control login 失败: ${errMsg(err)}`);
+			sendLogin("failed", void 0, errMsg(err));
+		}).finally(() => {
+			control.release();
+		});
+	};
+}
+//#endregion
 //#region src/host/core/session.ts
 /** 对象有效性判断：getMsgService() 调用不抛断言（cpp_impl 已激活）。
 * 与 isSessionUsable 的区别：这里允许返回 null（未 init 但对象有效）。 */
@@ -1688,18 +1976,6 @@ function probeCreatedSession(state, ctx) {
 		log(`BOOT: create() 探测失败: ${errMsg(e)}`);
 	}
 }
-/** 登录状态字面量（IPC login 消息，与 kernel LoginState 对齐）。 */
-const LOGIN_STATES = [
-	"idle",
-	"waiting_scan",
-	"scanned",
-	"logged_in",
-	"failed"
-];
-/** 宽松收窄（kernel onLoginProgress.state 是 string）。 */
-function isLoginState(value) {
-	return LOGIN_STATES.includes(value);
-}
 /** 非 IPC 模式 QR 透出标记行前缀（cli forwardFiltered 解析后终端渲染）。 */
 const QR_LINE_PREFIX = "NAPUTO_QR ";
 /** 登录参数（NAPUTO_QUICK_UIN 强制指定 / ref 目标 / qrOnly 强制扫码 / 默认）。 */
@@ -1724,36 +2000,6 @@ function buildLoginOpts(Appid, forcedUin, ref, qrOnly = false) {
 	};
 	return opts;
 }
-/** control login 指令 → 重新登录（qr=true 强制扫码跳过快速登录，uin 指定账号）。
-* 登录期（初始 doLogin 竞速中）成功结果经 preemptRef 接管引导链。 */
-function createLoginControlHandler(core, Appid, preemptRef) {
-	return (payload) => {
-		const opts = {
-			appid: String(Appid),
-			initTimeoutMs: 2e4,
-			qrFallback: true,
-			...payload.uin !== void 0 ? { quickUin: payload.uin } : {},
-			...payload.qr === true ? { qrOnly: true } : {},
-			onLoginProgress: (progress) => {
-				if (progress.qr !== void 0) sendQr(progress.qr.pngBase64, progress.qr.qrcodeUrl);
-				if (isLoginState(progress.state)) sendLogin(progress.state, progress.selfInfo, progress.message);
-			}
-		};
-		core.login(opts).then((result) => {
-			if (result !== null) {
-				sendLogin("logged_in", {
-					uin: result.uin,
-					uid: result.uid,
-					nick: result.nick ?? ""
-				});
-				preemptRef?.resolve?.(result);
-			} else sendLogin("failed", void 0, "登录返回空结果");
-		}).catch((err) => {
-			log(`bootstrap: control login 失败: ${errMsg(err)}`);
-			sendLogin("failed", void 0, errMsg(err));
-		});
-	};
-}
 /** V2 登录后替换 session：优先 QQ 主 session，其次 vehicle 单例表；自建宿主例外。 */
 function replaceSession(kernel, core, state, ctx) {
 	if (env.NAPUTO_SELF_HOST === "1") return null;
@@ -1849,20 +2095,72 @@ async function bootstrapWithCore(kernel, state, bootEnv, Appid) {
 	const preemptLogin = new Promise((resolve) => {
 		preempt.resolve = resolve;
 	});
+	const control = new LoginControl(preempt);
+	const reassembleRef = { current: null };
 	if (env.NAPUTO_IPC === "1") {
 		ipcActions = createIpcActionsForCore(core);
 		startIpcServer({
 			actions: ipcActions,
-			onLogin: createLoginControlHandler(core, Appid, preempt)
+			onLogin: createLoginControlHandler(core, Appid, control, { reassemble: (loginResult) => {
+				const fn = reassembleRef.current;
+				if (fn === null) {
+					log("bootstrap: softRelogin 未就绪（理论不可达：相位机 ready 守卫）");
+					return Promise.resolve(false);
+				}
+				return fn(loginResult);
+			} })
 		});
 	}
 	const ctx = core.attachWrapper(state.wrapperExports, { ...bootEnv });
 	log(`bootstrap: attachWrapper OK, engine=${typeof ctx.engine}, session=${ctx.session !== null}`);
+	let services = null;
+	let stopIpcServices = null;
+	let stopOb11Bridge = null;
+	/**
+	* 装配链尾部（登录成功后；初次引导与软重登共用）。
+	* @returns 装配是否成功（协议服务未装配 = false，调用方判引导失败）。
+	*/
+	const runAssembly = async (loginResult, initial) => {
+		const chosen = replaceSession(kernel, core, state, ctx);
+		await activateSession(kernel, state, ctx, chosen, loginResult, Appid, bootEnv);
+		await waitSessionReady(kernel, ctx);
+		if (env.NAPUTO_IPC === "1") sendStatus("sessioning");
+		if (initial) await runSmokeIfEnabled(kernel, ctx, loginResult);
+		const newServices = await startProtocols(kernel, ctx, loginResult);
+		if (newServices === null) {
+			log("bootstrap: 协议服务装配失败，引导中止");
+			return false;
+		}
+		if (env.NAPUTO_IPC === "1" && ipcActions !== null) {
+			stopIpcServices = attachIpcServices(ipcActions, newServices);
+			stopOb11Bridge = await attachOb11IpcBridge(ipcActions, newServices);
+		}
+		services = newServices;
+		return true;
+	};
+	/**
+	* 软重登重装配（ready 态 control login 成功，relogin.ts 经 deps 调用）：
+	* 清理旧装配面 → 用新登录结果重跑装配链（A2，2026-09-08）。
+	* 清理顺序：协议消费方（OB11 桥退订+动作表移除）→ IPC 事件转发/动作表
+	* → kernel 桥/缓存/消息日志（dispose，幂等）。失败返回 false（上报退出）。
+	*/
+	const softRelogin = async (loginResult) => {
+		log(`bootstrap: 软重登 uin=${loginResult.uin}——清理旧装配并重跑装配链`);
+		stopOb11Bridge?.();
+		stopOb11Bridge = null;
+		stopIpcServices?.();
+		stopIpcServices = null;
+		services?.dispose();
+		services = null;
+		return await runAssembly(loginResult, false);
+	};
+	reassembleRef.current = softRelogin;
 	probeCreatedSession(state, ctx);
 	startSessionProbe(state, ctx);
 	probeSessionMethods(ctx);
 	if (typeof core.login !== "function") {
 		log("bootstrap: kernel core missing login fn");
+		control.abort();
 		return false;
 	}
 	const forcedUin = env.NAPUTO_QUICK_UIN;
@@ -1871,8 +2169,9 @@ async function bootstrapWithCore(kernel, state, bootEnv, Appid) {
 	await pickLoginAccount(kernel, ctx, ref, forcedUin);
 	if (env.NAPUTO_IPC === "1") sendStatus("logging");
 	const loginResult = await Promise.race([doLogin(core, buildLoginOpts(Appid, forcedUin, ref, qrOnly)), preemptLogin]);
-	preempt.resolve = null;
+	control.beginAssembly();
 	if (loginResult === null) {
+		control.abort();
 		log("bootstrap: 登录失败，引导中止");
 		if (env.NAPUTO_IPC === "1") sendStatus("failed", "登录失败", {
 			code: "NOT_LOGIN",
@@ -1886,19 +2185,11 @@ async function bootstrapWithCore(kernel, state, bootEnv, Appid) {
 		uid: loginResult.uid,
 		nick: loginResult.nick ?? ""
 	});
-	await activateSession(kernel, state, ctx, replaceSession(kernel, core, state, ctx), loginResult, Appid, bootEnv);
-	await waitSessionReady(kernel, ctx);
-	if (env.NAPUTO_IPC === "1") sendStatus("sessioning");
-	await runSmokeIfEnabled(kernel, ctx, loginResult);
-	const services = await startProtocols(kernel, ctx, loginResult);
-	if (services === null) {
-		log("bootstrap: 协议服务装配失败，引导中止");
+	if (!await runAssembly(loginResult, true)) {
+		control.abort();
 		return false;
 	}
-	if (env.NAPUTO_IPC === "1" && ipcActions !== null) {
-		attachIpcServices(ipcActions, services);
-		await attachOb11IpcBridge(ipcActions, services);
-	}
+	control.markReady();
 	runProbePhase(kernel, ctx);
 	return true;
 }