grix-connector 4.0.2 → 4.2.0

package/scripts/upgrade-guardian.mjs

@@ -0,0 +1,1345 @@
+#!/usr/bin/env node
+// Cross-platform Node guardian used by the Windows service wrapper.
+// It is copied outside the npm package to <GRIX_HOME>/bin so an upgrade can
+// replace the active global package without replacing the running guardian.
+
+import {
+  copyFileSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { execFileSync, spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createServer } from 'node:net';
+import { homedir, uptime } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_NAME = 'grix-connector';
+const PACKAGE_BACKUP_SUFFIX = '.grix-upgrade-backup';
+const PACKAGE_FAILED_SUFFIX = '.grix-upgrade-failed';
+const RUNTIME_BACKUP_SUFFIX = '.grix-upgrade-backup';
+const RUNTIME_NEXT_SUFFIX = '.grix-upgrade-next';
+const NPM_PREFIX_UPGRADE_LOCK_FILE = '.grix-connector-upgrade.lock';
+const HEALTH_TIMEOUT_MS = 90_000;
+/** adopt-wrapper 等待旧 daemon 优雅退出的上限；超时也要把 wrapper 拉回来。 */
+const ADOPT_WRAPPER_DAEMON_EXIT_TIMEOUT_MS = 120_000;
+const HEALTH_POLL_MS = 2_000;
+const MONITOR_IDENTITY_GRACE_MS = 10_000;
+const TRANSACTION_PHASES = new Set([
+  'preparing',
+  'staged',
+  'handoff_ready',
+  'activating',
+  'verifying',
+  'healthy',
+  'rolling_back',
+  'rolled_back',
+  'finalizing',
+  'failed',
+]);
+const RENAME_RETRY_DELAYS_MS = [250, 750, 1_500, 3_000, 5_000];
+
+function pathsFor(rootDir) {
+  return {
+    pending: join(rootDir, 'data', 'upgrade-pending.json'),
+    pause: join(rootDir, 'data', 'upgrade-wrapper.pause.json'),
+    rollbackIntent: join(rootDir, 'data', 'upgrade-rollback.intent.json'),
+    lock: join(rootDir, 'upgrade-guardian.lock'),
+    log: join(rootDir, 'log', 'upgrade.log'),
+    healthPort: join(rootDir, 'data', 'health-port'),
+    daemonLock: join(rootDir, 'daemon.lock.json'),
+    daemonStatus: join(rootDir, 'daemon-status.json'),
+    wrapperChild: join(rootDir, 'data', 'upgrade-wrapper-child.json'),
+    monitorHeartbeat: join(rootDir, 'data', 'upgrade-monitor-heartbeat.json'),
+    installedGuardian: join(rootDir, 'bin', 'upgrade-guardian.mjs'),
+    fallbackGuardian: join(rootDir, 'bin', 'upgrade-guardian.fallback.mjs'),
+  };
+}
+
+function resolveManagedRuntimeDir(rootDir, env = process.env, userHome = homedir()) {
+  const localAppData = String(env.LOCALAPPDATA ?? '').trim();
+  const base = localAppData && isAbsolute(localAppData)
+    ? localAppData
+    : join(userHome, 'AppData', 'Local');
+  const serviceId = `GrixConnectorDaemon-${createHash('sha1')
+    .update(resolve(rootDir).trim() || 'default')
+    .digest('hex')
+    .slice(0, 12)}`;
+  return join(base, 'grix-connector', 'runtimes', serviceId);
+}
+
+function resolveTransactionRuntimeDir(rootDir, pending, deps = {}) {
+  if (deps.runtimeDir) return resolve(deps.runtimeDir);
+  if (!pending?.runtime_dir) return resolveManagedRuntimeDir(rootDir, deps.env, deps.homeDir);
+  const candidate = resolve(pending.runtime_dir);
+  const expectedServiceId = `GrixConnectorDaemon-${createHash('sha1')
+    .update(resolve(rootDir).trim() || 'default')
+    .digest('hex')
+    .slice(0, 12)}`;
+  if (
+    !isAbsolute(candidate)
+    || basename(candidate) !== expectedServiceId
+    || basename(dirname(candidate)) !== 'runtimes'
+    || basename(dirname(dirname(candidate))) !== 'grix-connector'
+  ) throw new Error(`unsafe recorded managed runtime path: ${candidate}`);
+  return candidate;
+}
+
+function sleep(ms) {
+  return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+}
+
+function readJson(file) {
+  // Windows PowerShell 5.1's default UTF-8 encoding emits a BOM. New launchers
+  // write without one, but accept records left by an older wrapper so rollback
+  // can still identify and terminate the exact child it launched.
+  return JSON.parse(readFileSync(file, 'utf8').replace(/^\uFEFF/, ''));
+}
+
+function writeJsonAtomic(file, value) {
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}`;
+  writeFileSync(tmp, JSON.stringify(value), 'utf8');
+  renameSync(tmp, file);
+}
+
+function readRollbackIntent(paths, transactionId) {
+  try {
+    const intent = readJson(paths.rollbackIntent);
+    return intent?.transaction_id === transactionId ? intent : null;
+  } catch {
+    return null;
+  }
+}
+
+function clearRollbackIntent(paths, transactionId) {
+  if (!readRollbackIntent(paths, transactionId)) return;
+  try { rmSync(paths.rollbackIntent, { force: true }); } catch { /* retry on the next guardian pass */ }
+}
+
+function appendLog(file, message) {
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `[${new Date().toISOString()}] guardian-js: ${message}\n`, { flag: 'a' });
+}
+
+function readPackageMetadata(packageDir) {
+  return readJson(join(packageDir, 'package.json'));
+}
+
+function packageVersion(packageDir) {
+  try {
+    const metadata = readPackageMetadata(packageDir);
+    if (metadata.name !== PACKAGE_NAME || typeof metadata.version !== 'string') return null;
+    return metadata.version.trim().replace(/^v(?=\d)/, '');
+  } catch {
+    return null;
+  }
+}
+
+function validatePackage(packageDir, expectedVersion) {
+  const metadata = readPackageMetadata(packageDir);
+  const version = typeof metadata.version === 'string'
+    ? metadata.version.trim().replace(/^v(?=\d)/, '')
+    : '';
+  if (metadata.name !== PACKAGE_NAME || version !== expectedVersion) {
+    throw new Error(`package mismatch at ${packageDir}: expected ${PACKAGE_NAME}@${expectedVersion}`);
+  }
+  const bins = typeof metadata.bin === 'string'
+    ? [[PACKAGE_NAME, metadata.bin]]
+    : Object.entries(metadata.bin ?? {}).filter(([, value]) => typeof value === 'string');
+  if (bins.length === 0) throw new Error(`package has no executable bin: ${packageDir}`);
+  for (const [, entry] of bins) {
+    if (!existsSync(join(packageDir, entry))) throw new Error(`package entrypoint is missing: ${entry}`);
+  }
+}
+
+function isPathInside(parent, child) {
+  const rel = relative(resolve(parent), resolve(child));
+  return rel !== '' && !rel.startsWith(`..${sep}`) && rel !== '..' && !isAbsolute(rel);
+}
+
+/**
+ * 事务自述的激活策略。guardian 按它分支而不看运行平台：
+ * `wrapper-runtime` 是 Windows 现状（wrapper 承接、切 per-root runtime）；
+ * `service-start` 是 macOS——切包后运行目标 CLI `start` 刷新受管 runtime 并重启
+ * 服务，不做 runtime 目录 rename，也不需要杀进程（`start` 自己完成服务重启）。
+ * 历史事务没有该字段，视为 `wrapper-runtime`。
+ */
+export function transactionStrategy(pending) {
+  return pending?.activation_strategy === 'service-start' ? 'service-start' : 'wrapper-runtime';
+}
+
+function defaultRunServiceStart(cliPath) {
+  execFileSync(process.execPath, [cliPath, 'start'], {
+    timeout: 180_000,
+    windowsHide: true,
+    stdio: 'ignore',
+  });
+}
+
+export function validateTransaction(pending) {
+  if (!pending || typeof pending !== 'object') throw new Error('pending transaction is missing');
+  if (typeof pending.phase !== 'string' || !TRANSACTION_PHASES.has(pending.phase)) {
+    throw new Error(`unknown upgrade transaction phase: ${String(pending.phase)}`);
+  }
+  if (
+    pending.activation_strategy !== undefined
+    && pending.activation_strategy !== 'wrapper-runtime'
+    && pending.activation_strategy !== 'service-start'
+  ) {
+    throw new Error(`unknown upgrade activation strategy: ${String(pending.activation_strategy)}`);
+  }
+  for (const key of ['transaction_id', 'from_version', 'target_version', 'npm_prefix', 'npm_lock_file', 'package_dir', 'backup_dir', 'staged_package_dir', 'staging_prefix']) {
+    if (typeof pending[key] !== 'string' || pending[key].trim() === '') {
+      throw new Error(`pending transaction is missing ${key}`);
+    }
+  }
+  const packageFromVersion = typeof pending.package_from_version === 'string' && pending.package_from_version.trim()
+    ? pending.package_from_version.trim()
+    : pending.from_version;
+  if (
+    pending.package_activation_mode !== undefined
+    && pending.package_activation_mode !== 'switched'
+    && pending.package_activation_mode !== 'unchanged'
+  ) throw new Error(`unknown package activation mode: ${String(pending.package_activation_mode)}`);
+  const packageDir = resolve(pending.package_dir);
+  const backupDir = resolve(pending.backup_dir);
+  const stagedPackageDir = resolve(pending.staged_package_dir);
+  const stagingPrefix = resolve(pending.staging_prefix);
+  const npmPrefix = resolve(pending.npm_prefix);
+  const npmLockFile = resolve(pending.npm_lock_file);
+  if (
+    dirname(dirname(packageDir)) !== npmPrefix
+    || basename(dirname(packageDir)) !== 'node_modules'
+    || basename(packageDir) !== PACKAGE_NAME
+  ) {
+    throw new Error(`unsafe active package path: ${packageDir}`);
+  }
+  if (backupDir !== `${packageDir}${PACKAGE_BACKUP_SUFFIX}`) {
+    throw new Error(`unsafe backup package path: ${backupDir}`);
+  }
+  if (npmLockFile !== join(npmPrefix, NPM_PREFIX_UPGRADE_LOCK_FILE)) {
+    throw new Error(`unsafe npm prefix lock path: ${npmLockFile}`);
+  }
+  if (
+    dirname(stagingPrefix) !== npmPrefix
+    || !basename(stagingPrefix).startsWith('.grix-upgrade-stage-')
+    || !isPathInside(stagingPrefix, stagedPackageDir)
+    || basename(dirname(stagedPackageDir)) !== 'node_modules'
+    || basename(stagedPackageDir) !== PACKAGE_NAME
+  ) {
+    throw new Error(`unsafe staged package path: ${stagedPackageDir}`);
+  }
+  return {
+    ...pending,
+    package_from_version: packageFromVersion,
+    npm_prefix: npmPrefix,
+    npm_lock_file: npmLockFile,
+    package_dir: packageDir,
+    backup_dir: backupDir,
+    staged_package_dir: stagedPackageDir,
+    staging_prefix: stagingPrefix,
+  };
+}
+
+function validateNpmPrefixLock(pending, pendingFile) {
+  let lock;
+  try {
+    lock = existsSync(join(pending.npm_lock_file, 'owner.json'))
+      ? readJson(join(pending.npm_lock_file, 'owner.json'))
+      : readJson(pending.npm_lock_file);
+  } catch { throw new Error('shared npm upgrade lock is missing or unreadable'); }
+  if (
+    lock?.transaction_id !== pending.transaction_id
+    || resolve(String(lock?.pending_file ?? '')) !== resolve(pendingFile)
+  ) {
+    throw new Error('shared npm upgrade lock belongs to another transaction');
+  }
+}
+
+function validateRuntimeTransaction(pending, runtimeDir) {
+  const resolvedRuntime = resolve(runtimeDir);
+  const runtimeBackup = `${resolvedRuntime}${RUNTIME_BACKUP_SUFFIX}`;
+  const runtimeNext = `${resolvedRuntime}${RUNTIME_NEXT_SUFFIX}`;
+  if (pending.runtime_dir && resolve(pending.runtime_dir) !== resolvedRuntime) {
+    throw new Error(`unsafe managed runtime path: ${pending.runtime_dir}`);
+  }
+  if (pending.runtime_backup_dir && resolve(pending.runtime_backup_dir) !== runtimeBackup) {
+    throw new Error(`unsafe managed runtime backup path: ${pending.runtime_backup_dir}`);
+  }
+  if (pending.runtime_next_dir && resolve(pending.runtime_next_dir) !== runtimeNext) {
+    throw new Error(`unsafe managed runtime staging path: ${pending.runtime_next_dir}`);
+  }
+  return { runtimeDir: resolvedRuntime, runtimeBackup, runtimeNext };
+}
+
+export function isTransientFsError(error) {
+  const code = error && typeof error === 'object' ? error.code : undefined;
+  return code === 'EBUSY' || code === 'EPERM' || code === 'EACCES' || code === 'ENOTEMPTY';
+}
+
+export async function renameWithRetry(source, destination, deps = {}) {
+  const rename = deps.rename ?? renameSync;
+  const wait = deps.sleep ?? sleep;
+  let lastError;
+  for (let attempt = 0; attempt <= RENAME_RETRY_DELAYS_MS.length; attempt++) {
+    try {
+      rename(source, destination);
+      return;
+    } catch (error) {
+      lastError = error;
+      if (!isTransientFsError(error) || attempt >= RENAME_RETRY_DELAYS_MS.length) throw error;
+      await wait(RENAME_RETRY_DELAYS_MS[attempt]);
+    }
+  }
+  throw lastError;
+}
+
+function guardianLockEndpoint(rootDir, platform = process.platform) {
+  const digest = createHash('sha256').update(resolve(rootDir)).digest('hex');
+  if (platform === 'win32') return `\\\\.\\pipe\\grix-upgrade-${digest.slice(0, 24)}`;
+  return { host: '127.0.0.1', port: 35_000 + (Number.parseInt(digest.slice(0, 8), 16) % 20_000) };
+}
+
+export async function acquireGuardianProcessLock(rootDir, deps = {}) {
+  const lockFile = pathsFor(rootDir).lock;
+  const server = (deps.createServer ?? createServer)();
+  const endpoint = deps.lockEndpoint ?? guardianLockEndpoint(rootDir, deps.platform);
+  const acquired = await new Promise((resolveAcquire, reject) => {
+    const onError = (error) => {
+      if (error?.code === 'EADDRINUSE' || error?.code === 'EACCES') resolveAcquire(false);
+      else reject(error);
+    };
+    server.once('error', onError);
+    server.once('listening', () => {
+      server.removeListener('error', onError);
+      server.on('error', () => { /* the process-lifetime lock remains fail-closed */ });
+      resolveAcquire(true);
+    });
+    server.listen(endpoint);
+  });
+  if (!acquired) return null;
+  server.unref?.();
+  const token = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  try {
+    writeJsonAtomic(lockFile, {
+      protocol: 'os-lifetime-v1',
+      token,
+      pid: process.pid,
+      created_at: Date.now(),
+      command_line: readProcessCommandLine(process.pid, deps),
+    });
+  } catch (error) {
+    await new Promise((resolveClose) => server.close(() => resolveClose()));
+    throw error;
+  }
+  return { server, lockFile, token };
+}
+
+export async function releaseGuardianProcessLock(handle) {
+  if (!handle) return;
+  try {
+    const lock = readJson(handle.lockFile);
+    if (lock?.protocol === 'os-lifetime-v1' && lock?.token === handle.token) {
+      rmSync(handle.lockFile, { force: true });
+    }
+  } catch { /* best effort */ }
+  await new Promise((resolveClose) => {
+    try { handle.server.close(() => resolveClose()); } catch { resolveClose(); }
+  });
+}
+
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+function readProcessCommandLine(pid, deps = {}) {
+  if (deps.getProcessCommandLine) return deps.getProcessCommandLine(pid);
+  if (process.platform !== 'win32' || !Number.isInteger(pid) || pid <= 0) return null;
+  try {
+    const output = execFileSync(
+      powershellPath(),
+      [
+        '-NoProfile',
+        '-NonInteractive',
+        '-WindowStyle',
+        'Hidden',
+        '-Command',
+        `(Get-CimInstance Win32_Process -Filter 'ProcessId=${pid}').CommandLine`,
+      ],
+      { encoding: 'utf8', timeout: 3_000, windowsHide: true },
+    ).trim();
+    return output || null;
+  } catch {
+    return null;
+  }
+}
+
+function originalProcessAlive(pending, deps = {}) {
+  const recordedBootTime = Number(pending.old_boot_time);
+  const currentBootTime = currentBootTimestamp(deps);
+  // A process cannot survive an OS reboot. This proof lets recovery proceed
+  // when the old PID has been reused and CIM command-line inspection is
+  // unavailable, without authorizing a kill of the unrelated new process.
+  if (
+    Number.isFinite(recordedBootTime)
+    && Number.isFinite(currentBootTime)
+    && Math.abs(currentBootTime - recordedBootTime) > 60_000
+  ) return false;
+  const alive = deps.isPidAlive ?? isPidAlive;
+  if (!alive(pending.old_pid)) return false;
+  const recorded = typeof pending.old_command_line === 'string' && pending.old_command_line
+    ? pending.old_command_line
+    : null;
+  if (!recorded) return true;
+  const current = readProcessCommandLine(pending.old_pid, deps);
+  return current === null || current === recorded;
+}
+
+async function waitForOriginalProcessExit(pending, timeoutMs = 15_000, deps = {}) {
+  const wait = deps.sleep ?? sleep;
+  const now = deps.now ?? Date.now;
+  const deadline = now() + timeoutMs;
+  while (originalProcessAlive(pending, deps) && now() < deadline) await wait(250);
+  return !originalProcessAlive(pending, deps);
+}
+
+function monitorIdentityAlive(pending, paths, deps = {}) {
+  const alive = deps.isPidAlive ?? isPidAlive;
+  const now = deps.now ?? Date.now;
+  if (!Number.isInteger(pending.guardian_pid) || !alive(pending.guardian_pid)) return false;
+  try {
+    const heartbeat = readJson(paths.monitorHeartbeat);
+    if (
+      heartbeat?.transaction_id === pending.transaction_id
+      && heartbeat?.pid === pending.guardian_pid
+      && Number.isFinite(heartbeat?.updated_at)
+      && now() - heartbeat.updated_at <= MONITOR_IDENTITY_GRACE_MS
+    ) return true;
+  } catch { /* monitor may still be starting */ }
+  const startedAt = Date.parse(pending.guardian_started_at ?? '');
+  return Number.isFinite(startedAt) && now() - startedAt <= MONITOR_IDENTITY_GRACE_MS;
+}
+
+async function waitForPidExit(pid, timeoutMs = 15_000, deps = {}) {
+  const alive = deps.isPidAlive ?? isPidAlive;
+  const wait = deps.sleep ?? sleep;
+  const now = deps.now ?? Date.now;
+  const deadline = now() + timeoutMs;
+  while (alive(pid) && now() < deadline) await wait(250);
+  return !alive(pid);
+}
+
+function updatePending(pendingFile, patch, expected = {}) {
+  const current = readJson(pendingFile);
+  if (expected.transactionId && current.transaction_id !== expected.transactionId) {
+    throw new Error('upgrade transaction ownership changed');
+  }
+  if (expected.phase && current.phase !== expected.phase) {
+    throw new Error(`upgrade transaction phase changed to ${String(current.phase)}`);
+  }
+  if (expected.guardianPid !== undefined && current.guardian_pid !== expected.guardianPid) {
+    throw new Error('upgrade verification monitor ownership changed');
+  }
+  const next = { ...current, ...patch };
+  writeJsonAtomic(pendingFile, next);
+  return next;
+}
+
+async function switchPackage(pending, deps = {}) {
+  const rename = (source, destination) => renameWithRetry(source, destination, deps);
+  const isValid = (directory, version) => {
+    try { validatePackage(directory, version); return true; } catch { return false; }
+  };
+  const sourceVersion = pending.package_from_version ?? pending.from_version;
+  if (isValid(pending.package_dir, pending.target_version)) {
+    if (sourceVersion === pending.target_version) {
+      // A completed legacy/root transaction may have left the fixed backup
+      // behind. This root did not switch the shared package and does not depend
+      // on that backup; terminal cleanup will remove it while holding the lock.
+      updatePending(deps.pendingFile, { package_activation_mode: 'unchanged' }, {
+        transactionId: pending.transaction_id,
+        phase: 'activating',
+      });
+      return 'unchanged';
+    }
+    if (!isValid(pending.backup_dir, sourceVersion)) {
+      throw new Error('target package is active but its global source backup is missing or invalid');
+    }
+    updatePending(deps.pendingFile, { package_activation_mode: 'switched' }, {
+      transactionId: pending.transaction_id,
+      phase: 'activating',
+    });
+    return 'switched';
+  }
+  if (!isValid(pending.staged_package_dir, pending.target_version)) {
+    throw new Error('staged target package is missing or invalid');
+  }
+
+  // Never discard the only valid source backup.  Interrupted renames can leave
+  // a corrupt active tree next to a complete backup; restore that backup first.
+  if (!isValid(pending.package_dir, sourceVersion)) {
+    if (!isValid(pending.backup_dir, sourceVersion)) {
+      throw new Error('active package and source backup are both invalid');
+    }
+    const failed = `${pending.package_dir}${PACKAGE_FAILED_SUFFIX}`;
+    rmSync(failed, { recursive: true, force: true });
+    if (existsSync(pending.package_dir)) await rename(pending.package_dir, failed);
+    await rename(pending.backup_dir, pending.package_dir);
+    rmSync(failed, { recursive: true, force: true });
+  } else if (existsSync(pending.backup_dir)) {
+    // Active source has been fully validated, so a stale backup can now be
+    // replaced without reducing the number of runnable source copies below one.
+    rmSync(pending.backup_dir, { recursive: true, force: true });
+  }
+  updatePending(deps.pendingFile, { package_activation_mode: 'switched' }, {
+    transactionId: pending.transaction_id,
+    phase: 'activating',
+  });
+  await rename(pending.package_dir, pending.backup_dir);
+  try {
+    await rename(pending.staged_package_dir, pending.package_dir);
+    validatePackage(pending.package_dir, pending.target_version);
+  } catch (error) {
+    if (existsSync(pending.backup_dir)) {
+      const failed = `${pending.package_dir}${PACKAGE_FAILED_SUFFIX}`;
+      rmSync(failed, { recursive: true, force: true });
+      if (existsSync(pending.package_dir)) await rename(pending.package_dir, failed);
+      await rename(pending.backup_dir, pending.package_dir);
+      rmSync(failed, { recursive: true, force: true });
+    }
+    throw error;
+  }
+  return 'switched';
+}
+
+async function deployManagedRuntime(pending, runtimeDir, deps = {}) {
+  const runtimeBackup = `${runtimeDir}${RUNTIME_BACKUP_SUFFIX}`;
+  const runtimeNext = `${runtimeDir}${RUNTIME_NEXT_SUFFIX}`;
+  updatePending(deps.pendingFile, {
+    runtime_dir: runtimeDir,
+    runtime_backup_dir: runtimeBackup,
+    runtime_next_dir: runtimeNext,
+  });
+
+  const isValid = (directory, version) => {
+    try { validatePackage(directory, version); return true; } catch { return false; }
+  };
+  if (isValid(runtimeDir, pending.target_version) && isValid(runtimeBackup, pending.from_version)) return;
+
+  if (!isValid(runtimeDir, pending.from_version)) {
+    if (!isValid(runtimeBackup, pending.from_version)) {
+      throw new Error('active managed runtime and source backup are both invalid');
+    }
+    const failed = `${runtimeDir}${PACKAGE_FAILED_SUFFIX}`;
+    rmSync(failed, { recursive: true, force: true });
+    if (existsSync(runtimeDir)) await renameWithRetry(runtimeDir, failed, deps);
+    await renameWithRetry(runtimeBackup, runtimeDir, deps);
+    rmSync(failed, { recursive: true, force: true });
+  } else if (existsSync(runtimeBackup)) {
+    rmSync(runtimeBackup, { recursive: true, force: true });
+  }
+
+  if (!isValid(runtimeNext, pending.target_version)) {
+    // Compatibility fallback for a transaction created before runtime
+    // pre-staging existed. New transactions finish this expensive copy while
+    // the old daemon is still online.
+    rmSync(runtimeNext, { recursive: true, force: true });
+    mkdirSync(runtimeNext, { recursive: true });
+    cpSync(join(pending.package_dir, 'dist'), join(runtimeNext, 'dist'), { recursive: true, force: true });
+    copyFileSync(join(pending.package_dir, 'package.json'), join(runtimeNext, 'package.json'));
+    const sourceNodeModules = join(pending.package_dir, 'node_modules');
+    if (existsSync(sourceNodeModules)) {
+      cpSync(sourceNodeModules, join(runtimeNext, 'node_modules'), { recursive: true, force: true });
+    }
+    validatePackage(runtimeNext, pending.target_version);
+  }
+
+  await renameWithRetry(runtimeDir, runtimeBackup, deps);
+  try {
+    await renameWithRetry(runtimeNext, runtimeDir, deps);
+    validatePackage(runtimeDir, pending.target_version);
+  } catch (error) {
+    if (existsSync(runtimeBackup)) {
+      const failed = `${runtimeDir}${PACKAGE_FAILED_SUFFIX}`;
+      rmSync(failed, { recursive: true, force: true });
+      if (existsSync(runtimeDir)) await renameWithRetry(runtimeDir, failed, deps);
+      await renameWithRetry(runtimeBackup, runtimeDir, deps);
+      rmSync(failed, { recursive: true, force: true });
+    }
+    throw error;
+  }
+}
+
+async function restoreBackupTree(activeDir, backupDir, deps = {}) {
+  const failedDir = `${activeDir}${PACKAGE_FAILED_SUFFIX}`;
+  rmSync(failedDir, { recursive: true, force: true });
+  let activeMoved = false;
+  if (existsSync(activeDir)) {
+    await renameWithRetry(activeDir, failedDir, deps);
+    activeMoved = true;
+  }
+  try {
+    await renameWithRetry(backupDir, activeDir, deps);
+  } catch (error) {
+    // A failed backup restore must not leave the stable path empty. Put the
+    // complete target back and retain the source backup for a later retry.
+    if (activeMoved && !existsSync(activeDir) && existsSync(failedDir)) {
+      try { await renameWithRetry(failedDir, activeDir, deps); } catch { /* surface original restore failure */ }
+    }
+    throw error;
+  }
+  rmSync(failedDir, { recursive: true, force: true });
+}
+
+function powershellPath(env = process.env) {
+  return `${env.SystemRoot || 'C:\\Windows'}\\System32\\WindowsPowerShell\\v1.0\\powershell.exe`;
+}
+
+function quoteWindowsArg(value) {
+  if (String(value).includes('"')) throw new Error('Windows helper path contains an unsupported quote');
+  return `"${value}"`;
+}
+
+function launchIndependentMonitor(rootDir) {
+  const scriptPath = fileURLToPath(import.meta.url);
+  if (process.platform !== 'win32') {
+    const child = spawn(process.execPath, [scriptPath, 'monitor', '--root', rootDir], {
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.unref();
+    return child.pid;
+  }
+  const commandLine = [process.execPath, scriptPath, 'monitor', '--root', rootDir]
+    .map(quoteWindowsArg)
+    .join(' ');
+  const escaped = commandLine.replace(/'/g, "''");
+  const ps = `$r=Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments @{CommandLine='${escaped}'}; if($r.ReturnValue -ne 0){exit $r.ReturnValue}; [Console]::Out.Write($r.ProcessId)`;
+  const encoded = Buffer.from(ps, 'utf16le').toString('base64');
+  const output = execFileSync(
+    powershellPath(),
+    ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', encoded],
+    { encoding: 'utf8', timeout: 10_000, windowsHide: true },
+  ).trim();
+  const pid = Number(output);
+  if (!Number.isInteger(pid) || pid <= 0) throw new Error(`monitor launch returned invalid pid: ${output}`);
+  return pid;
+}
+
+export function healthMatches(payload, pending, daemonStatus) {
+  const activationStartedAt = typeof pending.activation_started_at === 'number'
+    ? pending.activation_started_at
+    : Date.parse(pending.activation_started_at ?? '');
+  return Number.isFinite(activationStartedAt)
+    && Number.isInteger(pending.old_pid)
+    && pending.old_pid > 0
+    && payload?.status === 'ok'
+    && payload?.version === pending.target_version
+    && Number.isInteger(payload?.pid)
+    && payload.pid > 0
+    && payload.pid !== pending.old_pid
+    && daemonStatus?.state === 'running'
+    && daemonStatus?.pid === payload.pid
+    && typeof daemonStatus?.updated_at === 'number'
+    && daemonStatus.updated_at >= activationStartedAt;
+}
+
+async function fetchHealth(rootDir) {
+  const paths = pathsFor(rootDir);
+  let port = '19579';
+  try { port = readFileSync(paths.healthPort, 'utf8').trim() || port; } catch { /* default */ }
+  const response = await fetch(`http://127.0.0.1:${port}/healthz`, { signal: AbortSignal.timeout(2_000) });
+  if (!response.ok) return null;
+  return response.json();
+}
+
+async function readDaemonStatus(rootDir) {
+  return readJson(pathsFor(rootDir).daemonStatus);
+}
+
+async function readDaemonLock(rootDir) {
+  return readJson(pathsFor(rootDir).daemonLock);
+}
+
+async function readWrapperChild(rootDir) {
+  return readJson(pathsFor(rootDir).wrapperChild);
+}
+
+function currentBootTimestamp(deps = {}) {
+  return deps.bootTime ?? (Date.now() - uptime() * 1000);
+}
+
+function activationTimestamp(pending) {
+  return typeof pending.activation_started_at === 'number'
+    ? pending.activation_started_at
+    : Date.parse(pending.activation_started_at ?? '');
+}
+
+function postActivationDaemonPid(daemonStatus, pending, deps = {}) {
+  const activationStartedAt = activationTimestamp(pending);
+  const earliestGenerationTime = Math.max(activationStartedAt, currentBootTimestamp(deps) - 60_000);
+  return Number.isFinite(activationStartedAt)
+    && ['starting', 'running', 'stopping', 'failed'].includes(daemonStatus?.state)
+    && Number.isInteger(daemonStatus?.pid)
+    && daemonStatus.pid > 0
+    && daemonStatus.pid !== pending.old_pid
+    && typeof daemonStatus?.instance_id === 'string'
+    && daemonStatus.instance_id.length > 0
+    && typeof daemonStatus?.updated_at === 'number'
+    && daemonStatus.updated_at >= earliestGenerationTime
+    ? daemonStatus.pid
+    : null;
+}
+
+function verifiedTargetDaemonPid(rootDir, runtimeDir, daemonStatus, daemonLock, pending, deps = {}) {
+  const candidatePid = postActivationDaemonPid(daemonStatus, pending, deps);
+  if (candidatePid === null) return null;
+  const activationStartedAt = activationTimestamp(pending);
+  const earliestGenerationTime = Math.max(activationStartedAt, currentBootTimestamp(deps) - 60_000);
+  const recordedCommandLine = typeof daemonLock?.command_line === 'string'
+    ? daemonLock.command_line.trim()
+    : '';
+  const expectedCli = join(runtimeDir, 'dist', 'grix.js').replace(/\\/g, '/').toLowerCase();
+  if (
+    daemonLock?.pid !== candidatePid
+    || typeof daemonLock?.root_dir !== 'string'
+    || resolve(daemonLock.root_dir) !== resolve(rootDir)
+    || typeof daemonLock?.instance_id !== 'string'
+    || daemonLock.instance_id.length === 0
+    || daemonLock.instance_id !== daemonStatus.instance_id
+    || typeof daemonLock?.acquired_at !== 'number'
+    || daemonLock.acquired_at < earliestGenerationTime
+    || recordedCommandLine.length === 0
+    || !recordedCommandLine.replace(/\\/g, '/').toLowerCase().includes(expectedCli)
+  ) return null;
+  const currentCommandLine = readProcessCommandLine(candidatePid, deps);
+  return currentCommandLine !== null && currentCommandLine === recordedCommandLine
+    ? candidatePid
+    : null;
+}
+
+function wrapperChildPid(record, runtimeDir, pending, deps = {}) {
+  const activationStartedAt = activationTimestamp(pending);
+  const currentBootTime = currentBootTimestamp(deps);
+  const expectedCli = join(runtimeDir, 'dist', 'grix.js');
+  return Number.isFinite(activationStartedAt)
+    && Number.isInteger(record?.pid)
+    && record.pid > 0
+    && record.pid !== pending.old_pid
+    && typeof record?.launched_at === 'number'
+    && record.launched_at >= Math.max(activationStartedAt, currentBootTime - 60_000)
+    && typeof record?.boot_time === 'number'
+    && Math.abs(record.boot_time - currentBootTime) <= 60_000
+    && typeof record?.cli_path === 'string'
+    && resolve(record.cli_path) === resolve(expectedCli)
+    ? record.pid
+    : null;
+}
+
+function verifiedWrapperChildPid(record, runtimeDir, pending, deps = {}) {
+  const candidatePid = wrapperChildPid(record, runtimeDir, pending, deps);
+  if (candidatePid === null) return null;
+  const expectedCli = join(runtimeDir, 'dist', 'grix.js').replace(/\\/g, '/').toLowerCase();
+  const currentCommandLine = readProcessCommandLine(candidatePid, deps);
+  return currentCommandLine !== null
+    && currentCommandLine.replace(/\\/g, '/').toLowerCase().includes(expectedCli)
+    ? candidatePid
+    : null;
+}
+
+/**
+ * The active package is already the verified target at this point. Refresh the
+ * package-out guardian through a same-directory temporary file so the next
+ * upgrade never depends on the package version that is about to be replaced.
+ */
+export async function installActiveGuardian(rootDir, pending, deps = {}) {
+  const paths = pathsFor(rootDir);
+  const source = join(pending.package_dir, 'scripts', 'upgrade-guardian.mjs');
+  if (!isPathInside(pending.package_dir, source) || !existsSync(source)) {
+    throw new Error(`active package guardian is missing: ${source}`);
+  }
+  mkdirSync(dirname(paths.installedGuardian), { recursive: true });
+  const temporary = `${paths.installedGuardian}.tmp-${process.pid}`;
+  const copy = deps.copyFile ?? copyFileSync;
+  try {
+    // Keep the transaction creator's helper as a fallback. If antivirus
+    // quarantines the newly installed primary during the next handoff, the
+    // wrapper can still finish that transaction with its matching schema.
+    try {
+      if (existsSync(paths.installedGuardian)) copy(paths.installedGuardian, paths.fallbackGuardian);
+    } catch { /* primary remains authoritative */ }
+    copy(source, temporary);
+    await renameWithRetry(temporary, paths.installedGuardian, deps);
+  } finally {
+    try { rmSync(temporary, { force: true }); } catch { /* best effort */ }
+  }
+}
+
+async function restorePreviousVersion(rootDir, pending, deps = {}) {
+  const paths = pathsFor(rootDir);
+  writeJsonAtomic(paths.pause, { transaction_id: pending.transaction_id });
+  updatePending(paths.pending, { phase: 'rolling_back', error_code: 'STARTUP_CRASH' });
+
+  if (transactionStrategy(pending) === 'service-start') {
+    await restorePreviousVersionByServiceStart(rootDir, pending, paths, deps);
+    return;
+  }
+
+  const daemonStatus = await (deps.readDaemonStatus ?? readDaemonStatus)(rootDir).catch(() => null);
+  const daemonLock = await (deps.readDaemonLock ?? readDaemonLock)(rootDir).catch(() => null);
+  const wrapperChild = await (deps.readWrapperChild ?? readWrapperChild)(rootDir).catch(() => null);
+  const expectedRuntimeDir = resolveTransactionRuntimeDir(rootDir, pending, deps);
+  const statusPid = postActivationDaemonPid(daemonStatus, pending, deps);
+  const launchedPid = wrapperChildPid(wrapperChild, expectedRuntimeDir, pending, deps);
+  const alive = deps.isPidAlive ?? isPidAlive;
+  const liveCandidates = [...new Set([statusPid, launchedPid]
+    .filter((pid) => pid !== null && alive(pid)))];
+  if (liveCandidates.length > 1) {
+    throw new Error(`multiple target daemon candidates are alive (${liveCandidates.join(', ')}); refusing rollback`);
+  }
+  if (liveCandidates.length === 1) {
+    const candidatePid = liveCandidates[0];
+    const verifiedByDaemonState = candidatePid === statusPid && verifiedTargetDaemonPid(
+      rootDir,
+      expectedRuntimeDir,
+      daemonStatus,
+      daemonLock,
+      pending,
+      deps,
+    );
+    const verifiedByWrapper = candidatePid === launchedPid
+      && verifiedWrapperChildPid(wrapperChild, expectedRuntimeDir, pending, deps);
+    const targetPid = verifiedByDaemonState || verifiedByWrapper;
+    if (targetPid === null || targetPid === false) {
+      throw new Error(`target daemon ${candidatePid} identity could not be verified; refusing rollback`);
+    }
+    if (deps.terminatePid) {
+      await deps.terminatePid(targetPid);
+    } else if (process.platform === 'win32') {
+      try { execFileSync('taskkill', ['/PID', String(targetPid), '/T', '/F'], { timeout: 10_000, windowsHide: true }); } catch { /* already gone */ }
+    } else {
+      try { process.kill(targetPid, 'SIGTERM'); } catch { /* already gone */ }
+    }
+    if (!(await waitForPidExit(targetPid, 10_000, deps))) {
+      throw new Error(`target daemon ${targetPid} did not exit; refusing to move active package or runtime`);
+    }
+  }
+
+  const { runtimeDir, runtimeBackup } = validateRuntimeTransaction(pending, expectedRuntimeDir);
+  const packageSourceVersion = pending.package_from_version ?? pending.from_version;
+  const packageWasSwitched = pending.package_activation_mode === 'switched'
+    || (pending.package_activation_mode === undefined && packageSourceVersion !== pending.target_version);
+  const needsRuntimeRestore = packageVersion(runtimeDir) !== pending.from_version;
+  const needsPackageRestore = packageWasSwitched
+    && packageVersion(pending.package_dir) !== packageSourceVersion;
+  // Validate both offline recovery sources before moving either active tree.
+  // This preserves the last runnable pair when a transaction is corrupt.
+  if (needsRuntimeRestore && packageVersion(runtimeBackup) !== pending.from_version) {
+    throw new Error('previous managed runtime backup is missing or invalid');
+  }
+  if (needsPackageRestore && packageVersion(pending.backup_dir) !== packageSourceVersion) {
+    throw new Error('previous package backup is missing or invalid');
+  }
+
+  if (needsRuntimeRestore) {
+    await restoreBackupTree(runtimeDir, runtimeBackup, deps);
+  }
+
+  if (needsPackageRestore) {
+    await restoreBackupTree(pending.package_dir, pending.backup_dir, deps);
+  }
+  validatePackage(
+    pending.package_dir,
+    packageWasSwitched ? packageSourceVersion : pending.target_version,
+  );
+  validatePackage(runtimeDir, pending.from_version);
+
+  updatePending(paths.pending, { phase: 'rolled_back', error_code: 'STARTUP_CRASH' });
+  rmSync(paths.pause, { force: true });
+  clearRollbackIntent(paths, pending.transaction_id);
+  appendLog(paths.log, `rolled back managed runtime to ${pending.from_version}; global package is ${packageVersion(pending.package_dir)}`);
+}
+
+/**
+ * service-start 策略的回滚：daemon 跑的是受管 runtime 拷贝，不占用全局包目录，
+ * 包可以在服务运行中原子换回；随后由恢复出的旧版 CLI `start` 刷新 runtime 并
+ * 重启服务——它自己会替换正在运行的实例，无需在这里识别并杀进程。
+ */
+async function restorePreviousVersionByServiceStart(rootDir, pending, paths, deps = {}) {
+  const packageSourceVersion = pending.package_from_version ?? pending.from_version;
+  const packageWasSwitched = pending.package_activation_mode === 'switched'
+    || (pending.package_activation_mode === undefined && packageSourceVersion !== pending.target_version);
+  const needsPackageRestore = packageWasSwitched
+    && packageVersion(pending.package_dir) !== packageSourceVersion;
+  if (needsPackageRestore && packageVersion(pending.backup_dir) !== packageSourceVersion) {
+    throw new Error('previous package backup is missing or invalid');
+  }
+  if (needsPackageRestore) {
+    await restoreBackupTree(pending.package_dir, pending.backup_dir, deps);
+  }
+  validatePackage(
+    pending.package_dir,
+    packageWasSwitched ? packageSourceVersion : pending.target_version,
+  );
+  const restoredCli = join(pending.package_dir, 'dist', 'grix.js');
+  if (!existsSync(restoredCli)) throw new Error(`restored package CLI is missing: ${restoredCli}`);
+  // 激活失败必须让事务落 failed：包虽已恢复，但受管 runtime 仍是目标版本，
+  // 不刷新就宣告 rolled_back 会让 launchd 继续跑没人守护的坏版本。
+  (deps.runServiceStart ?? defaultRunServiceStart)(restoredCli);
+
+  updatePending(paths.pending, { phase: 'rolled_back', error_code: 'STARTUP_CRASH' });
+  rmSync(paths.pause, { force: true });
+  clearRollbackIntent(paths, pending.transaction_id);
+  appendLog(paths.log, `service-start rollback restored ${packageVersion(pending.package_dir)} and reactivated the managed service`);
+}
+
+async function launchVerificationMonitor(rootDir, pending, paths, injected) {
+  const current = validateTransaction(readJson(paths.pending));
+  if (monitorIdentityAlive(current, paths, injected)) {
+    rmSync(paths.pause, { force: true });
+    return 'verifying';
+  }
+  const verificationStartedAt = current.verification_started_at
+    ?? new Date((injected.now ?? Date.now)()).toISOString();
+  updatePending(paths.pending, {
+    phase: 'verifying',
+    guardian_pid: undefined,
+    guardian_started_at: undefined,
+    verification_started_at: verificationStartedAt,
+  });
+  const monitorPid = await (injected.launchMonitor ?? launchIndependentMonitor)(rootDir);
+  updatePending(paths.pending, {
+    guardian_pid: monitorPid,
+    guardian_started_at: new Date((injected.now ?? Date.now)()).toISOString(),
+  });
+  rmSync(paths.pause, { force: true });
+  appendLog(paths.log, `activated ${pending.target_version}; monitor pid=${monitorPid}`);
+  return 'verifying';
+}
+
+export async function activateWindowsUpgrade(rootDir, injected = {}) {
+  const paths = pathsFor(rootDir);
+  let rawPending;
+  try {
+    rawPending = readJson(paths.pending);
+  } catch {
+    rmSync(paths.pause, { force: true });
+    appendLog(paths.log, 'cleared orphaned wrapper pause marker because the pending transaction is missing or unreadable');
+    return 'stale_marker_cleared';
+  }
+
+  let pending;
+  try {
+    pending = validateTransaction(rawPending);
+  } catch (error) {
+    rmSync(paths.pause, { force: true });
+    appendLog(paths.log, `cleared wrapper pause marker for an invalid transaction: ${error instanceof Error ? error.message : String(error)}`);
+    return 'stale_marker_cleared';
+  }
+  const rollbackIntent = readRollbackIntent(paths, pending.transaction_id);
+  if (
+    rollbackIntent
+    && (pending.phase === 'verifying' || pending.phase === 'healthy' || pending.phase === 'rolling_back')
+  ) {
+    pending = updatePending(paths.pending, {
+      phase: 'rolling_back',
+      guardian_pid: undefined,
+      error_code: 'STARTUP_CRASH',
+      error_msg: rollbackIntent.message,
+    }, { transactionId: pending.transaction_id });
+  }
+  let hasMatchingPause = false;
+  if (existsSync(paths.pause)) {
+    let pauseTransactionId;
+    try { pauseTransactionId = readJson(paths.pause)?.transaction_id; } catch { /* stale/corrupt marker */ }
+    if (pauseTransactionId !== pending.transaction_id) {
+      rmSync(paths.pause, { force: true });
+      appendLog(paths.log, `cleared stale wrapper pause marker (marker=${String(pauseTransactionId)}, pending=${pending.transaction_id})`);
+      return 'stale_marker_cleared';
+    }
+    hasMatchingPause = true;
+  }
+  const runtimeDir = resolveTransactionRuntimeDir(rootDir, pending, injected);
+  validateRuntimeTransaction(pending, runtimeDir);
+  if (pending.phase === 'healthy' || pending.phase === 'rolled_back' || pending.phase === 'finalizing') {
+    rmSync(paths.pause, { force: true });
+    return pending.phase;
+  }
+  if (pending.phase === 'failed') {
+    // 回滚源损坏时保留 pending 供人工诊断，但不能让 wrapper 因 marker 永久停服。
+    rmSync(paths.pause, { force: true });
+    appendLog(paths.log, 'manual recovery is required; released wrapper to run the last intact runtime');
+    return 'failed';
+  }
+  if (pending.phase === 'preparing' || (
+    (pending.phase === 'staged' || pending.phase === 'handoff_ready')
+    && !hasMatchingPause
+  )) {
+    // A plain pending file is not authorization to cross the idle/shutdown
+    // boundary. This is important because the wrapper also invokes us after an
+    // unrelated daemon crash while staging may still be in progress.
+    appendLog(paths.log, `transaction ${pending.transaction_id} is waiting for an explicit wrapper handoff`);
+    return 'waiting_for_handoff';
+  }
+  validateNpmPrefixLock(pending, paths.pending);
+  if (
+    !injected.wrapperHandoffComplete
+    && pending.old_pid
+    && !(await waitForOriginalProcessExit(pending, 15_000, injected))
+  ) {
+    throw new Error(`old daemon ${pending.old_pid} is still running`);
+  }
+
+  if (pending.phase === 'rolling_back') {
+    try {
+      await restorePreviousVersion(rootDir, pending, injected);
+      return 'rolled_back';
+    } catch (error) {
+      updatePending(paths.pending, {
+        phase: 'failed',
+        error_code: 'ROLLBACK_FAILED',
+        error_msg: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
+    }
+  }
+
+  if (pending.phase === 'verifying') {
+    try {
+      validatePackage(pending.package_dir, pending.target_version);
+      // service-start 策略没有 guardian 管理的 runtime 目录，健康与否由 monitor
+      // 按 healthz/daemon-status 裁决即可。
+      if (transactionStrategy(pending) === 'wrapper-runtime') {
+        validatePackage(pending.runtime_dir ?? runtimeDir, pending.target_version);
+      }
+      return await launchVerificationMonitor(rootDir, pending, paths, injected);
+    } catch (error) {
+      appendLog(paths.log, `verification resume failed: ${error instanceof Error ? error.message : String(error)}`);
+      try {
+        await restorePreviousVersion(rootDir, pending, injected);
+        return 'rolled_back';
+      } catch (rollbackError) {
+        updatePending(paths.pending, {
+          phase: 'failed',
+          error_code: 'ROLLBACK_FAILED',
+          error_msg: rollbackError instanceof Error ? rollbackError.message : String(rollbackError),
+        });
+        throw rollbackError;
+      }
+    }
+  }
+
+  try {
+    updatePending(paths.pending, { phase: 'activating', guardian_pid: process.pid });
+    await switchPackage(pending, { ...injected, pendingFile: paths.pending });
+    if (transactionStrategy(pending) === 'wrapper-runtime') {
+      const current = validateTransaction(readJson(paths.pending));
+      await deployManagedRuntime(current, runtimeDir, { ...injected, pendingFile: paths.pending });
+    } else {
+      // service-start：已切换的目标 CLI `start` 会刷新受管 runtime 副本、重写
+      // 服务定义并重启服务（替换 launchd 拉起的旧 runtime 实例）。失败视同激活
+      // 失败，走下方回滚。
+      (injected.runServiceStart ?? defaultRunServiceStart)(join(pending.package_dir, 'dist', 'grix.js'));
+    }
+    try { rmSync(pending.staging_prefix, { recursive: true, force: true }); } catch { /* best effort */ }
+    return await launchVerificationMonitor(rootDir, pending, paths, injected);
+  } catch (error) {
+    appendLog(paths.log, `activation failed: ${error instanceof Error ? error.message : String(error)}`);
+    try {
+      const current = validateTransaction(readJson(paths.pending));
+      await restorePreviousVersion(rootDir, current, injected);
+      return 'rolled_back';
+    } catch (rollbackError) {
+      updatePending(paths.pending, {
+        phase: 'failed',
+        error_code: 'ROLLBACK_FAILED',
+        error_msg: rollbackError instanceof Error ? rollbackError.message : String(rollbackError),
+      });
+      throw rollbackError;
+    }
+  }
+}
+
+export async function monitorWindowsUpgrade(rootDir, injected = {}) {
+  const paths = pathsFor(rootDir);
+  let pending = validateTransaction(readJson(paths.pending));
+  const transactionId = pending.transaction_id;
+  const monitorPid = injected.monitorPid ?? process.pid;
+  const fence = {
+    transactionId,
+    phase: 'verifying',
+    ...(Number.isInteger(pending.guardian_pid) ? { guardianPid: monitorPid } : {}),
+  };
+  const ownsVerification = (candidate) => candidate.transaction_id === transactionId
+    && candidate.phase === 'verifying'
+    && (fence.guardianPid === undefined || candidate.guardian_pid === monitorPid);
+  if (!ownsVerification(pending)) return 'superseded';
+  const runtimeDir = resolveTransactionRuntimeDir(rootDir, pending, injected);
+  validateRuntimeTransaction(pending, runtimeDir);
+  validateNpmPrefixLock(pending, paths.pending);
+  const probe = injected.fetchHealth ?? fetchHealth;
+  const readStatus = injected.readDaemonStatus ?? readDaemonStatus;
+  const wait = injected.sleep ?? sleep;
+  const now = injected.now ?? Date.now;
+  const timeoutMs = injected.healthTimeoutMs ?? HEALTH_TIMEOUT_MS;
+  const rollbackIfRequested = async () => {
+    const intent = readRollbackIntent(paths, transactionId);
+    if (!intent) return null;
+    let current = validateTransaction(readJson(paths.pending));
+    if (current.transaction_id !== transactionId) return 'superseded';
+    if (current.phase === 'rolled_back' || current.phase === 'finalizing') {
+      clearRollbackIntent(paths, transactionId);
+      return current.phase;
+    }
+    if (current.phase === 'failed') return 'failed';
+    current = updatePending(paths.pending, {
+      phase: 'rolling_back',
+      guardian_pid: undefined,
+      error_code: 'STARTUP_CRASH',
+      error_msg: intent.message,
+    }, { transactionId });
+    appendLog(paths.log, `durable rollback intent won verification for ${transactionId}`);
+    try {
+      await restorePreviousVersion(rootDir, current, injected);
+      rmSync(paths.monitorHeartbeat, { force: true });
+      return 'rolled_back';
+    } catch (error) {
+      updatePending(paths.pending, {
+        phase: 'failed',
+        error_code: 'ROLLBACK_FAILED',
+        error_msg: error instanceof Error ? error.message : String(error),
+      }, { transactionId });
+      throw error;
+    }
+  };
+  const verificationStartedAt = Date.parse(
+    pending.verification_started_at ?? pending.activation_started_at ?? '',
+  );
+  // Production uses an absolute transaction deadline, so restarting a killed
+  // monitor cannot extend an unhealthy target indefinitely. Tests may inject a
+  // short relative timeout for deterministic clocks.
+  const deadline = injected.healthTimeoutMs === undefined && Number.isFinite(verificationStartedAt)
+    ? verificationStartedAt + timeoutMs
+    : now() + timeoutMs;
+  let consecutive = 0;
+  const writeHeartbeat = () => writeJsonAtomic(paths.monitorHeartbeat, {
+    transaction_id: transactionId,
+    pid: monitorPid,
+    updated_at: now(),
+  });
+  writeHeartbeat();
+  while (now() < deadline) {
+    const rollbackResult = await rollbackIfRequested();
+    if (rollbackResult) return rollbackResult;
+    pending = validateTransaction(readJson(paths.pending));
+    if (!ownsVerification(pending)) {
+      rmSync(paths.monitorHeartbeat, { force: true });
+      return 'superseded';
+    }
+    writeHeartbeat();
+    const health = await probe(rootDir).catch(() => null);
+    const daemonStatus = await readStatus(rootDir).catch(() => null);
+    if (healthMatches(health, pending, daemonStatus)) {
+      consecutive += 1;
+      if (consecutive >= 2) {
+        try {
+          const rollbackBeforeCommit = await rollbackIfRequested();
+          if (rollbackBeforeCommit) return rollbackBeforeCommit;
+          pending = validateTransaction(readJson(paths.pending));
+          if (!ownsVerification(pending)) {
+            rmSync(paths.monitorHeartbeat, { force: true });
+            return 'superseded';
+          }
+          await installActiveGuardian(rootDir, pending, injected);
+          const rollbackAfterGuardianInstall = await rollbackIfRequested();
+          if (rollbackAfterGuardianInstall) return rollbackAfterGuardianInstall;
+          updatePending(paths.pending, {
+            phase: 'healthy',
+            guardian_pid: undefined,
+            guardian_started_at: undefined,
+          }, fence);
+          const rollbackAfterCommit = await rollbackIfRequested();
+          if (rollbackAfterCommit) return rollbackAfterCommit;
+          rmSync(paths.monitorHeartbeat, { force: true });
+          appendLog(paths.log, `target ${pending.target_version} passed exact health checks`);
+          return 'healthy';
+        } catch (error) {
+          consecutive = 0;
+          appendLog(paths.log, `failed to refresh package-out guardian: ${error instanceof Error ? error.message : String(error)}`);
+        }
+      }
+    } else {
+      consecutive = 0;
+    }
+    await wait(HEALTH_POLL_MS);
+  }
+  pending = validateTransaction(readJson(paths.pending));
+  if (!ownsVerification(pending)) {
+    rmSync(paths.monitorHeartbeat, { force: true });
+    return 'superseded';
+  }
+  updatePending(paths.pending, {
+    phase: 'rolling_back',
+    error_code: 'STARTUP_CRASH',
+  }, fence);
+  pending = validateTransaction(readJson(paths.pending));
+  appendLog(paths.log, `target ${pending.target_version} failed health verification; rolling back`);
+  try {
+    await restorePreviousVersion(rootDir, pending, injected);
+    rmSync(paths.monitorHeartbeat, { force: true });
+    return 'rolled_back';
+  } catch (error) {
+    updatePending(paths.pending, {
+      phase: 'failed',
+      error_code: 'ROLLBACK_FAILED',
+      error_msg: error instanceof Error ? error.message : String(error),
+    });
+    appendLog(paths.log, `offline rollback failed: ${error instanceof Error ? error.message : String(error)}`);
+    throw error;
+  }
+}
+
+/**
+ * 找出跑指定 wrapper 脚本的 wscript 进程。wmic 在 Win11 上已被移除，回落 CIM。
+ */
+function findWrapperPids(wrapperFileName) {
+  const parse = (text) => String(text || '')
+    .split(/\r?\n/)
+    .map((line) => Number.parseInt(line.trim(), 10))
+    .filter((pid) => Number.isFinite(pid) && pid > 0);
+  try {
+    return parse(execFileSync(
+      'wmic',
+      ['process', 'where', `CommandLine like '%${wrapperFileName}%'`, 'get', 'ProcessId'],
+      { encoding: 'utf8', timeout: 15_000, windowsHide: true },
+    ));
+  } catch { /* fall through to CIM */ }
+  try {
+    const script = `Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -like '*${wrapperFileName}*' } | ForEach-Object { $_.ProcessId }`;
+    return parse(execFileSync(
+      `${process.env.SystemRoot || 'C:\\Windows'}\\System32\\WindowsPowerShell\\v1.0\\powershell.exe`,
+      ['-NoProfile', '-NonInteractive', '-Command', script],
+      { encoding: 'utf8', timeout: 20_000, windowsHide: true },
+    ));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 存量安装的 wrapper 接管。
+ *
+ * 旧 wrapper 是纯 `Do shell.Run daemon Loop`，既不调 guardian 也不注入
+ * GRIX_WRAPPER_SUPERVISED，事务化自升级因此永远被拒。daemon 刷新完磁盘上的
+ * wrapper 后派本流程完成交接：
+ *
+ *   1. 先只杀 wscript 进程本身（不带 /T）。Windows 不级联杀子进程，daemon 因此
+ *      毫发无伤，但旧 wrapper 的 5 秒重启循环就此停下，不会在交接窗口里再拉起
+ *      一个 daemon 和我们抢。
+ *   2. 等 daemon 自己优雅退出。
+ *   3. 拉起刷新后的 wrapper。
+ *
+ * 第 3 步放在 finally：中间任何一步失败都必须把 wrapper 拉回来，否则我们刚亲手
+ * 拆掉了这台机器的自启动监管。
+ */
+async function adoptWindowsWrapper(rootDir, options) {
+  const paths = pathsFor(rootDir);
+  const { wrapperPath, serviceId, daemonPid } = options;
+  if (!wrapperPath || !serviceId) {
+    appendLog(paths.log, 'adopt-wrapper: missing --wrapper or --service-id; nothing to do');
+    return;
+  }
+  // 升级事务在途时 wrapper 归 activate 流程管，这里退开。
+  if (existsSync(paths.pending)) {
+    appendLog(paths.log, 'adopt-wrapper: upgrade transaction in flight; skipping wrapper adoption');
+    return;
+  }
+  let wrapperRestarted = false;
+  try {
+    const wrapperFileName = `${serviceId}-wrapper.vbs`;
+    for (const pid of findWrapperPids(wrapperFileName)) {
+      if (pid === process.pid) continue;
+      // 只杀 wscript 自己：带 /T 会连同它启动的 daemon 一起杀，交接就不再优雅。
+      try { execFileSync('taskkill', ['/PID', String(pid), '/F'], { timeout: 10_000, windowsHide: true }); } catch { /* already gone */ }
+      appendLog(paths.log, `adopt-wrapper: stopped stale wrapper pid=${pid}`);
+    }
+
+    if (daemonPid > 0) {
+      const deadline = Date.now() + ADOPT_WRAPPER_DAEMON_EXIT_TIMEOUT_MS;
+      while (Date.now() < deadline && isPidAlive(daemonPid)) await sleep(500);
+      if (isPidAlive(daemonPid)) {
+        // 不再等下去：没有 wrapper 的机器等于失去自启动监管，宁可让新 wrapper
+        // 拉起的 daemon 通过单例锁把这个赖着不走的旧进程换掉。
+        appendLog(paths.log, `adopt-wrapper: daemon pid=${daemonPid} still alive after timeout; restarting wrapper anyway`);
+      } else {
+        appendLog(paths.log, `adopt-wrapper: daemon pid=${daemonPid} exited`);
+      }
+    }
+  } finally {
+    try {
+      spawn('wscript.exe', ['//B', '//NoLogo', wrapperPath], {
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+      }).unref();
+      wrapperRestarted = true;
+    } catch (error) {
+      appendLog(paths.log, `adopt-wrapper: failed to start refreshed wrapper: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  if (wrapperRestarted) appendLog(paths.log, `adopt-wrapper: started refreshed wrapper ${wrapperPath}`);
+}
+
+async function runCli() {
+  const args = process.argv.slice(2);
+  const mode = args[0] || 'activate';
+  const rootIndex = args.indexOf('--root');
+  const rootDir = rootIndex >= 0 && args[rootIndex + 1]
+    ? resolve(args[rootIndex + 1])
+    : resolve(process.env.GRIX_CONNECTOR_HOME || join(homedir(), '.grix'));
+  const paths = pathsFor(rootDir);
+  const readArg = (name) => {
+    const index = args.indexOf(name);
+    return index >= 0 && args[index + 1] ? args[index + 1] : '';
+  };
+  let lockHandle = await acquireGuardianProcessLock(rootDir);
+  if (!lockHandle && mode === 'monitor') {
+    for (let attempt = 0; attempt < 40 && !lockHandle; attempt++) {
+      await sleep(250);
+      lockHandle = await acquireGuardianProcessLock(rootDir);
+    }
+  }
+  if (!lockHandle) {
+    // POSIX 上互斥用 hash 派生的本地端口，撞上无关服务就永远拿不到锁。
+    // 静默 return 75 会让排查时看不出任何线索，至少留一行。
+    appendLog(paths.log, `${mode}: another guardian holds the process lock (or its endpoint is occupied); giving up this round`);
+    return 75;
+  }
+  try {
+    if (mode === 'monitor') await monitorWindowsUpgrade(rootDir);
+    else if (mode === 'adopt-wrapper') {
+      await adoptWindowsWrapper(rootDir, {
+        wrapperPath: readArg('--wrapper'),
+        serviceId: readArg('--service-id'),
+        daemonPid: Number.parseInt(readArg('--daemon-pid'), 10) || 0,
+      });
+    } else await activateWindowsUpgrade(rootDir, { wrapperHandoffComplete: args.includes('--wrapper-handoff') });
+    return 0;
+  } catch (error) {
+    appendLog(paths.log, `${mode} failed: ${error instanceof Error ? error.stack || error.message : String(error)}`);
+    return 1;
+  } finally {
+    await releaseGuardianProcessLock(lockHandle);
+  }
+}
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url));
+if (isMain) process.exitCode = await runCli();