@coclaw/openclaw-coclaw 0.26.2 → 0.26.3

package/src/auto-upgrade/updater.js

@@ -2,17 +2,15 @@ import fs from 'node:fs/promises';
 import nodeFs from 'node:fs';
 import nodePath from 'node:path';
 
-import { checkForUpdate } from './updater-check.js';
+import { checkForUpdate, getPackageInfo, inspectPluginInstall } from './updater-check.js';
 import { spawnUpgradeWorker } from './updater-spawn.js';
-import { readState, resolveStateDir, writeState } from './state.js';
-import { getClawConfig } from '../claw-config.js';
+import { readInflight, readState, recordUpgradeTerminal, resolveStateDir, writeState } from './state.js';
+import { removeBackup } from './worker-backup.js';
+import { isVersionReached } from './worker-verify.js';
+import { getRuntime } from '../runtime.js';
 import { remoteLog } from '../remote-log.js';
 import { atomicWriteFile } from '../utils/atomic-write.js';
 
-// OpenClaw ≥ 2026.4.25 起把插件安装记录从 openclaw.json 的 plugins.installs
-// 迁移到独立账本文件，并在 loadConfig() 返回前剥掉 plugins.installs。
-const INSTALLS_LEDGER_RELATIVE_PATH = nodePath.join('plugins', 'installs.json');
-
 // 首次检查延迟较长：失败时由 worker 触发 gateway restart，scheduler 重启后会重新计时；
 // 60 分钟基线（实际随机 60-120 分钟）能把"失败→重启→再次检查"的循环周期拉长，
 // 避免连续升级失败时 gateway 在短时间内反复被打扰。
@@ -30,6 +28,46 @@ const LOCK_FILENAME = 'upgrade.lock';
 // 且底层升级命令失败会走回滚，不会破坏插件。
 const LOCK_TTL_MS = 110 * 60 * 1000; // 110 分钟
 
