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

package/lib/plugin-update-controller.js

@@ -1,8 +1,12 @@
 // Admission owns the durable transaction and its lease; the worker consumes exactly the accepted release.
 import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, realpathSync, rmSync, statSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { acquireLock, newOperationId, readTransaction, releaseLock, serverOperationPath, finishOwnedTerminal,
-  transactionFile, updateLockPath, validOperationId, writeOwnedTransaction, convergeStaleTransaction } from './plugin-update-transaction.js';
-import { checkForUpdate, runSelfUpdate, isTerminalPhase, resolveManifestSource, UPDATE_SOURCE_KIND } from './plugin-self-update.js';
+  transactionFile, updateLockPath, validOperationId, writeOwnedTransaction, convergeStaleTransaction, workRoot } from './plugin-update-transaction.js';
+import { checkForUpdate, prepareNpmArtifacts, runSelfUpdate, isTerminalPhase, resolvePluginUpdateSource, UPDATE_SOURCE_KIND } from './plugin-self-update.js';
+import { createOperationLog } from './plugin-update-log.js';
 
 /// 客户端可达视图：只改写属于**本机回环主机源**的 artifact 路由，外部发布源保持原样（F1）。
 export function clientReleaseView(release, { clientOrigin = '', basePath = '/m', loopback = false } = {}) {
@@ -15,28 +19,144 @@ export function clientReleaseView(release, { clientOrigin = '', basePath = '/m',
     plugin: { ...release.plugin, url: `${clientOrigin}${mount}/api/update/plugin` },
   };
 }
+function safeUpdateReason(reason) {
+  const value = typeof reason === 'string' ? reason : '';
+  return /^[a-z0-9][a-z0-9._-]{0,96}$/i.test(value) ? value : 'update-failed';
+}
+
 export function publicTransaction(tx, view = {}) {
   if (!tx) return null;
-  const { opId, phase, targetVersion, targetContentSha256, rolledBack, attempts, result, startedAt, release } = tx;
-  return { opId, phase, targetVersion, targetContentSha256, rolledBack: !!rolledBack, attempts: attempts ?? 0, result: result ?? null, startedAt,
+  const { opId, phase, targetVersion, targetContentSha256, targetAppVersion, rolledBack, attempts, result, startedAt, release } = tx;
+  const publicResult = result ? {
+    ok: !!result.ok,
+    ...(result.reason ? { reason: safeUpdateReason(result.reason) } : {}),
+    ...(result.at ? { at: result.at } : {}),
+    ...(result.matched ? { matched: result.matched } : {}),
+  } : null;
+  return { opId, phase, targetVersion, targetContentSha256, targetAppVersion: targetAppVersion ?? null,
+    rolledBack: !!rolledBack, attempts: attempts ?? 0, result: publicResult, startedAt,
     release: release ? clientReleaseView(release, view) : null };
 }
 export function createPluginUpdateController(options) {
-  const { home = homedir(), configValue, profileDir, capabilities, localVersion, localContentSha256,
+  const { home = homedir(), configValue, profileDir, packageName = '', npmPackageView, capabilities, localVersion, localContentSha256,
     status, log = () => {}, fetchImpl = fetch, auth = {}, basePath = '/m', workerOptions = {},
-    schedule = fn => setImmediate(fn), runSelfUpdate: runner = runSelfUpdate, persist = writeOwnedTransaction } = options;
+    schedule = fn => setImmediate(fn), runSelfUpdate: runner = runSelfUpdate, prepareNpmArtifacts: prepareRunner = prepareNpmArtifacts,
+    persist = writeOwnedTransaction } = options;
   const currentFile = transactionFile(home), lockPath = updateLockPath(home);
-  const checking = () => checkForUpdate({ configValue, localVersion: typeof localVersion === 'function' ? localVersion() : localVersion, localContentSha256,
+  const preparedUpdates = new Map();
+  const preparedTtlMs = 30 * 60 * 1000;
+  const safePreparedWorkRoot = resolve(workRoot(home));
+  const removePreparedWorkDir = workDir => {
+    if (!workDir || !existsSync(safePreparedWorkRoot)) return false;
+    try {
+      const rootReal = realpathSync(safePreparedWorkRoot);
+      const targetReal = realpathSync(workDir);
+      const rel = relative(rootReal, targetReal);
+      if (rel === '' || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return false;
+      rmSync(targetReal, { recursive: true, force: true });
+      return true;
+    } catch { return false; }
+  };
+  const cleanupPreparedUpdates = () => {
+    const now = Date.now();
+    for (const [key, entry] of preparedUpdates) {
+      if (entry.expiresAt <= now) {
+        clearTimeout(entry.expireTimer);
+        removePreparedWorkDir(entry.workDir);
+        preparedUpdates.delete(key);
+      }
+    }
+    try {
+      if (!existsSync(safePreparedWorkRoot)) return;
+      const rootReal = realpathSync(safePreparedWorkRoot);
+      const active = new Set([...preparedUpdates.values()].map(entry => resolve(entry.workDir)));
+      const activeTransaction = readTransaction(currentFile);
+      const activePreparedDir = activeTransaction && !isTerminalPhase(activeTransaction.phase) && activeTransaction.preparedId
+        ? `prepare-${activeTransaction.preparedId}` : "";
+      for (const item of readdirSync(rootReal, { withFileTypes: true })) {
+        if (!item.isDirectory() || !item.name.startsWith('prepare-') || item.name === activePreparedDir) continue;
+        const target = join(rootReal, item.name);
+        if (active.has(resolve(target))) continue;
+        if (now - statSync(target).mtimeMs > preparedTtlMs) removePreparedWorkDir(target);
+      }
+    } catch { /* cleanup is best-effort; never disrupt update checks */ }
+  };
+  cleanupPreparedUpdates();
+  const checking = () => checkForUpdate({ configValue, packageName, npmCwd: profileDir, npmPackageView,
+    localVersion: typeof localVersion === 'function' ? localVersion() : localVersion, localContentSha256,
     capabilities: capabilities(), fetchImpl, auth });
   /// 手机视图：**只用于 HTTP 出口**，绝不写回内部事务（F1）。
-  /// 内部 worker 必须继续用回环 locator 读受保护产物；手机看到的是自己可达的路由。
+  /// 内部 worker 必须继续用受信定位；当前 NPM 来源不会把 registry URL 投影给客户端。
   const clientView = clientOrigin => ({
-    clientOrigin, basePath, loopback: resolveManifestSource(configValue).loopback === true,
+    clientOrigin, basePath, loopback: resolvePluginUpdateSource(configValue).loopback === true,
   });
+  async function prepare(body = {}) {
+    if (!body || typeof body !== 'object' || Array.isArray(body) || ('opId' in body && !validOperationId(body.opId))) {
+      return { status: 400, body: { error: 'invalid-operation-id' } };
+    }
+    const source = resolvePluginUpdateSource(configValue);
+    if (source.kind === UPDATE_SOURCE_KIND.OFF) return { status: 503, body: { error: 'update-source-off' } };
+    if (source.kind === UPDATE_SOURCE_KIND.INVALID) return { status: 400, body: { error: 'update-source-invalid' } };
+    if (!profileDir) return { status: 409, body: { error: 'profile-not-found' } };
+    if (!capabilities().canSelfUpdate) return { status: 409, body: { error: 'restart-unsupported' } };
+    const opId = body.opId ?? newOperationId();
+    cleanupPreparedUpdates();
+    const current = preparedUpdates.get(opId);
+    if (current && current.expiresAt > Date.now()) return { status: 200, body: {
+      ok: true, action: 'prepared', opId, prepareId: current.prepareId, candidate: current.candidate,
+    } };
+    const old = readTransaction(currentFile);
+    if (old && !isTerminalPhase(old.phase)) return { status: 409, body: { error: 'update-busy', transaction: publicTransaction(old) } };
+    const checked = await checking(); Object.assign(status, checked);
+    if (checked.state !== 'update-available') return { status: 200, body: { ok: true, action: 'none', check: checked } };
+    const candidate = checked.candidate;
+    if (!candidate?.carrier?.legacyMetadataMissing) {
+      return { status: 200, body: { ok: true, action: 'confirmation-required', opId, candidate, check: checked } };
+    }
+    const prepareId = newOperationId();
+    const workDir = join(safePreparedWorkRoot, `prepare-${prepareId}`);
+    mkdirSync(workDir, { recursive: true, mode: 0o700 });
+    let artifacts;
+    try {
+      artifacts = await prepareRunner({ npmCandidate: candidate, packageName, profileDir, workDir });
+      if (!artifacts?.ok || !artifacts.carrierAppVersion || !artifacts.pluginContentSha256) {
+        removePreparedWorkDir(workDir);
+        return { status: 502, body: { error: 'candidate-preparation-failed', reason: artifacts?.error ?? 'npm-preparation-incomplete' } };
+      }
+    } catch {
+      removePreparedWorkDir(workDir);
+      return { status: 502, body: { error: 'candidate-preparation-failed', reason: 'npm-preparation-failed' } };
+    }
+    const preparedCandidate = {
+      ...candidate,
+      plugin: { ...candidate.plugin, contentSha256: artifacts.pluginContentSha256 },
+      carrier: { ...candidate.carrier, appVersion: artifacts.carrierAppVersion,
+        pluginContentSha256: artifacts.pluginContentSha256, legacyMetadataMissing: false },
+    };
+    const preparedCheck = {
+      ...checked,
+      candidate: preparedCandidate,
+      remote: { ...checked.remote, contentSha256: artifacts.pluginContentSha256,
+        appVersion: artifacts.carrierAppVersion, legacyCarrierMetadata: false },
+    };
+    const entry = { prepareId, opId, candidate: preparedCandidate, artifacts, workDir, expiresAt: Date.now() + preparedTtlMs };
+    entry.expireTimer = setTimeout(() => {
+      const current = preparedUpdates.get(opId);
+      if (current?.prepareId === prepareId) {
+        removePreparedWorkDir(current.workDir);
+        preparedUpdates.delete(opId);
+      }
+    }, preparedTtlMs);
+    entry.expireTimer.unref?.();
+    preparedUpdates.set(opId, entry);
+    Object.assign(status, preparedCheck);
+    return { status: 200, body: { ok: true, action: 'prepared', opId, prepareId, candidate: preparedCandidate, check: preparedCheck } };
+  }
   async function submit(body = {}, { clientOrigin = '' } = {}) {
     if (!body || typeof body !== 'object' || Array.isArray(body) ||
       ('opId' in body && !validOperationId(body.opId))) return { status: 400, body: { error: 'invalid-operation-id' } };
-    const source = resolveManifestSource(configValue);
+    if ('targetVersion' in body && typeof body.targetVersion !== 'string') return { status: 400, body: { error: 'invalid-target-version' } };
+    const source = resolvePluginUpdateSource(configValue);
     if (source.kind === UPDATE_SOURCE_KIND.OFF) return { status: 503, body: { error: 'update-source-off' } };
     if (source.kind === UPDATE_SOURCE_KIND.INVALID) return { status: 400, body: { error: 'update-source-invalid' } };
     if (!profileDir) return { status: 409, body: { error: 'profile-not-found' } };
@@ -56,40 +176,99 @@ export function createPluginUpdateController(options) {
       return { status: 200, body: { ok: true, action: 'none', check: { ...checked, release: clientReleaseView(checked.release, view) } } };
     }
     const opId = body.opId ?? newOperationId();
+    let effectiveCheck = checked;
+    let npmCandidate = checked.candidate ?? null;
+    let preparedNpmArtifacts = null;
+    if (npmCandidate?.carrier?.legacyMetadataMissing) {
+      cleanupPreparedUpdates();
+      const prepared = preparedUpdates.get(opId);
+      if (!prepared || prepared.expiresAt <= Date.now() || prepared.prepareId !== body.prepareId) {
+        return { status: 200, body: { ok: true, action: 'prepare-required', opId, check: checked } };
+      }
+      if (prepared.candidate.plugin.version !== npmCandidate.plugin.version
+        || prepared.candidate.carrier.version !== npmCandidate.carrier.version
+        || prepared.candidate.plugin.integrity !== npmCandidate.plugin.integrity
+        || prepared.candidate.carrier.integrity !== npmCandidate.carrier.integrity) {
+        return { status: 409, body: { error: 'prepared-candidate-stale', check: checked } };
+      }
+      npmCandidate = prepared.candidate;
+      preparedNpmArtifacts = prepared.artifacts;
+      effectiveCheck = { ...checked, candidate: npmCandidate,
+        remote: { ...checked.remote, contentSha256: npmCandidate.plugin.contentSha256,
+          appVersion: npmCandidate.carrier.appVersion, legacyCarrierMetadata: false } };
+      Object.assign(status, effectiveCheck);
+    } else if (body.prepareId) {
+      return { status: 409, body: { error: 'prepare-not-required', check: checked } };
+    }
+    const targetPlugin = checked.release?.plugin ?? npmCandidate?.plugin;
+    if (!targetPlugin?.version) return { status: 503, body: { error: 'update-candidate-incomplete' } };
+    if (typeof body.targetVersion === 'string' && body.targetVersion !== targetPlugin.version) {
+      return { status: 409, body: { error: 'candidate-changed', check: effectiveCheck } };
+    }
     const lock = acquireLock(lockPath, { opId, stateFile: currentFile });
     if (!lock.ok) return { status: 409, body: { error: lock.error, transaction: publicTransaction(readTransaction(currentFile)) } };
     const lease = lock.lease, stateFile = serverOperationPath(home, lease.generation);
+    const operationLog = createOperationLog({ home, generation: lease.generation,
+      redactPaths: [home, profileDir, workerOptions.pluginRoot, workerOptions.installedRoot] });
+    operationLog.setStage('staging', 'NPM plugin update accepted');
     let tx;
     try {
       tx = persist(stateFile, { ...workerOptions, opId, phase: 'staging', startedAt: new Date().toISOString(),
-        profileDir, release: checked.release, manifestUrl: checked.release.manifestUrl,
-        targetVersion: checked.release.plugin.version, targetContentSha256: checked.release.plugin.contentSha256,
+        profileDir, release: checked.release ?? null, npmCandidate,
+        manifestUrl: checked.release?.manifestUrl ?? '',
+        targetVersion: targetPlugin.version, targetContentSha256: targetPlugin.contentSha256 ?? '',
+        targetAppVersion: npmCandidate?.carrier?.appVersion ?? checked.release?.app?.version ?? null,
+        preparedId: body.prepareId ?? null,
         currentFile, lockPath, lease, attempts: 0 }, { lockPath, lease, currentFile });
     } catch(e) {
       releaseLock(lockPath, lease, { stateFile: currentFile });
-      log(`update admission persistence failed: ${e.message}`);
+      operationLog.setStage('failed', 'Could not persist update admission state.');
+      operationLog.flush();
+      log('plugin update admission state write failed');
       return { status: 500, body: { error: 'update-state-write-failed' } };
     }
+    // Consume the in-memory preflight only after the durable transaction accepts the same opId.
+    if (preparedNpmArtifacts) {
+      clearTimeout(preparedUpdates.get(opId)?.expireTimer);
+      preparedUpdates.delete(opId);
+    }
     // Only this lease schedules this worker. Same request retries return the saved operation above.
     schedule(async () => {
       try {
         const run = await runner({ ...workerOptions, home, profileDir, fetchImpl, auth, opId,
-          release: tx.release, plugin: tx.release.plugin, manifestUrl: tx.manifestUrl,
-          stateFile, currentFile, lockPath, lease, initialTransaction: tx, log });
-        if (run.ok) Object.assign(status, { state: 'restarting', reason: 'update-staged', opId });
-        else Object.assign(status, { state: run.transaction?.phase === 'rolling-back' ? 'rolling-back' : 'update-failed', reason: run.error, opId });
+          release: tx.release ?? null, npmCandidate: tx.npmCandidate ?? null, preparedNpmArtifacts,
+          plugin: tx.release?.plugin ?? tx.npmCandidate?.plugin, manifestUrl: tx.manifestUrl,
+          onStep: step => { operationLog.setStage(step); workerOptions.onStep?.(step); },
+          onOutput: (stream, text) => operationLog.appendChunk(stream, text),
+          stateFile, currentFile, lockPath, lease, initialTransaction: tx,
+          log: message => { operationLog.appendStatus(message, 'worker'); log('plugin update progress recorded'); } });
+        operationLog.flush();
+        if (run.ok) {
+          operationLog.setStage('restart', 'Plugin install finished; waiting for host restart and health confirmation.');
+          Object.assign(status, { state: 'restarting', reason: 'update-staged', opId });
+        } else {
+          const reason = safeUpdateReason(run.error);
+          // 失败原因必须进日志：详情页要能直接看到，而不是只有一句“看安装输出”。
+          operationLog.setStage('failed', `Plugin update failed: ${reason}`);
+          Object.assign(status, { state: run.transaction?.phase === 'rolling-back' ? 'rolling-back' : 'update-failed', reason, opId });
+        }
       } catch(e) {
         // Never clear an install/recovery lease as a generic catch. The armed supervisor owns recovery.
         const latest = readTransaction(stateFile);
+        const reason = safeUpdateReason(e.message);
         if (latest && latest.lease?.generation === lease.generation && latest.phase === 'staging') {
-          try { finishOwnedTerminal(stateFile, { phase: 'failed', result: { ok: false, reason: e.message }, expectedPhases: ['staging'] }, { lockPath, lease, currentFile }); }
+          try { finishOwnedTerminal(stateFile, { phase: 'failed', result: { ok: false, reason }, expectedPhases: ['staging'] }, { lockPath, lease, currentFile }); }
           catch { /* lost lease: do not overwrite a newer operation */ }
         }
-        Object.assign(status, { state: 'update-failed', reason: e.message, opId }); log(`update worker failed: ${e.message}`);
+        operationLog.setStage('failed', `Update worker failed: ${reason}`);
+        operationLog.flush();
+        Object.assign(status, { state: 'update-failed', reason, opId }); log('plugin update worker failed');
+      } finally {
+        if (preparedNpmArtifacts?.workDir) removePreparedWorkDir(preparedNpmArtifacts.workDir);
       }
     });
     return { status: 200, body: { ok: true, action: 'accepted', opId,
-      transaction: publicTransaction(tx, view), check: { ...checked, release: clientReleaseView(checked.release, view) } } };
+      transaction: publicTransaction(tx, view), check: { ...effectiveCheck, release: clientReleaseView(effectiveCheck.release, view) } } };
   }
-  return { submit, check: checking };
+  return { submit, check: checking, prepare };
 }

package/lib/plugin-update-log.js

@@ -0,0 +1,164 @@
+import { randomUUID } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
+import { serverOperationPath } from "./plugin-update-transaction.js";
+
+export const UPDATE_LOG_MAX_LINES = 400;
+export const UPDATE_LOG_MAX_BYTES = 128 * 1024;
+export const UPDATE_LOG_MAX_OPERATIONS = 20;
+const MAX_LINE_BYTES = 4096;
+const ANSI = /\u001b(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g;
+const SENSITIVE_KEY = /\b(_authToken|_auth|npm_config_[A-Za-z0-9_-]+|password|token|access_token|refresh_token|api[_-]?key|secret)\s*[:=]\s*([^\s&"']+)/gi;
+const URL_USERINFO = /(https?:\/\/)[^/\s@]+@/gi;
+const URL_SECRET_QUERY = /([?&](?:token|auth|password|key|secret|signature|access_token|refresh_token)=)[^&#\s]*/gi;
+
+function logPath(home, generation) {
+	return `${serverOperationPath(home, generation)}.log.jsonl`;
+}
+
+/** Keep the active/new log plus a bounded tail of completed operation logs. */
+export function pruneOperationLogs({ home, generation, maxOperations = UPDATE_LOG_MAX_OPERATIONS } = {}) {
+	const currentPath = logPath(home, generation);
+	const dir = dirname(currentPath);
+	if (!existsSync(dir)) return 0;
+	const limit = Number.isSafeInteger(maxOperations) && maxOperations > 0 ? maxOperations : UPDATE_LOG_MAX_OPERATIONS;
+	try {
+		const root = realpathSync(dir);
+		const currentName = basename(currentPath);
+		const logs = readdirSync(root, { withFileTypes: true })
+			.filter((entry) => entry.isFile() && /^[a-f0-9-]{36}\.json\.log\.jsonl$/.test(entry.name))
+			.map((entry) => ({ name: entry.name, mtime: statSync(join(root, entry.name)).mtimeMs }))
+			.sort((a, b) => b.mtime - a.mtime);
+		const keep = new Set([currentName, ...logs.map((item) => item.name).filter((name) => name !== currentName).slice(0, limit - 1)]);
+		let removed = 0;
+		for (const item of logs) {
+			if (keep.has(item.name)) continue;
+			const target = join(root, item.name);
+			const resolved = realpathSync(target);
+			const rel = relative(root, resolved);
+			if (rel !== item.name || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) continue;
+			rmSync(resolved, { force: true });
+			removed++;
+		}
+		return removed;
+	} catch {
+		return 0;
+	}
+}
+
+function readEvents(filePath) {
+	try {
+		return readFileSync(filePath, "utf8").split(/\r?\n/).filter(Boolean).map((line) => JSON.parse(line))
+			.filter((event) => Number.isSafeInteger(event?.seq) && typeof event?.text === "string");
+	} catch {
+		return [];
+	}
+}
+
+function sanitize(text, redactPaths = []) {
+	let value = String(text ?? "").replace(ANSI, "");
+	value = value.replace(/\b(authorization\s*:\s*)(?:basic|bearer)\s+[^\s]+/gi, "$1[REDACTED]");
+	value = value.replace(/\b(basic|bearer)\s+[^\s]+/gi, "$1 [REDACTED]");
+	value = value.replace(URL_USERINFO, "$1[REDACTED]@");
+	value = value.replace(URL_SECRET_QUERY, "$1[REDACTED]");
+	value = value.replace(SENSITIVE_KEY, "$1=[REDACTED]");
+	for (const path of [...redactPaths].filter((item) => typeof item === "string" && item !== "").sort((a, b) => b.length - a.length)) {
+		value = value.split(path).join("[host-path]");
+	}
+	if (Buffer.byteLength(value) > MAX_LINE_BYTES) {
+		let end = Math.min(value.length, MAX_LINE_BYTES);
+		while (end > 0 && Buffer.byteLength(value.slice(0, end)) > MAX_LINE_BYTES - 16) end -= 64;
+		value = `${value.slice(0, Math.max(0, end))}…[line truncated]`;
+	}
+	return value;
+}
+
+function persistEvents(filePath, events, { maxLines = UPDATE_LOG_MAX_LINES, maxBytes = UPDATE_LOG_MAX_BYTES } = {}) {
+	let kept = events.slice(-Math.max(1, maxLines));
+	const encoded = () => kept.map((event) => JSON.stringify(event)).join("\n") + (kept.length ? "\n" : "");
+	while (kept.length > 0 && Buffer.byteLength(encoded()) > maxBytes) kept = kept.slice(1);
+	mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+	const tmp = `${filePath}.${randomUUID()}.tmp`;
+	try {
+		writeFileSync(tmp, encoded(), { encoding: "utf8", mode: 0o600 });
+		renameSync(tmp, filePath);
+		try { chmodSync(filePath, 0o600); } catch { /* best-effort on platforms without POSIX modes */ }
+	} finally {
+		if (existsSync(tmp)) rmSync(tmp, { force: true });
+	}
+	return kept;
+}
+
+function appendEvents(filePath, items, options = {}) {
+	if (!Array.isArray(items) || items.length === 0) return readEvents(filePath);
+	const events = readEvents(filePath);
+	let seq = events.length ? events[events.length - 1].seq + 1 : 1;
+	const next = items.map((item) => ({
+		seq: seq++,
+		at: new Date().toISOString(),
+		stage: String(item.stage ?? "unknown"),
+		stream: item.stream === "stdout" || item.stream === "stderr" ? item.stream : "status",
+		text: sanitize(item.text, options.redactPaths),
+	}));
+	return persistEvents(filePath, [...events, ...next], options);
+}
+
+/** Create a bounded append/replay view keyed only by the server-generated operation generation. */
+export function createOperationLog({ home, generation, maxLines = UPDATE_LOG_MAX_LINES, maxBytes = UPDATE_LOG_MAX_BYTES,
+	maxOperations = UPDATE_LOG_MAX_OPERATIONS, redactPaths = [] } = {}) {
+	const filePath = logPath(home, generation);
+	mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+	if (!existsSync(filePath)) writeFileSync(filePath, "", { encoding: "utf8", mode: 0o600 });
+	pruneOperationLogs({ home, generation, maxOperations });
+	let stage = "staging";
+	const pending = { stdout: "", stderr: "" };
+	const options = { maxLines, maxBytes, redactPaths };
+	return {
+		filePath,
+		setStage(nextStage, text = "") {
+			stage = String(nextStage || "unknown");
+			return appendEvents(filePath, [{ stage, stream: "status", text: text || stage }], options);
+		},
+		appendStatus(text, stageOverride = stage) {
+			return appendEvents(filePath, [{ stage: stageOverride, stream: "status", text }], options);
+		},
+		appendChunk(stream, text) {
+			if (stream !== "stdout" && stream !== "stderr") return;
+			const merged = `${pending[stream]}${String(text ?? "")}`.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+			const lines = merged.split("\n");
+			pending[stream] = lines.pop() ?? "";
+			const items = lines.map((line) => ({ stage, stream, text: line }));
+			if (items.length) appendEvents(filePath, items, options);
+		},
+		flush() {
+			const items = [];
+			for (const stream of ["stdout", "stderr"]) {
+				if (pending[stream] !== "") items.push({ stage, stream, text: pending[stream] });
+				pending[stream] = "";
+			}
+			if (items.length) appendEvents(filePath, items, options);
+		},
+		read(afterSeq = 0) {
+			return readOperationLog({ home, generation, afterSeq, maxLines });
+		},
+	};
+}
+
+/** Append one sanitized status event from a separate supervisor process. */
+export function appendOperationLog({ home, generation, stage = "supervisor", stream = "status", text = "", maxLines = UPDATE_LOG_MAX_LINES, maxBytes = UPDATE_LOG_MAX_BYTES, redactPaths = [] } = {}) {
+	return appendEvents(logPath(home, generation), [{ stage, stream, text }], { maxLines, maxBytes, redactPaths });
+}
+
+/** Read only a bounded, sanitized page using a server-owned operation generation. */
+export function readOperationLog({ home, generation, afterSeq = 0, maxLines = UPDATE_LOG_MAX_LINES } = {}) {
+	const events = readEvents(logPath(home, generation));
+	const firstSeq = events[0]?.seq ?? 0;
+	const lastSeq = events.at(-1)?.seq ?? 0;
+	const cursor = Number.isSafeInteger(afterSeq) && afterSeq >= 0 ? afterSeq : 0;
+	return {
+		events: events.filter((event) => event.seq > cursor).slice(-Math.max(1, maxLines)),
+		firstSeq,
+		lastSeq,
+		truncated: firstSeq > 0 && (firstSeq > 1 || cursor > 0 && cursor < firstSeq - 1),
+	};
+}

package/lib/plugin-update-transaction.js

@@ -233,11 +233,11 @@ export function finishOwnedTerminal(stateFile, { phase, result, expectedPhases }
   if (!r.ok) throw new Error(r.error);
   return r.transaction;
 }
-export function restoreOwnedProfile({ profileDir, snapshotDir, snapshot, key, lockPath, lease } = {}) {
-  return arbitrate(lockPath, { operation: 'restore-profile', profileDir, snapshotDir, snapshot, key, lease });
+export function restoreOwnedProfile({ profileDir, snapshotDir, snapshot, key, preserveSpecifier = false, lockPath, lease } = {}) {
+  return arbitrate(lockPath, { operation: 'restore-profile', profileDir, snapshotDir, snapshot, key, preserveSpecifier, lease });
 }
-export function publishOwnedSnapshotLink({ profileDir, snapshotDir, lockPath, lease } = {}) {
-  return arbitrate(lockPath, { operation: 'publish-snapshot-link', profileDir, snapshotDir, lease });
+export function publishOwnedSnapshotLink({ profileDir, snapshotDir, key, lockPath, lease } = {}) {
+  return arbitrate(lockPath, { operation: 'publish-snapshot-link', profileDir, snapshotDir, key, lease });
 }
 export function validOperationId(opId) {
   return typeof opId === "string" && /^[A-Za-z0-9][A-Za-z0-9_-]{0,95}$/.test(opId);

package/lib/tool-process.js

@@ -0,0 +1,20 @@
+// 跨平台子进程调用辅助（issue #39 Windows 修复）。
+//
+// Windows 上 npm/pnpm 是 `npm.cmd`/`pnpm.cmd`：Node 在 `shell: false` 下用 CreateProcess
+// 无法解析 `.cmd`（只会自动补 `.exe`），直接 spawn 裸命令名会 ENOENT。因此在 win32 上
+// 必须经 shell 调用，并对含空白的参数（典型是 profile/临时目录路径）做 cmd 引用。
+//
+// 本模块保持零依赖，避免 npm-update-source ↔ plugin-self-update 的循环引用。
+
+/** 仅 Windows 需要 `shell: true`；POSIX 保持直接 spawn（更可控、无 shell 注入面）。 */
+export function shellOptions(platform = process.platform) {
+	return platform === "win32" ? { shell: true } : {};
+}
+
+/** Windows shell 下给含空白/元字符的参数加引号；POSIX 原样返回。 */
+export function quoteShellArgument(value, platform = process.platform) {
+	const text = String(value ?? "");
+	if (platform !== "win32" || text === "") return text;
+	if (!/[\s"&|<>^]/.test(text)) return text;
+	return `"${text.replace(/"/g, '""')}"`;
+}

package/lib/update-lock-arbiter.js

@@ -1,6 +1,6 @@
 // Runs only under an OS flock on a persistent inode. No lock-directory unlink/rename races.
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, rmSync, symlinkSync, realpathSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, isAbsolute, join, relative, sep } from 'node:path';
 import { randomUUID } from 'node:crypto';
 
 function read(file) { try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return null; } }
@@ -89,7 +89,12 @@ function execute(input) {
     const doc = input.snapshot?.packageJson ? JSON.parse(input.snapshot.packageJson) : read(file);
     if (!doc?.dependencies) throw new Error('profile-dependencies-missing');
     const key = input.key || 'dsh-mobile-remote';
-    doc.dependencies[key] = `file:${input.snapshotDir}`; atomic(file, doc);
+    if (input.preserveSpecifier === true) {
+      if (typeof doc.dependencies[key] !== 'string' || doc.dependencies[key] === '') throw new Error('profile-dependency-missing');
+    } else {
+      doc.dependencies[key] = `file:${input.snapshotDir}`;
+    }
+    atomic(file, doc);
     const lockfile = join(input.profileDir, 'pnpm-lock.yaml');
     if (typeof input.snapshot?.pnpmLock === 'string') writeFileSync(lockfile, input.snapshot.pnpmLock, { mode: 0o600 });
     else if (input.snapshot?.pnpmLock === null && existsSync(lockfile)) rmSync(lockfile);
@@ -100,7 +105,14 @@ function execute(input) {
     const modules = join(input.profileDir, 'node_modules'); mkdirSync(modules, { recursive: true });
     // Never traverse an unexpected node_modules symlink into another profile.
     if (realpathSync(modules) !== join(realpathSync(input.profileDir), 'node_modules')) throw new Error('profile-modules-outside-root');
-    const target = join(modules, 'dsh-mobile-remote');
+    const key = input.key || 'dsh-mobile-remote';
+    if (!/^(?:@[A-Za-z0-9._-]+\/)?[A-Za-z0-9._-]+$/.test(key)) throw new Error('dependency-key-invalid');
+    const segments = key.split('/');
+    const parent = join(modules, ...segments.slice(0, -1));
+    mkdirSync(parent, { recursive: true });
+    const relativeParent = relative(realpathSync(modules), realpathSync(parent));
+    if (relativeParent === '..' || relativeParent.startsWith(`..${sep}`) || isAbsolute(relativeParent)) throw new Error('profile-package-scope-outside-root');
+    const target = join(parent, segments.at(-1));
     const staged = `${target}.restore-${randomUUID()}`, previous = `${target}.previous-${randomUUID()}`;
     symlinkSync(realpathSync(input.snapshotDir), staged, 'dir');
     let moved = false;