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

package/lib/plugin-self-update.js

@@ -10,13 +10,16 @@
 //   - 下载地址由 `resolvePluginUrl()` 解析后接入执行链（R4）；
 //   - 期望内容标识以**解包后复算的值**为准（合成清单没有它也能正确收尾）（R5）；
 //   - 安装/解包用**异步子进程**，不在宿主主线程上阻塞 HTTP/SSE/agent（R6）。
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { createReadStream, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
 import { createHash } from "node:crypto";
 import { spawn, spawnSync } from "node:child_process";
+import { appCarrierAlias, discoverAppCarrier } from "./app-carrier.js";
 import { pluginContentDigest } from "./plugin-content-digest.js";
 import { fetchUpdateResource } from "./update-fetch.js";
 import { decidePluginUpdate, normalizeReleaseManifest } from "./plugin-update.js";
+import { NPM_CHECK_LOG_LIMIT, createNpmPackageView, resolveNpmUpdateCandidate } from "./npm-update-source.js";
+import { quoteShellArgument, shellOptions } from "./tool-process.js";
 import {
 	TRANSACTION_PHASE,
 	acquireLock,
@@ -62,7 +65,7 @@ export const UPSTREAM_MANIFEST_URL = `https://github.com/${UPSTREAM_REPO}/releas
 export const UPSTREAM_RELEASES_API = `https://api.github.com/repos/${UPSTREAM_REPO}/releases/latest`;
 
 /** 更新来源的三种配置形态。 */
-export const UPDATE_SOURCE_KIND = { UPSTREAM: "upstream", OFF: "off", CUSTOM: "custom", INVALID: "invalid" };
+export const UPDATE_SOURCE_KIND = { NPM: "npm", UPSTREAM: "upstream", OFF: "off", CUSTOM: "custom", INVALID: "invalid" };
 
 /** 检查结果（会随 bootstrap/diagnostics 下发，也是 PC 端提示的依据）。 */
 export const UPDATE_CHECK_STATE = {
@@ -88,44 +91,57 @@ export const UPDATE_STEP = {
 /** 回滚最多一次：避免"重启风暴"。 */
 export const MAX_ROLLBACK_ATTEMPTS = 1;
 
-/** 异步跑一个子进程（**不阻塞宿主事件循环**）。 */
-export function runCommand(cmd, args, { cwd, timeoutMs = 10 * 60 * 1000 } = {}) {
+/** 异步跑一个子进程；两个输出管道始终并行 drain，避免高输出安装被管道背压卡住。 */
+export function runCommand(cmd, args, { cwd, timeoutMs = 10 * 60 * 1000, maxOutputBytes = 16 * 1024, onOutput, platform = process.platform } = {}) {
 	return new Promise((resolve) => {
 		let child;
 		try {
-			// stdout 直接丢弃（**不能**设成 pipe 又不消费：管道写满后子进程会阻塞到超时，F5）。
-			// stderr 保留尾部若干字节用于报错。
-			child = spawn(cmd, args, { cwd, stdio: ["ignore", "ignore", "pipe"] });
+			// Windows 上 npm/pnpm 是 .cmd，必须经 shell 才能解析（见 tool-process.js）。
+			child = spawn(cmd, args, { cwd, stdio: ["ignore", "pipe", "pipe"], ...shellOptions(platform) });
 		} catch (e) {
-			resolve({ ok: false, error: String(e?.message ?? e) });
+			resolve({ ok: false, error: String(e?.message ?? e), exitCode: null, stdout: "", stderr: "" });
 			return;
 		}
-		const STDERR_CAP = 16 * 1024;
-		let stderr = "";
-		let timedOut = false;
-		const timer = setTimeout(() => {
-			timedOut = true;
-			try {
-				child.kill("SIGKILL");
-			} catch {
-				// 已经退出
+		const cap = Number.isSafeInteger(maxOutputBytes) && maxOutputBytes > 0 ? maxOutputBytes : 16 * 1024;
+		let stdout = Buffer.alloc(0), stderr = Buffer.alloc(0), timedOut = false, callbackFailed = false, settled = false;
+		const appendTail = (prior, chunk) => {
+			const next = Buffer.concat([prior, Buffer.from(chunk)]);
+			return next.length > cap ? next.subarray(next.length - cap) : next;
+		};
+		const onChunk = (stream, buffer) => {
+			if (stream === "stdout") stdout = appendTail(stdout, buffer);
+			else stderr = appendTail(stderr, buffer);
+			if (typeof onOutput === "function") {
+				try { onOutput(stream, Buffer.from(buffer).toString("utf8")); }
+				catch { callbackFailed = true; }
 			}
-		}, timeoutMs);
-		child.stderr?.on("data", (d) => {
-			stderr += d.toString();
-			if (stderr.length > STDERR_CAP) stderr = stderr.slice(-STDERR_CAP);
-		});
-		child.on("error", (e) => {
+		};
+		let timer;
+		const finish = (result) => {
+			if (settled) return;
+			settled = true;
 			clearTimeout(timer);
-			resolve({ ok: false, error: String(e?.message ?? e) });
-		});
+			resolve({ ...result, stdout: stdout.toString("utf8"), stderr: stderr.toString("utf8") });
+		};
+		timer = setTimeout(() => {
+			timedOut = true;
+			try { child.kill("SIGKILL"); } catch { /* already exited */ }
+		}, timeoutMs);
+		child.stdout?.on("data", chunk => onChunk("stdout", chunk));
+		child.stderr?.on("data", chunk => onChunk("stderr", chunk));
+		child.on("error", (e) => finish({ ok: false, error: String(e?.message ?? e), exitCode: null }));
 		child.on("close", (code) => {
-			clearTimeout(timer);
 			if (timedOut) {
-				resolve({ ok: false, error: `timeout-after-${Math.round(timeoutMs / 1000)}s${stderr ? `: ${stderr.trim()}` : ""}` });
+				finish({ ok: false, error: `timeout-after-${Math.round(timeoutMs / 1000)}s`, exitCode: code });
 				return;
 			}
-			resolve(code === 0 ? { ok: true } : { ok: false, error: (stderr || `exit ${code}`).trim() });
+			if (callbackFailed) {
+				finish({ ok: false, error: "output-capture-failed", exitCode: code });
+				return;
+			}
+			finish(code === 0
+				? { ok: true, exitCode: 0 }
+				: { ok: false, error: `exit-${code ?? "unknown"}`, exitCode: code });
 		});
 	});
 }
@@ -151,6 +167,24 @@ export function resolveManifestSource(configValue) {
 	return { kind: UPDATE_SOURCE_KIND.INVALID, value: v };
 }
 
+/** Resolve the fork's fixed NPM source; legacy source values migrate to NPM, only off disables. */
+export function resolvePluginUpdateSource(configValue) {
+	const value = typeof configValue === "string" ? configValue.trim() : "";
+	if (value === "off") return { kind: UPDATE_SOURCE_KIND.OFF };
+	if (value === "" || value === "npm" || value === "upstream" || /^https:\/\/\S+$/.test(value)) {
+		return { kind: UPDATE_SOURCE_KIND.NPM, migrated: value !== "" && value !== "npm" };
+	}
+	try {
+		const url = new URL(value);
+		if (url.protocol === "http:" && (url.hostname === "127.0.0.1" || url.hostname === "localhost") && url.pathname.startsWith("/")) {
+			return { kind: UPDATE_SOURCE_KIND.NPM, migrated: true };
+		}
+	} catch {
+		// invalid values are rejected below
+	}
+	return { kind: UPDATE_SOURCE_KIND.INVALID, value };
+}
+
 async function fetchJson(url, fetchImpl, userAgent, auth = {}) {
 	try {
 		const { response: res, finalUrl } = await fetchUpdateResource(url, { fetchImpl, ...auth,
@@ -301,7 +335,10 @@ export function planForShape(shape, { specifier = "", dirPath = "", canSelfUpdat
 
 /** 检查是否有新版（**不下载、不改动任何东西**）。 */
 export async function checkForUpdate({
-	configValue = "upstream",
+	configValue = "npm",
+	packageName = "",
+	npmPackageView = null,
+	npmCwd,
 	localVersion = "",
 	localContentSha256 = "",
 	fetchImpl = fetch,
@@ -310,38 +347,48 @@ export async function checkForUpdate({
 	auth = {},
 } = {}) {
 	const withCaps = (r) => (capabilities ? { ...r, ...capabilities } : r);
-	const source = resolveManifestSource(configValue);
+	// 检查日志（脱敏、限行长）：和手机端日志一样可展开/复制，避免“只给一个错误码”的黑盒。
+	const checkLog = [];
+	const finish = (result) => withCaps({
+		...result,
+		source: "npm",
+		checkedAt: new Date().toISOString(),
+		checkLog: checkLog.slice(-NPM_CHECK_LOG_LIMIT),
+	});
+	const source = resolvePluginUpdateSource(configValue);
 	if (source.kind === UPDATE_SOURCE_KIND.OFF) {
-		return withCaps({ state: UPDATE_CHECK_STATE.DISABLED, reason: "update-source-off", checkedAt: new Date().toISOString() });
+		return finish({ state: UPDATE_CHECK_STATE.DISABLED, reason: "update-source-off" });
 	}
 	if (source.kind === UPDATE_SOURCE_KIND.INVALID) {
-		return withCaps({
-			state: UPDATE_CHECK_STATE.UNAVAILABLE,
-			reason: "update-source-invalid",
-			source: String(source.value ?? ""),
-			checkedAt: new Date().toISOString(),
-		});
+		checkLog.push("更新来源配置无效（应固定为宿主 npm registry）");
+		return finish({ state: UPDATE_CHECK_STATE.UNAVAILABLE, reason: "update-source-invalid" });
+	}
+	const view = npmPackageView ?? createNpmPackageView({ packageName, cwd: npmCwd });
+	const resolved = await resolveNpmUpdateCandidate({ packageName, localVersion, packageView: view, log: checkLog });
+	if (!resolved.ok) {
+		checkLog.push(`检查失败：${resolved.reason}`);
+		return finish({ state: UPDATE_CHECK_STATE.UNAVAILABLE, reason: resolved.reason });
 	}
-	const fetched = await fetchReleaseManifest({ source, fetchImpl, userAgent, auth });
-	if (!fetched.ok) {
-		return withCaps({ state: UPDATE_CHECK_STATE.UNAVAILABLE, reason: fetched.error, source: source.kind, checkedAt: new Date().toISOString() });
+	const remote = { version: resolved.plugin.version, contentSha256: resolved.plugin.contentSha256 || "" };
+	const decision = decidePluginUpdate({ localVersion, localContentSha256, remote });
+	// NPM versions are immutable. Never turn a same-version content mutation into an update.
+	if (decision.reason === "content-differs-same-version") {
+		checkLog.push(`检查失败：${remote.version} 内容标识与已安装内容不一致（不可变版本不得覆盖）`);
+		return finish({ state: UPDATE_CHECK_STATE.UNAVAILABLE, reason: "npm-version-content-mismatch" });
 	}
-	const decision = decidePluginUpdate({ localVersion, localContentSha256, remote: fetched.manifest.plugin });
-	return withCaps({
+	checkLog.push(`结论：${decision.action}（${decision.reason}）`);
+	return finish({
 		state: decision.action,
 		reason: decision.reason,
-		source: source.kind,
-		synthesized: Boolean(fetched.synthesized),
-		manifestUrl: fetched.manifestUrl ?? "",
-		release: fixedReleaseSnapshot(fetched.manifest, fetched.manifestUrl),
+		candidate: resolved,
 		remote: {
-			version: fetched.manifest.plugin.version,
-			contentSha256: fetched.manifest.plugin.contentSha256 || "",
-			sha256: fetched.manifest.plugin.sha256 || "",
-			size: fetched.manifest.plugin.size ?? null,
-			url: resolvePluginUrl(fetched.manifestUrl ?? "", fetched.manifest.plugin),
+			version: resolved.plugin.version,
+			contentSha256: resolved.plugin.contentSha256 || "",
+			integrity: resolved.plugin.integrity,
+			carrierVersion: resolved.carrier.version,
+			appVersion: resolved.carrier.appVersion,
+			legacyCarrierMetadata: resolved.carrier.legacyMetadataMissing,
 		},
-		checkedAt: new Date().toISOString(),
 	});
 }
 
@@ -405,8 +452,41 @@ export function defaultRunTar(tgzPath, destDir) {
 }
 
 /** 默认安装器：包管理器（异步、带超时）。 */
-export function defaultRunInstall(profileDir) {
-	return runCommand("pnpm", ["install"], { cwd: profileDir });
+export function defaultRunInstall(profileDir, { onOutput, platform = process.platform } = {}) {
+	return runCommand("pnpm", ["install"], { cwd: profileDir, onOutput, platform });
+}
+
+async function fileIntegrity(file, algorithm = "sha512") {
+	const digest = createHash(algorithm);
+	for await (const chunk of createReadStream(file)) digest.update(chunk);
+	return `${algorithm}-${digest.digest("base64")}`;
+}
+
+/** Pack an exact NPM version through the host npm config and verify its immutable SRI. */
+export async function packNpmTarball({ packageName, version, expectedIntegrity, destDir, cwd, run = runCommand, platform = process.platform } = {}) {
+	if (!packageName || !version || !expectedIntegrity || !destDir) return { ok: false, error: "npm-pack-input-invalid" };
+	mkdirSync(destDir, { recursive: true });
+	// Windows shell 下含空白的临时目录必须引用，否则会被拆成多个参数。
+	const result = await run("npm", ["pack", "--json", "--ignore-scripts", "--pack-destination", quoteShellArgument(destDir, platform), `${packageName}@${version}`], {
+		cwd, timeoutMs: 120_000, maxOutputBytes: 256 * 1024, ...shellOptions(platform),
+	});
+	if (!result?.ok) return { ok: false, error: "npm-pack-failed" };
+	let entries;
+	try { entries = JSON.parse(result.stdout); } catch { return { ok: false, error: "npm-pack-json-invalid" }; }
+	const entry = Array.isArray(entries) && entries.length === 1 ? entries[0] : null;
+	if (!entry || entry.name !== packageName || entry.version !== version || entry.integrity !== expectedIntegrity) {
+		return { ok: false, error: "npm-pack-metadata-mismatch" };
+	}
+	const filename = typeof entry.filename === "string" ? basename(entry.filename) : "";
+	if (filename === "" || !filename.endsWith(".tgz")) return { ok: false, error: "npm-pack-filename-invalid" };
+	const file = join(destDir, filename);
+	try {
+		if (!statSync(file).isFile()) return { ok: false, error: "npm-pack-tarball-missing" };
+	} catch { return { ok: false, error: "npm-pack-tarball-missing" }; }
+	let actualIntegrity;
+	try { actualIntegrity = await fileIntegrity(file); } catch { return { ok: false, error: "npm-pack-tarball-unreadable" }; }
+	if (actualIntegrity !== expectedIntegrity) return { ok: false, error: "npm-pack-integrity-mismatch" };
+	return { ok: true, file, filename, integrity: actualIntegrity, size: statSync(file).size };
 }
 
 /**
@@ -428,6 +508,103 @@ export async function extractVerified({ tgzPath, workDir, contentSha256, runTar
 	return { ok: true, digest, packageDir };
 }
 
+async function fileSha256(file) {
+	const digest = createHash("sha256");
+	for await (const chunk of createReadStream(file)) digest.update(chunk);
+	return digest.digest("hex");
+}
+
+async function safeTarListing(tarball, run = runCommand) {
+	const listing = await run("tar", ["-tzf", tarball], { timeoutMs: 30_000, maxOutputBytes: 256 * 1024 });
+	if (!listing?.ok) return { ok: false, error: "npm-tar-list-failed" };
+	const entries = listing.stdout.split(/\r?\n/).filter(Boolean);
+	if (entries.length === 0 || entries.length > 2048) return { ok: false, error: "npm-tar-list-invalid" };
+	for (const entry of entries) {
+		const normalized = entry.replace(/\\/g, "/");
+		if (normalized.startsWith("/") || normalized.split("/").includes("..") || (normalized !== "package" && !normalized.startsWith("package/"))) {
+			return { ok: false, error: "npm-tar-path-invalid" };
+		}
+	}
+	return { ok: true };
+}
+
+/** Download and validate the exact NPM pair before touching the profile. */
+export async function prepareNpmArtifacts({ npmCandidate, packageName, profileDir, workDir, runCommandImpl = runCommand, runTar = defaultRunTar } = {}) {
+	const name = packageName || npmCandidate?.plugin?.name || "";
+	if (!npmCandidate?.plugin?.version || !npmCandidate?.carrier?.version || !name || !profileDir || !workDir) {
+		return { ok: false, error: "npm-candidate-incomplete" };
+	}
+	const pluginPackDir = join(workDir, "npm-plugin");
+	const carrierPackDir = join(workDir, "npm-carrier");
+	const plugin = await packNpmTarball({ packageName: name, version: npmCandidate.plugin.version,
+		expectedIntegrity: npmCandidate.plugin.integrity, destDir: pluginPackDir, cwd: profileDir, run: runCommandImpl });
+	if (!plugin.ok) return plugin;
+	const carrier = await packNpmTarball({ packageName: name, version: npmCandidate.carrier.version,
+		expectedIntegrity: npmCandidate.carrier.integrity, destDir: carrierPackDir, cwd: profileDir, run: runCommandImpl });
+	if (!carrier.ok) return carrier;
+
+	const pluginListing = await safeTarListing(plugin.file, runCommandImpl);
+	if (!pluginListing.ok) return pluginListing;
+	const carrierListing = await safeTarListing(carrier.file, runCommandImpl);
+	if (!carrierListing.ok) return carrierListing;
+	const pluginExtract = await extractVerified({ tgzPath: plugin.file, workDir: join(workDir, "plugin-extract"),
+		contentSha256: npmCandidate.plugin.contentSha256 || "", runTar });
+	if (!pluginExtract.ok) return { ok: false, error: `npm-plugin-${pluginExtract.error}` };
+	const carrierExtractDir = join(workDir, "carrier-extract");
+	rmSync(carrierExtractDir, { recursive: true, force: true });
+	mkdirSync(carrierExtractDir, { recursive: true });
+	const carrierUnpack = await runTar(carrier.file, carrierExtractDir);
+	if (!carrierUnpack?.ok) return { ok: false, error: "npm-carrier-extract-failed" };
+	const carrierPackageDir = join(carrierExtractDir, "package");
+	let manifest;
+	try { manifest = JSON.parse(readFileSync(join(carrierPackageDir, "manifest.json"), "utf8")); }
+	catch { return { ok: false, error: "npm-carrier-manifest-unreadable" }; }
+	// npm pack 会把 tarball 名规范化（加 scope 前缀、去掉发布产物里的 `-v`），
+	// 因此不能拿 manifest.plugin.file 与下载文件名逐字比较；身份由版本、大小与
+	// 后续 sha256/contentSha256 校验共同钉死。
+	if (manifest?.schema !== 1 || manifest?.plugin?.version !== npmCandidate.plugin.version
+		|| manifest?.plugin?.size !== plugin.size) {
+		return { ok: false, error: "npm-carrier-plugin-identity-mismatch" };
+	}
+	let tarballSha256;
+	try { tarballSha256 = await fileSha256(plugin.file); } catch { return { ok: false, error: "npm-plugin-tarball-unreadable" }; }
+	if (manifest.plugin.sha256 !== tarballSha256) return { ok: false, error: "npm-plugin-tarball-sha256-mismatch" };
+	const pluginContentSha256 = pluginExtract.digest;
+	if (manifest.plugin.contentSha256 !== pluginContentSha256) return { ok: false, error: "npm-plugin-content-sha256-mismatch" };
+	if (npmCandidate.plugin.contentSha256 && npmCandidate.plugin.contentSha256 !== pluginContentSha256) {
+		return { ok: false, error: "npm-packument-content-sha256-mismatch" };
+	}
+	if (npmCandidate.carrier.appVersion && npmCandidate.carrier.appVersion !== manifest.app?.version) {
+		return { ok: false, error: "npm-packument-app-version-mismatch" };
+	}
+	if (npmCandidate.carrier.pluginContentSha256 && npmCandidate.carrier.pluginContentSha256 !== manifest.plugin.contentSha256) {
+		return { ok: false, error: "npm-packument-content-sha256-mismatch" };
+	}
+
+	const alias = appCarrierAlias(name);
+	const link = join(pluginExtract.packageDir, "node_modules", alias);
+	try {
+		mkdirSync(dirname(link), { recursive: true });
+		symlinkSync(carrierPackageDir, link, "dir");
+	} catch { return { ok: false, error: "npm-carrier-link-failed" }; }
+	const inspected = discoverAppCarrier({ pluginRoot: pluginExtract.packageDir, dshHome: join(workDir, "isolated-dsh") });
+	if (!inspected.ok || inspected.pluginContent?.matches !== true) {
+		return { ok: false, error: inspected.reason || "npm-carrier-validation-failed" };
+	}
+	return {
+		ok: true,
+		workDir,
+		pluginTgzPath: plugin.file,
+		carrierTgzPath: carrier.file,
+		pluginPackageDir: pluginExtract.packageDir,
+		carrierPackageDir,
+		pluginContentSha256,
+		pluginTarballSha256: tarballSha256,
+		carrierAppVersion: inspected.manifest.appVersion,
+		manifest,
+	};
+}
+
 /** 把解包好的版本目录记进 profile 的依赖声明（持久生效的关键，见 ADR 0019）。 */
 export function switchDependencySpecifier({ profileDir, nextSpecifier, keys = [LEGACY_DEPENDENCY_KEY], readJson = readJsonFile, writeJson = writeJsonFile } = {}) {
 	const file = join(profileDir, "package.json");
@@ -623,11 +800,12 @@ export async function waitForSupervisorReady({
  * 由调用方启动外部监督器接管（重启 + 健康确认 + 失败回滚）。
  */
 export async function runSelfUpdate({
-  home, plugin, release = null, manifestUrl = "", profileDir, restartForm = "unsupported", hostPid = process.pid,
+  home, plugin, release = null, npmCandidate = null, packageName = "", manifestUrl = "", profileDir, restartForm = "unsupported", hostPid = process.pid,
   port = 3080, basePath = "/m", token = "", profile = "web", dshCommand = "dsh", installedRoot = "", pluginRoot = "",
   needsEscape = false, supervisorTimeoutMs = 15_000, freezeImpl = freezeSupervisor, spawnArmedImpl = spawnSupervisorArmed,
   awaitReadyImpl = waitForSupervisorReady, opId = newOperationId(), fetchImpl = fetch, auth = {}, runTar = defaultRunTar,
-  runInstall = defaultRunInstall, onStep = () => {}, log = () => {}, now = () => Date.now(),
+  runInstall = defaultRunInstall, onStep = () => {}, onOutput = () => {}, prepareNpmArtifactsImpl = prepareNpmArtifacts,
+  preparedNpmArtifacts = null, log = () => {}, now = () => Date.now(),
   lease: admittedLease, initialTransaction, stateFile: operationStateFile, currentFile = transactionFile(home),
   lockPath = updateLockPath(home),
 } = {}) {
@@ -638,11 +816,14 @@ export async function runSelfUpdate({
   const lease = grant.lease, id = lease.generation;
   const stateFile = operationStateFile || serverOperationPath(home, id);
   let tx = initialTransaction ?? { opId, lease, id, phase: "staging", startedAt: new Date(now()).toISOString(),
-    profileDir, installedRoot, manifestUrl, release, restartForm, hostPid, port, basePath, token, profile, dshCommand,
+    profileDir, installedRoot, manifestUrl, release, npmCandidate, restartForm, hostPid, port, basePath, token, profile, dshCommand,
     lockPath, currentFile, targetVersion: plugin?.version ?? "", targetContentSha256: plugin?.contentSha256 ?? "", attempts: 0 };
-  let destructive = false, step = "supervisor";
+  let destructive = false, step = "supervisor", npmWorkDir = "";
   const save = (patch, expectedPhases) => { tx = writeOwnedTransaction(stateFile, { ...tx, ...patch }, { lockPath, lease, currentFile, expectedPhases }); return tx; };
   const fail = error => {
+    if (npmCandidate && npmWorkDir) {
+      try { rmSync(npmWorkDir, { recursive: true, force: true }); } catch { /* recovery snapshot is independent of NPM scratch */ }
+    }
     // 一旦可能动过 profile/安装字节，只有已 armed 的监督器能结束这个事务（C5）。
     if (destructive) {
       save({ phase: "rolling-back", rolledBack: true, result: { ok: false, reason: error }, recoveryCause: error }, ["installing"]);
@@ -666,19 +847,39 @@ export async function runSelfUpdate({
     assertUpdateLease(lockPath, lease);
 
     const work = join(workRoot(home), id); mkdirSync(work, { recursive: true });
-    const tgzPath = join(work, "plugin.tgz"); step = UPDATE_STEP.DOWNLOAD; onStep(step);
-    const downloaded = await downloadVerified({ url: resolvePluginUrl(manifestUrl, plugin), destPath: tgzPath,
-      sha256: plugin.sha256, size: plugin.size ?? null, fetchImpl, auth });
-    assertUpdateLease(lockPath, lease);
-    if (!downloaded.ok) return fail(downloaded.error);
-    onStep(UPDATE_STEP.VERIFY); step = UPDATE_STEP.EXTRACT; onStep(step);
-    const staged = await extractVerified({ tgzPath, workDir: join(work, "extract"), contentSha256: plugin.contentSha256, runTar });
-    assertUpdateLease(lockPath, lease);
-    if (!staged.ok) return fail(staged.error);
+    if (npmCandidate && !preparedNpmArtifacts) npmWorkDir = work;
+    let staged, npmPrepared = null;
+    step = UPDATE_STEP.DOWNLOAD; onStep(step);
+    if (npmCandidate) {
+      if (npmCandidate.carrier?.legacyMetadataMissing && !preparedNpmArtifacts) return fail("legacy-carrier-preparation-required");
+      npmPrepared = preparedNpmArtifacts ?? await prepareNpmArtifactsImpl({ npmCandidate, packageName: packageName || npmCandidate.plugin?.name,
+        profileDir, workDir: work, runCommandImpl: runCommand, runTar });
+      assertUpdateLease(lockPath, lease);
+      if (!npmPrepared?.ok) return fail(npmPrepared?.error ?? "npm-artifact-preparation-failed");
+      if (npmPrepared.manifest?.plugin?.version !== npmCandidate.plugin.version
+        || npmPrepared.manifest?.plugin?.contentSha256 !== npmPrepared.pluginContentSha256
+        || npmPrepared.manifest?.app?.version !== npmPrepared.carrierAppVersion) return fail("npm-prepared-candidate-mismatch");
+      staged = { ok: true, digest: npmPrepared.pluginContentSha256, packageDir: npmPrepared.pluginPackageDir };
+    } else {
+      const tgzPath = join(work, "plugin.tgz");
+      const downloaded = await downloadVerified({ url: resolvePluginUrl(manifestUrl, plugin), destPath: tgzPath,
+        sha256: plugin.sha256, size: plugin.size ?? null, fetchImpl, auth });
+      assertUpdateLease(lockPath, lease);
+      if (!downloaded.ok) return fail(downloaded.error);
+      onStep(UPDATE_STEP.VERIFY); step = UPDATE_STEP.EXTRACT; onStep(step);
+      staged = await extractVerified({ tgzPath, workDir: join(work, "extract"), contentSha256: plugin.contentSha256, runTar });
+      assertUpdateLease(lockPath, lease);
+      if (!staged.ok) return fail(staged.error);
+    }
+    if (!staged?.digest || !staged.packageDir) return fail("staged-plugin-invalid");
     const destDir = artifactDir(artifactRoot(home), staged.digest);
     if (existsSync(destDir)) {
       if (pluginContentDigest(destDir) !== staged.digest) return fail("artifact-integrity-mismatch");
-    } else { mkdirSync(dirname(destDir), { recursive: true }); renameSync(staged.packageDir, destDir); }
+    } else {
+      mkdirSync(dirname(destDir), { recursive: true });
+      if (npmCandidate) rmSync(join(staged.packageDir, "node_modules"), { recursive: true, force: true });
+      renameSync(staged.packageDir, destDir);
+    }
 
     step = UPDATE_STEP.SNAPSHOT; onStep(step);
     if (!installedRoot || !existsSync(installedRoot)) return fail("installed-root-missing");
@@ -696,18 +897,56 @@ export async function runSelfUpdate({
     const dependencyKeys = dependencyKeysFor(pluginRoot);
     const dependencyKey = dependencyKeyIn(JSON.parse(packageFile), dependencyKeys) || LEGACY_DEPENDENCY_KEY;
     const oldSpecifier = JSON.parse(packageFile).dependencies?.[dependencyKey];
+    const npmPackageName = npmCandidate?.plugin?.name || packageName;
+    const targetAppVersion = npmPrepared?.carrierAppVersion || npmPrepared?.manifest?.app?.version || npmCandidate?.carrier?.appVersion || null;
+    const resolvedNpmCandidate = npmCandidate ? {
+      ...npmCandidate,
+      plugin: { ...npmCandidate.plugin, contentSha256: staged.digest },
+      carrier: { ...npmCandidate.carrier, appVersion: targetAppVersion,
+        pluginContentSha256: staged.digest, legacyMetadataMissing: false },
+    } : null;
     // Durable recovery metadata precedes the first destructive write, so crashes also recover.
-    save({ phase: "installing", artifactDir: destDir, targetContentSha256: staged.digest, previousContentSha256: previousContent,
-      previousSnapshotDir: previousSnapshot, previousSpecifier: oldSpecifier, dependencyKey,
-      profileSnapshot: { packageJson: packageFile, pnpmLock, dependencyKey },
+    save({ phase: "installing", artifactDir: destDir, targetContentSha256: staged.digest, targetAppVersion,
+      previousContentSha256: previousContent, previousSnapshotDir: previousSnapshot, previousSpecifier: oldSpecifier, dependencyKey,
+      profileSnapshot: { packageJson: packageFile, pnpmLock, dependencyKey }, npmCandidate: resolvedNpmCandidate,
       release: tx.release ? { ...tx.release, plugin: { ...tx.release.plugin, contentSha256: staged.digest } } : null }, ["staging"]);
     destructive = true; step = UPDATE_STEP.SWITCH; onStep(step);
-    const switched = switchOwnedDependency({ profileDir, nextSpecifier: `file:${destDir}`, key: dependencyKey, lockPath, lease });
+    const exactNpmSpecifier = npmCandidate
+      ? (dependencyKey === npmPackageName ? npmCandidate.plugin.version : `npm:${npmPackageName}@${npmCandidate.plugin.version}`)
+      : `file:${destDir}`;
+    const switched = switchOwnedDependency({ profileDir, nextSpecifier: exactNpmSpecifier, key: dependencyKey, lockPath, lease });
     if (!switched.ok) return fail(switched.error);
     step = UPDATE_STEP.INSTALL; onStep(step); assertUpdateLease(lockPath, lease);
-    const installed = await runInstall(profileDir);
+    const installed = await runInstall(profileDir, { onOutput });
     assertUpdateLease(lockPath, lease);
     if (!installed?.ok) return fail(installed?.error ?? "install-failed");
+    if (npmCandidate) {
+      const targetPath = join(profileDir, "node_modules", ...dependencyKey.split("/"));
+      let resolvedRoot;
+      try { resolvedRoot = realpathSync(targetPath); } catch { return fail("npm-installed-plugin-missing"); }
+      let installedPackage;
+      try { installedPackage = JSON.parse(readFileSync(join(resolvedRoot, "package.json"), "utf8")); }
+      catch { return fail("npm-installed-package-invalid"); }
+      if (installedPackage.name !== npmPackageName || installedPackage.version !== npmCandidate.plugin.version) return fail("npm-installed-package-identity-mismatch");
+      let installedDigest;
+      try { installedDigest = pluginContentDigest(resolvedRoot); } catch { return fail("npm-installed-content-unreadable"); }
+      if (installedDigest !== staged.digest) return fail("npm-installed-content-sha256-mismatch");
+      const installedCarrier = discoverAppCarrier({ pluginRoot: resolvedRoot, dshHome: join(home, ".dsh") });
+      if (!installedCarrier.ok || installedCarrier.pluginContent?.matches !== true) return fail(`npm-installed-carrier-invalid:${installedCarrier.reason ?? "content-mismatch"}`);
+      if (installedCarrier.carrier.version !== npmCandidate.carrier.version || installedCarrier.manifest.appVersion !== targetAppVersion) {
+        return fail("npm-installed-carrier-pairing-mismatch");
+      }
+      if (installedCarrier.manifest.pluginTgzSha256 !== npmPrepared.manifest.plugin.sha256
+        || installedCarrier.manifest.contentSha256 !== staged.digest
+        || installedCarrier.apk.sha256 !== npmPrepared.manifest.app?.sha256
+        || installedCarrier.apk.size !== npmPrepared.manifest.app?.size) {
+        return fail("npm-installed-carrier-integrity-mismatch");
+      }
+    }
+    if (npmCandidate) {
+      // The package-manager install is complete; discard its NPM tarball/extraction scratch before restart.
+      try { rmSync(work, { recursive: true, force: true }); } catch { /* cleanup cannot invalidate an installed package */ }
+    }
     step = UPDATE_STEP.RESTART; onStep(step);
     save({ phase: "restart-pending", installedAt: new Date(now()).toISOString(), result: null }, ["installing"]);
     log(`mobile-remote: 已落位，监督器将确认内容 ${staged.digest.slice(0,12)}`);