+// 精确 semver 形态（含可选 prerelease / build 段），spec 钉死检测用
+const EXACT_SEMVER_RE = /^\d+\.\d+\.\d+(-[\w.-]+)?(\+[\w.-]+)?$/;
+
+// 运行态版本：模块加载时刻同步捕获，coclaw.upgradeHealth handler 与 inflight
+// 对账共用本快照（getLoadedPluginVersion）。成功判据必须反映"当前 gateway
+// 真正加载的代码"，禁止判定时再读磁盘 package.json：中断的升级可能已把磁盘
+// 写成新版本而新代码从未被加载，误记成功会删掉唯一的回滚备份。
+// （src/plugin-version.js 的懒读缓存原语是 info 展示用，语义不同，勿互相替代。）
+let LOADED_PLUGIN_VERSION = null;
+try {
+	const rawPkg = nodeFs.readFileSync(nodePath.resolve(import.meta.dirname, '../../package.json'), 'utf8');
+	const ver = JSON.parse(rawPkg)?.version;
+	LOADED_PLUGIN_VERSION = typeof ver === 'string' ? ver : null;
+}
+/* c8 ignore next 3 -- 自身 package.json 读取失败的兜底：测试环境必可读 */
+catch {
+	// 读不到自身 package.json：对账退化为"无法判定"，保留 inflight 下轮重试
+}
+
+/**
+ * 加载时刻钉住的自身版本快照（即当前进程真正加载的代码）。
+ * 快照不可得时返回 null——调用方把 null 当"未达标"是保守正确方向；
+ * 禁止加"为 null 就回退读磁盘"的 fallback（见上方快照注释的 Why）。
+ * @returns {string|null}
+ */
+export function getLoadedPluginVersion() {
+	return LOADED_PLUGIN_VERSION;
+}
+
+/**
+ * 测试用：覆盖加载时快照（判别"返回快照 vs 调用时读磁盘"），返回旧值便于恢复。
+ * @param {string|null} version
+ * @returns {string|null}
+ */
+export function __setLoadedPluginVersionForTest(version) {
+	const prev = LOADED_PLUGIN_VERSION;
+	LOADED_PLUGIN_VERSION = version;
+	return prev;
+}
+
 // ── upgrade.lock：保证同时最多一个 worker 进程 ──
 
 export function getLockPath() {
@@ -115,107 +153,77 @@ export async function writeUpgradeLock(pid) {
 }
 
 /**
- * 读取本插件的安装记录（兼容新旧 OpenClaw 契约）
- *
- * - 新版（OpenClaw ≥ 2026.4.25）：账本文件 `<state-dir>/plugins/installs.json`
- *   下的 `installRecords[pluginId]` 是来源真相；`loadConfig()` 返回的对象里
- *   `plugins.installs` 已被剥离。
- * - 旧版（OpenClaw ≤ 2026.4.24）：账本文件不存在，
- *   `loadConfig().plugins.installs[pluginId]` 是来源真相。
- *
- * 兼容策略：先尝试账本文件；ENOENT（文件不存在）→ 回落到旧字段；
- * 其它失败（权限/JSON 损坏/缺记录）→ 视为账本不可用，按"无来源信息"处理，不回落。
- * 这两条互斥（新 gateway 必有账本、旧 gateway 必无）能让两个分支天然分流。
- *
- * 失败路径会通过 `remoteLog` 外推诊断信号（`upgrade.state-dir-failed` /
- * `upgrade.ledger-read-failed` / `upgrade.ledger-parse-failed`），避免运维只
- * 看到 start() 那条 "Skipping: not an npm-installed plugin" 时误判方向。
+ * 包含谓词：判断 child 是否位于 parent 内（两者均须已 realpath 归一）。
  *
- * 注：内部 `readFileSync` 为同步 IO，**有意保留**——只在升级周期决策时读一次
- * 账本（整个进程生命周期通常一锤子）。改 async 必须沿 `shouldSkipAutoUpgrade`
- * 等调用链向上传播，收益不抵成本。
+ * 禁用裸 `startsWith('..')`——`..foo` 这类目录名会被误判为"在外"。
+ * Windows 大小写差异由 path.win32.relative 天然处理；跨盘符（relative 返回
+ * 绝对路径）落 isAbsolute 兜住。
  *
- * 另：OpenClaw plugin SDK 当前未暴露查询 installRecords 的 API，只能直接读
- * `<state-dir>/plugins/installs.json`（与上游 `manifest-metadata-scan` 等
- * 内部模块同源做法）。如果上游后续开放官方接口，可切换并删除直读分支。
- *
- * @param {string} pluginId
- * @returns {object|null}
+ * @param {string} parent
+ * @param {string} child
+ * @param {object} [pathImpl] - 测试注入（win32 盘符/大小写边角）；默认 nodePath
+ * @returns {boolean}
  */
-function loadInstallRecord(pluginId) {
-	let ledgerPath;
-	try {
-		ledgerPath = nodePath.join(resolveStateDir(), INSTALLS_LEDGER_RELATIVE_PATH);
-	}
-	catch (err) {
-		// 极少触发：host runtime 的 state resolver 自身异常
-		/* c8 ignore next -- ?? fallback：err 字段缺省的兜底分支不强制覆盖 */
-		remoteLog(`upgrade.state-dir-failed msg=${err?.message ?? String(err)}`);
-		return null;
-	}
-	let raw;
-	try {
-		raw = nodeFs.readFileSync(ledgerPath, 'utf8');
-	}
-	catch (err) {
-		if (err?.code === 'ENOENT') {
-			return loadInstallRecordFromLegacyConfig(pluginId);
-		}
-		// 账本应该可读但读不到（权限/EISDIR/IO 错误）：不回落到旧字段，避免误判老路径
-		// 静默返回 null 会让 start() 打 "Skipping: not an npm-installed plugin"，对运维毫无指向；
-		// 把诊断信号外推到 server，便于定位
-		/* c8 ignore next -- ?? fallback：err 字段缺省的兜底分支不强制覆盖 */
-		remoteLog(`upgrade.ledger-read-failed code=${err?.code ?? 'unknown'} msg=${err?.message ?? String(err)}`);
-		return null;
-	}
-	let parsed;
-	try {
-		parsed = JSON.parse(raw);
-	}
-	catch (err) {
-		// 账本损坏：同样不回落，并外推诊断信号
-		/* c8 ignore next -- ?? fallback：err 字段缺省的兜底分支不强制覆盖 */
-		remoteLog(`upgrade.ledger-parse-failed msg=${err?.message ?? String(err)}`);
-		return null;
-	}
-	return parsed?.installRecords?.[pluginId] ?? null;
+export function isPathInside(parent, child, pathImpl) {
+	/* c8 ignore next -- ?? fallback */
+	const p = pathImpl ?? nodePath;
+	const rel = p.relative(parent, child);
+	return rel === '' || (!rel.startsWith(`..${p.sep}`) && rel !== '..' && !p.isAbsolute(rel));
 }
 
 /**
- * 旧版 OpenClaw（≤ 2026.4.24）账本路径：openclaw.json 的 plugins.installs。
- * @param {string} pluginId
- * @returns {object|null}
+ * 判断是否应跳过自动升级（L0：Nix 短路 + 位置自检）
+ *
+ * 账本直读已移除；来源判定（npm/path/archive/...）后移到 L1（`__check` 内
+ * 逐周期 inspect，瞬时失败下周期自愈）。这里只做启动时刻的同步短路：
+ * - Nix mode：config 不可变，自动升级无意义；
+ * - 位置自检：正式安装三代均落在 state-dir 内，自身包根在外 ⇒ dev/link 装置，
+ *   跳过整个 scheduler——避免 dev 长命网关在"已发版未 pull"常态窗口每小时
+ *   spawn 一次 inspect，且不依赖 CLI 可用性。
+ *
+ * 只信 runtime 注入的 resolveStateDir：state.js 的 env/home 兜底可能与上游
+ * 真实 state-dir 分叉，不得用于"在外"判定。runtime 不可用或 realpath/谓词
+ * 任一步抛错 → 不下"在外"结论，放行到 L1 兜底 + remoteLog 信号。
+ *
+ * @param {string} pluginId - 兼容旧签名保留；位置判定不依赖它
+ * @param {object} [opts] - 测试注入
+ * @param {string} [opts.pluginRoot] - 覆盖自身包根
+ * @param {string} [opts.stateDir] - 覆盖 state-dir（绕过 runtime）
+ * @returns {boolean} true 表示应跳过自动升级
  */
-function loadInstallRecordFromLegacyConfig(pluginId) {
+export function shouldSkipAutoUpgrade(pluginId, opts) {
+	if (isNixMode()) return true;
 	try {
-		const config = getClawConfig();
-		return config?.plugins?.installs?.[pluginId] ?? null;
+		let stateDir = opts?.stateDir;
+		if (stateDir == null) {
+			const rt = getRuntime();
+			if (typeof rt?.state?.resolveStateDir !== 'function') {
+				// runtime 不可用：不能用 env/home 兜底下"在外"结论，放行到 L1
+				remoteLog('upgrade.state-dir-failed msg=runtime resolveStateDir unavailable');
+				return false;
+			}
+			stateDir = rt.state.resolveStateDir();
+		}
+		// 先 resolve 得根、再 realpath：link 模式下结果确定为 stage 根（与 updater-check.js 同锚点）
+		const pkgRoot = nodeFs.realpathSync(
+			opts?.pluginRoot ?? nodePath.resolve(import.meta.dirname, '../..'),
+		);
+		const realStateDir = nodeFs.realpathSync(stateDir);
+		if (!isPathInside(realStateDir, pkgRoot)) {
+			// start() 每次 gateway 启动只走一次，至多一条，与 nix-skip 同级
+			remoteLog(`upgrade.position-skip pkgRoot=${pkgRoot} stateDir=${realStateDir}`);
+			return true;
+		}
+		return false;
 	}
 	catch (err) {
-		// 与同函数其他 catch 风格对齐：旧版账本读取异常也外推诊断信号，
-		// 否则下游只能看到笼统的 "Skipping: not an npm-installed plugin"，无定位线索
+		// realpath/谓词任一步异常：不下"在外"结论，放行 + 信号
 		/* c8 ignore next -- ?? fallback：err 字段缺省的兜底分支不强制覆盖 */
-		remoteLog(`upgrade.legacy-config-read-failed msg=${err?.message ?? String(err)}`);
-		return null;
+		remoteLog(`upgrade.state-dir-failed msg=${err?.message ?? String(err)}`);
+		return false;
 	}
 }
 
-/**
- * 判断是否应跳过自动升级
- *
- * `openclaw plugins update` 仅对 source === "npm" 的安装生效。
- * source 的可能值：
- * - "npm"：从 npm registry 安装（生产环境，允许自动升级）
- * - "path"：link 模式（本地开发，跳过）
- * - "archive"：从 tarball 安装（跳过）
- *
- * @param {string} pluginId
- * @returns {boolean} true 表示应跳过自动升级
- */
-export function shouldSkipAutoUpgrade(pluginId) {
-	return loadInstallRecord(pluginId)?.source !== 'npm';
-}
-
 /**
  * 判断 host 是否运行在 Nix mode。
  *
@@ -231,15 +239,6 @@ export function isNixMode() {
 	return process.env.OPENCLAW_NIX_MODE === '1';
 }
 
-/**
- * 获取插件安装路径
- * @param {string} pluginId
- * @returns {string|null}
- */
-export function getPluginInstallPath(pluginId) {
-	return loadInstallRecord(pluginId)?.installPath ?? null;
-}
-
 /**
  * 自动升级调度器
  */
@@ -255,6 +254,8 @@ export class AutoUpgradeScheduler {
 	__opts = {};
 	/** 已报告过的 lastUpgrade.ts，用于去重 */
 	__lastReportedUpgradeTs = null;
+	/** L1 门禁信号去重：key=`<原因>|<toVersion>`，重启重置（稳定态装置至多重发一条） */
+	__reportedGateSignals = new Set();
 
 	/**
 	 * @param {object} [params]
@@ -267,7 +268,15 @@ export class AutoUpgradeScheduler {
 	 * @param {Function} [params.opts.spawnFn]
 	 * @param {Function} [params.opts.shouldSkipFn]
 	 * @param {Function} [params.opts.isNixModeFn]
-	 * @param {Function} [params.opts.getPluginInstallPathFn]
+	 * @param {Function} [params.opts.inspectInstallFn] - L1 来源门禁的 inspect 注入
+	 * @param {string} [params.opts.pluginRoot] - L0 位置自检/L1 回退的包根注入
+	 * @param {string} [params.opts.stateDir] - L0 位置自检的 state-dir 注入
+	 * @param {Function} [params.opts.readInflightFn] - inflight 对账读注入
+	 * @param {Function} [params.opts.recordUpgradeTerminalFn] - inflight 对账终态写注入
+	 * @param {Function} [params.opts.removeBackupFn] - inflight 对账备份清理注入
+	 * @param {string} [params.opts.runtimeVersion] - 运行态版本覆盖（对账判据注入）
+	 * @param {string} [params.opts.platform] - spawn 探针平台覆盖
+	 * @param {NodeJS.ProcessEnv} [params.opts.scopeEnv] - spawn 探针 env 覆盖
 	 */
 	constructor(params) {
 		if (params?.pluginId) this.__pluginId = params.pluginId;
@@ -300,13 +309,13 @@ export class AutoUpgradeScheduler {
 		}
 
 		const shouldSkip = this.__opts.shouldSkipFn ?? shouldSkipAutoUpgrade;
-		if (shouldSkip(this.__pluginId)) {
-			this.__logger.info?.('[auto-upgrade] Skipping: not an npm-installed plugin');
+		if (shouldSkip(this.__pluginId, this.__opts)) {
+			this.__logger.info?.('[auto-upgrade] Skipping: plugin package root is outside state-dir (dev/link install)');
 			this.__running = false;
 			return;
 		}
 
-		// 默认 5~10 分钟随机延迟，避免多实例同时发起检查
+		// 默认 60~120 分钟随机延迟，避免多实例同时发起检查
 		/* c8 ignore next 2 -- ?? fallback：测试始终注入 initialDelayMs */
 		const initialDelay = this.__opts.initialDelayMs
 			?? (INITIAL_DELAY_MS + Math.floor(Math.random() * INITIAL_DELAY_MS));
@@ -339,6 +348,20 @@ export class AutoUpgradeScheduler {
 		this.__logger.info?.('[auto-upgrade] Scheduler stopped');
 	}
 
+	/**
+	 * L1 门禁信号去重上报：同一 (原因, toVersion) 每个 gateway 进程周期只发一条。
+	 * source-skip / 无记录是稳定态，逐周期重验若不去重会每小时刷 server；
+	 * gate-inspect-failed 持续存在时也只需一条（重启重置，至多重发一条）。
+	 * installPath 回退两条信号（fallback / pkg-name-mismatch）同模式去重。
+	 * @param {string} key - 去重键，`<原因>|<toVersion>`
+	 * @param {string} text - remoteLog 文本
+	 */
+	__gateSignalOnce(key, text) {
+		if (this.__reportedGateSignals.has(key)) return;
+		this.__reportedGateSignals.add(key);
+		remoteLog(text);
+	}
+
 	/**
 	 * 检查 lastUpgrade 是否有未报告的结果，若有则 remoteLog 并标记已报告
 	 */
@@ -350,7 +373,9 @@ export class AutoUpgradeScheduler {
 			if (!last?.ts || last.ts === state.lastReport) return;
 			if (last.ts === this.__lastReportedUpgradeTs) return;
 			this.__lastReportedUpgradeTs = last.ts;
-			remoteLog(`upgrade.result result=${last.result} from=${last.from} to=${last.to}`);
+			// error 附上报行（lastUpgrade.error 已在写入时截断），真因远程可见
+			const errSuffix = last.error ? ` error=${last.error}` : '';
+			remoteLog(`upgrade.result result=${last.result} from=${last.from} to=${last.to}${errSuffix}`);
 			this.__logger.info?.(`[auto-upgrade] Last upgrade: ${last.from} → ${last.to} result=${last.result}`);
 			state.lastReport = last.ts;
 			const writeStateFn = this.__opts.writeStateFn ?? writeState;
@@ -362,6 +387,98 @@ export class AutoUpgradeScheduler {
 		}
 	}
 
+	/**
+	 * inflight 对账：worker 写过 inflight 但没活到终态记账（典型：被自己触发的
+	 * 网关重启杀死）时，由 scheduler 在锁空闲周期补记终态。
+	 *
+	 * 成功判据用模块加载时刻捕获的运行态版本（LOADED_PLUGIN_VERSION，与
+	 * upgradeHealth 同源）：达 verifyTarget → 补记 ok + 删备份（verifyTarget ≠
+	 * toVersion 时复刻 worker advancedShortfall 语义补 skip）；未达 → 补记
+	 * interrupted（带 phase）+ 告警，不自动 skip——回滚记账已前移 + 终态原子化后，
+	 * 中断窗口只剩"死在回滚中途"，下周期重验自然收敛，自动 skip 反而误伤瞬态。
+	 * interrupted 不清备份（保留人工恢复，下次备份前覆盖）。
+	 *
+	 * 畸形 inflight（verifyTarget 与 to 皆缺）永远无法判定达标，defer 会让升级
+	 * 管线永久停摆——按 interrupted（phase=malformed）消化；只有自身快照不可得
+	 * （runtimeVersion 空）才 defer（"无法判定就不动盘"的正确保守）。
+	 *
+	 * @returns {Promise<boolean>} false 表示 inflight 存在但未消化（判据不可得 /
+	 *   终态写失败），本周期应跳过 checkForUpdate，避免新 spawn 覆盖中断账目
+	 */
+	async __reconcileInflight() {
+		let inflight;
+		try {
+			/* c8 ignore next -- ?? fallback */
+			const readInflightFn = this.__opts.readInflightFn ?? readInflight;
+			inflight = await readInflightFn();
+		}
+		catch (err) {
+			this.__logger.warn?.(`[auto-upgrade] Inflight read failed: ${err?.message}`);
+			remoteLog(`upgrade.reconcile-failed msg=${err?.message}`);
+			return false;
+		}
+		if (!inflight) return true;
+
+		const { from, to, verifyTarget, phase } = inflight;
+		/* c8 ignore next -- ?? fallback */
+		const recordTerminal = this.__opts.recordUpgradeTerminalFn ?? recordUpgradeTerminal;
+		const target = verifyTarget || to;
+		if (!target) {
+			// 畸形 inflight：无判定目标，defer 等不来转机，按 interrupted 消化让管线继续
+			try {
+				await recordTerminal({ from: from || 'unknown', to: to || 'unknown', result: 'interrupted', phase: 'malformed' });
+			}
+			catch (err) {
+				// 终态写失败：inflight 保留，下轮重试；本周期不再 spawn
+				this.__logger.warn?.(`[auto-upgrade] Inflight reconcile failed: ${err?.message}`);
+				remoteLog(`upgrade.reconcile-failed msg=${err?.message}`);
+				return false;
+			}
+			this.__gateSignalOnce('reconcile-malformed', 'upgrade.reconcile-malformed');
+			this.__logger.warn?.('[auto-upgrade] Malformed inflight (no verifyTarget/to), recorded as interrupted');
+			return true;
+		}
+		/* c8 ignore next -- ?? fallback */
+		const runtimeVersion = this.__opts.runtimeVersion ?? LOADED_PLUGIN_VERSION;
+		if (!runtimeVersion) {
+			// 判据不可得：不下结论，保留 inflight 下轮重试
+			this.__gateSignalOnce(
+				`reconcile-no-version|${to}`,
+				`upgrade.reconcile-no-version to=${to}`,
+			);
+			this.__logger.warn?.('[auto-upgrade] Inflight found but reconcile criteria unavailable, deferring');
+			return false;
+		}
+		try {
+			if (isVersionReached(runtimeVersion, target)) {
+				// 运行态已达 verifyTarget：升级实际生效（worker 只是没活到记账），补记成功
+				await recordTerminal({
+					from, to: runtimeVersion, result: 'ok',
+					skipVersion: target !== to ? to : undefined,
+				});
+				/* c8 ignore next -- ?? fallback */
+				const doRemoveBackup = this.__opts.removeBackupFn ?? removeBackup;
+				try { await doRemoveBackup(this.__pluginId); }
+				catch (e) { this.__logger.warn?.(`[auto-upgrade] Reconcile backup cleanup failed (non-fatal): ${e?.message}`); }
+				this.__logger.info?.(`[auto-upgrade] Reconciled interrupted upgrade as ok: ${from} → ${runtimeVersion}`);
+			}
+			else {
+				/* c8 ignore next -- ?? fallback */
+				const phaseToken = phase ?? 'unknown';
+				await recordTerminal({ from, to, result: 'interrupted', phase: phaseToken });
+				remoteLog(`upgrade.interrupted from=${from} to=${to} phase=${phaseToken} runtime=${runtimeVersion}`);
+				this.__logger.warn?.(`[auto-upgrade] Interrupted upgrade detected: ${from} → ${to} (phase=${phaseToken})`);
+			}
+			return true;
+		}
+		catch (err) {
+			// 终态写失败：inflight 保留，下轮重试；本周期不再 spawn
+			this.__logger.warn?.(`[auto-upgrade] Inflight reconcile failed: ${err?.message}`);
+			remoteLog(`upgrade.reconcile-failed msg=${err?.message}`);
+			return false;
+		}
+	}
+
 	/**
 	 * 执行一次检查
 	 */
@@ -377,6 +494,10 @@ export class AutoUpgradeScheduler {
 				return;
 			}
 
+			// 锁空闲才对账：先消化 inflight（补记中断 worker 的终态），再跑新
+			// checkForUpdate——未消化就 spawn 会让新 worker 覆盖中断账目
+			if (!(await this.__reconcileInflight())) return;
+
 			// 报告上一次升级结果（若有未报告的）
 			await this.__reportLastUpgradeResult();
 
@@ -386,8 +507,19 @@ export class AutoUpgradeScheduler {
 			});
 
 			if (!result.available) {
-				if (result.skipped) {
-					remoteLog(`upgrade.skipped version=${result.latestVersion}`);
+				if (result.prerelease) {
+					// prerelease 挂 latest（人为失误）是稳定态，逐周期重验须去重防刷屏
+					this.__gateSignalOnce(
+						`prerelease-skip|${result.latestVersion}`,
+						`upgrade.prerelease-skip version=${result.latestVersion}`,
+					);
+					this.__logger.info?.(`[auto-upgrade] Latest ${result.latestVersion} is a prerelease, skipping`);
+				} else if (result.skipped) {
+					// skipped 同为稳定态（直到下个正式版发布），同模式去重
+					this.__gateSignalOnce(
+						`skipped|${result.latestVersion}`,
+						`upgrade.skipped version=${result.latestVersion}`,
+					);
 					this.__logger.info?.(`[auto-upgrade] Version ${result.latestVersion} skipped (previously failed)`);
 				} else {
 					this.__logger.info?.(`[auto-upgrade] No update available (current: ${result.currentVersion})`);
@@ -395,26 +527,120 @@ export class AutoUpgradeScheduler {
 				return;
 			}
 
+			// L1 来源门禁：有新版才核对权威安装记录（独立 CLI 子进程，不冻结网关，
+			// 逐周期重验——结构上消灭"一次误判 → 永久静默停摆"）。
+			// 必须局部 try/catch：外层 catch-all 会把这里的异常吞成泛化 upgrade.check-failed，混淆信号。
+			let install;
+			try {
+				/* c8 ignore next -- ?? fallback */
+				const inspectInstall = this.__opts.inspectInstallFn ?? inspectPluginInstall;
+				const inspected = await inspectInstall(this.__pluginId, { execFileFn: this.__opts.execFileFn });
+				if (!inspected.ok) {
+					// inspect 真失败（exit≠0 / 解析失败）：本周期跳过，下周期自动重试（瞬时自愈、持续可见）
+					this.__gateSignalOnce(
+						`gate-inspect-failed|${result.latestVersion}`,
+						`upgrade.gate-inspect-failed to=${result.latestVersion} msg=${inspected.reason}`,
+					);
+					this.__logger.warn?.(`[auto-upgrade] Install record inspect failed, skipping this cycle: ${inspected.reason}`);
+					return;
+				}
+				install = inspected.install;
+			}
+			catch (err) {
+				// 注入实现异常也按真失败处理：跳过本周期，下周期重试
+				/* c8 ignore next -- ?? fallback：err 字段缺省的兜底分支不强制覆盖 */
+				const msg = err?.message ?? String(err);
+				this.__gateSignalOnce(
+					`gate-inspect-failed|${result.latestVersion}`,
+					`upgrade.gate-inspect-failed to=${result.latestVersion} msg=${msg}`,
+				);
+				this.__logger.warn?.(`[auto-upgrade] Install record inspect threw, skipping this cycle: ${msg}`);
+				return;
+			}
+
+			const source = install?.source ?? 'none';
+			if (source !== 'npm') {
+				// 非 npm 装置（path/archive/git/...）或无安装记录（source=none）：
+				// 与现状语义等价（这些装置今天也不升级），但多了远程可见性
+				this.__gateSignalOnce(
+					`source-skip:${source}|${result.latestVersion}`,
+					`upgrade.source-skip source=${source} to=${result.latestVersion}`,
+				);
+				this.__logger.info?.(`[auto-upgrade] Skipping: install source is ${source} (not npm)`);
+				return;
+			}
+
+			// spec 钉死可见性：install.spec 是精确版本时 update 永远 resolve 同一版本
+			//（fallback install / 人工 `pkg@x.y.z` 留下的）。worker 侧裸包名 update 会
+			// 顺带解钉，这里只发去重信号，不改行为
+			const spec = typeof install.spec === 'string' ? install.spec : '';
+			const specAt = spec.lastIndexOf('@');
+			if (specAt > 0 && EXACT_SEMVER_RE.test(spec.slice(specAt + 1))) {
+				this.__gateSignalOnce(
+					`spec-pinned|${result.latestVersion}`,
+					`upgrade.spec-pinned spec=${spec}`,
+				);
+			}
+
+			// 来源验明 npm 后才上报 available——否则永不升级的装置每小时刷一条
 			remoteLog(`upgrade.available from=${result.currentVersion} to=${result.latestVersion}`);
 			this.__logger.info?.(`[auto-upgrade] Update available: ${result.currentVersion} → ${result.latestVersion}`);
 
-			const getInstallPath = this.__opts.getPluginInstallPathFn ?? getPluginInstallPath;
-			const pluginDir = getInstallPath(this.__pluginId);
+			// installPath 取自权威记录（新鲜）；缺失时回退自推包根，
+			// 并核验该目录 package.json 的包名，防错传目录给备份/回滚
+			let pluginDir = install.installPath;
 			if (!pluginDir) {
-				remoteLog('upgrade.no-install-path');
-				this.__logger.warn?.('[auto-upgrade] Cannot determine plugin install path');
-				return;
+				pluginDir = this.__opts.pluginRoot ?? nodePath.resolve(import.meta.dirname, '../..');
+				// 记录缺 installPath 是稳定异常态，与门禁信号同模式按 (原因, toVersion) 去重
+				this.__gateSignalOnce(
+					`install-path-fallback|${result.latestVersion}`,
+					`upgrade.install-path-fallback to=${result.latestVersion} dir=${pluginDir}`,
+				);
+				this.__logger.warn?.(`[auto-upgrade] Install record has no installPath, falling back to plugin root: ${pluginDir}`);
+				let pkgName = null;
+				try {
+					({ name: pkgName } = await getPackageInfo(pluginDir));
+				}
+				catch {
+					// package.json 读不到/损坏：按核验失败处理
+				}
+				if (pkgName !== result.pkgName) {
+					this.__gateSignalOnce(
+						`no-install-path:pkg-name-mismatch|${result.latestVersion}`,
+						`upgrade.no-install-path reason=pkg-name-mismatch got=${pkgName}`,
+					);
+					this.__logger.warn?.(`[auto-upgrade] Fallback plugin dir failed package name check (got ${pkgName}), skipping`);
+					return;
+				}
 			}
 
-			const { child } = spawnUpgradeWorker({
+			// 基线版本来自权威记录：worker 据此区分"record 推进/未推进"（L2 结局核对）
+			const baselineVersion = typeof install.version === 'string' ? install.version : '';
+			this.__logger.info?.(`[auto-upgrade] Pre-upgrade baseline: version=${baselineVersion || '(unknown)'} path=${pluginDir}`);
+
+			const { child, escapeFailed } = await spawnUpgradeWorker({
 				pluginDir,
 				fromVersion: result.currentVersion,
 				toVersion: result.latestVersion,
+				baselineVersion,
 				pluginId: this.__pluginId,
 				pkgName: result.pkgName,
-				opts: { spawnFn: this.__opts.spawnFn },
+				opts: {
+					spawnFn: this.__opts.spawnFn,
+					execFileFn: this.__opts.execFileFn,
+					platform: this.__opts.platform,
+					scopeEnv: this.__opts.scopeEnv,
+				},
 				logger: this.__logger,
 			});
+			if (escapeFailed) {
+				// systemd 形态但 scope 脱逃不可用：worker 大概率活不过自己触发的重启，
+				// 终态靠下轮 inflight 对账兜底；稳定态信号去重防每小时刷屏
+				this.__gateSignalOnce(
+					`cgroup-escape-failed|${result.latestVersion}`,
+					`upgrade.cgroup-escape-failed to=${result.latestVersion}`,
+				);
+			}
 
 			// 记录 worker PID，下次 check 时据此判断 worker 是否仍在运行
 			/* c8 ignore next -- ?? fallback */
@@ -422,8 +648,10 @@ export class AutoUpgradeScheduler {
 			await writeLock(child.pid);
 		}
 		catch (err) {
-			remoteLog(`upgrade.check-failed msg=${err.message}`);
-			this.__logger.warn?.(`[auto-upgrade] Check failed: ${err.message}`);
+			/* c8 ignore next -- ?? fallback：err 字段缺省的兜底分支不强制覆盖 */
+			const msg = err?.message ?? String(err);
+			remoteLog(`upgrade.check-failed msg=${msg}`);
+			this.__logger.warn?.(`[auto-upgrade] Check failed: ${msg}`);
 		}
 		finally {
 			this.__checking = false;