@whobot/cli-test 0.0.0-stage → 0.0.2

package/bin/install.mjs

@@ -0,0 +1,1878 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import {
+  accessSync,
+  constants,
+  createWriteStream,
+  openSync,
+  fsyncSync,
+  closeSync,
+  realpathSync,
+} from "node:fs";
+import fs from "node:fs/promises";
+import http from "node:http";
+import https from "node:https";
+import os from "node:os";
+import path from "node:path";
+import tls from "node:tls";
+import { fileURLToPath } from "node:url";
+import { gunzipSync, inflateRawSync } from "node:zlib";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const pkgRoot = path.resolve(here, "..");
+const bootstrap = JSON.parse(
+  await fs.readFile(path.join(pkgRoot, "bootstrap.json"), "utf8"),
+);
+const pkg = JSON.parse(
+  await fs.readFile(path.join(pkgRoot, "package.json"), "utf8"),
+);
+
+// The release profile (ADR-0015) is baked into the published package: its npm
+// entry command is the single package.json bin key and its CLI home directory
+// is bootstrap.homeName.
+const COMMAND = cliCommand(pkg);
+const HOME_NAME = cliHomeName(bootstrap);
+
+function cliCommand(p) {
+  const names = Object.keys(p.bin || {});
+  if (names.length !== 1 || !/^whobot(-[a-z]+)?$/.test(names[0])) {
+    throw new Error(`package.json must register exactly one whobot command, got ${JSON.stringify(p.bin)}`);
+  }
+  return names[0];
+}
+
+function cliHomeName(b) {
+  const name = String(b.homeName || "");
+  if (!/^\.whobot(-[a-z]+)?-cli$/.test(name)) {
+    throw new Error(`bootstrap.json homeName is missing or invalid: ${JSON.stringify(b.homeName)}`);
+  }
+  return name;
+}
+
+const OS_MAP = { darwin: "darwin", linux: "linux", win32: "windows" };
+const ARCH_MAP = { x64: "amd64", arm64: "arm64" };
+const BINARY_UNIX = COMMAND;
+const BINARY_WINDOWS = `${COMMAND}.exe`;
+const ALLOWED_FILES = new Set([
+  BINARY_UNIX,
+  BINARY_WINDOWS,
+  "LICENSE",
+  "LICENSE.md",
+  "LICENSE.txt",
+  "NOTICE",
+  "NOTICE.md",
+  "NOTICE.txt",
+  "README",
+  "README.md",
+  "README.txt",
+]);
+const DIST_TAGS = new Set(["latest", "next", "canary", "stable", "intranet", "*"]);
+const SEMVER =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const STABLE_TARGET =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const SHA256_HEX = /^[0-9a-fA-F]{64}$/;
+const DOWNLOAD_TIMEOUT_MS = 60_000;
+const SMOKE_TIMEOUT_MS = 15_000;
+const ZIP_EOCD_SIZE = 22;
+const ZIP_CENTRAL_HEADER_SIZE = 46;
+const ZIP_LOCAL_HEADER_SIZE = 30;
+const ZIP_ENCRYPTED_FLAG = 0x1;
+const ZIP_STRONG_ENCRYPTION_FLAG = 0x40;
+const ZIP64_UINT32 = 0xffffffff;
+
+export class InstallerError extends Error {
+  constructor(message, code = "INTERNAL") {
+    super(message);
+    this.name = "InstallerError";
+    this.code = code;
+  }
+}
+
+function writeJSONFailure(code, message) {
+  const body = {
+    ok: false,
+    error: {
+      code,
+      category: code === "CHANNEL_INVALID" ? "input" : "unavailable",
+      userMessage: code === "CHANNEL_INVALID" ? "安装包的发行渠道信息有误，请重新安装。" : "CLI 更新未完成，已有身份数据已保留。",
+      detail: message,
+      retry: { safe: false },
+    },
+    next: { action: "stop" },
+    meta: {
+      requestId: "req_00000000000000000000000000000000",
+      cli: pkg.version,
+      protocol: 2,
+      notices: [],
+    },
+  };
+  process.stdout.write(`${JSON.stringify(body)}\n`);
+}
+
+function bakedChannel() {
+  const ch = String(bootstrap.channel || "").trim();
+  if (ch !== "intranet" && ch !== "latest") {
+    throw new InstallerError("发行渠道缺失或非法", "CHANNEL_INVALID");
+  }
+  return ch;
+}
+
+function logStderr(message) {
+  process.stderr.write(`${COMMAND}: ${message}\n`);
+}
+
+export function nativeBinaryPath(root = pkgRoot) {
+  const platform = mapPlatform(process.platform, process.arch, bootstrap);
+  return path.join(root, "bin", platform.binary);
+}
+
+async function isRegularFile(p) {
+  try {
+    const st = await fs.stat(p);
+    return st.isFile();
+  } catch {
+    return false;
+  }
+}
+
+export async function ensureNativeBinary(env, { force = false, dest: destOverride, version: versionOverride } = {}) {
+  const version = resolveVersion(undefined, {}, versionOverride || pkg.version);
+  const platform = mapPlatform(process.platform, process.arch, bootstrap);
+  const dest = destOverride || path.join(pkgRoot, "bin", platform.binary);
+  if (!force && (await isRegularFile(dest))) {
+    return dest;
+  }
+  logStderr(`downloading native CLI ${version} for ${platform.os}/${platform.arch}`);
+  const cwd = process.cwd();
+  const smokeHome = String(env.WHOBOT_AGENT_CLI_HOME || "").trim() || cwd;
+  await fs.mkdir(path.dirname(dest), { recursive: true, mode: 0o755 });
+  const smokeStage = path.join(
+    path.dirname(dest),
+    `.${platform.binary}.stage.${process.pid}.${Math.random().toString(16).slice(2)}`,
+  );
+  const base = resolveDownloadBase(env);
+  const work = await makeWorkDir([tmpDirFromEnv(env), pkgRoot, cwd]);
+  try {
+    const manifest = await fetchManifest(base, version, env);
+    const artifact = selectArtifact(manifest, version, platform, bootstrap);
+    const archivePath = path.join(work, artifact.name);
+    await downloadFile(
+      `${base}/${encodeURIComponent(version)}/${encodeURIComponent(artifact.name)}`,
+      archivePath,
+      artifact.size,
+      artifact.sha256,
+      env,
+    );
+    const archive = await fs.readFile(archivePath);
+    const entries = inspectAndExtract(archive, artifact.name);
+    const stagedBin = selectBinary(entries, platform);
+    await fs.writeFile(smokeStage, stagedBin.body, { mode: 0o755 });
+    await fs.chmod(smokeStage, 0o755);
+    smoke(smokeStage, version, smokeHome, env);
+    await replaceAtomically(smokeStage, dest);
+    smoke(dest, version, smokeHome, env);
+    return dest;
+  } finally {
+    await fs.unlink(smokeStage).catch(() => {});
+    await fs.rm(work, { recursive: true, force: true });
+  }
+}
+
+function isNpxPath(value) {
+  const v = String(value || "");
+  if (!v) {
+    return false;
+  }
+  return (
+    v.includes(`${path.sep}_npx${path.sep}`) ||
+    v.includes("/_npx/") ||
+    v.includes("\\_npx\\") ||
+    v.includes(`${path.sep}.npm${path.sep}_npx`) ||
+    /(?:^|[\\/])_npx(?:[\\/]|$)/.test(v)
+  );
+}
+
+export function shouldSkipPostinstall(env) {
+  const ua = String(env.npm_config_user_agent || "");
+  if (/\bnpx\b/i.test(ua)) {
+    return true;
+  }
+  if (String(env.npm_lifecycle_event || "") === "npx") {
+    return true;
+  }
+  const localPrefix = String(env.npm_config_local_prefix || "");
+  if (isNpxPath(localPrefix) || isNpxPath(pkgRoot)) {
+    return true;
+  }
+  return false;
+}
+
+export async function runPostinstall(env) {
+  if (shouldSkipPostinstall(env)) {
+    logStderr("skipping native download in npx cache");
+    return;
+  }
+  try {
+    await ensureNativeBinary(env, { force: true });
+  } catch (err) {
+    const message = err && err.message ? err.message : String(err);
+    if (/download base is not set/i.test(message)) {
+      logStderr(`${message}; leaving native binary for first command`);
+      return;
+    }
+    throw err;
+  }
+}
+
+export function whichCommand(name, env, ignoreRealpath = "") {
+  const pathEnv = env.PATH || env.Path || "";
+  const exts = process.platform === "win32" ? [".cmd", ".exe", ".bat", ""] : [""];
+  for (const dir of pathEnv.split(path.delimiter)) {
+    if (!dir) {
+      continue;
+    }
+    for (const ext of exts) {
+      const candidate = path.join(dir, name + ext);
+      try {
+        accessSync(candidate, constants.X_OK);
+        if (ignoreRealpath && realpathSync(candidate) === ignoreRealpath) continue;
+        return candidate;
+      } catch {
+        // try next
+      }
+    }
+  }
+  return "";
+}
+
+export function findRuntimeTools(env) {
+  const node = whichCommand("node", env);
+  const npm = whichCommand("npm", env);
+  const npx = whichCommand("npx", env);
+  const missing = [];
+  if (!node) {
+    missing.push("node");
+  }
+  if (!npm) {
+    missing.push("npm");
+  }
+  if (!npx) {
+    missing.push("npx");
+  }
+  return { node: node || process.execPath, npm, npx, missing };
+}
+
+export function runtimeMissingMessage(missing) {
+  return (
+    `missing required tools: ${missing.join(", ")}. ` +
+    `Install Node.js >= 20 from https://nodejs.org (includes npm and npx), then retry. ` +
+    `Not installing system packages or running business commands.`
+  );
+}
+
+export function globalNpmEnv(env) {
+  const out = { ...env };
+  for (const key of Object.keys(out)) {
+    const lower = key.toLowerCase();
+    if (lower === "npm_config_prefix" || lower === "npm_config_global_prefix") {
+      if (isNpxPath(out[key])) {
+        delete out[key];
+      }
+    }
+    if (
+      lower === "npm_config_user_agent" ||
+      lower === "npm_lifecycle_event" ||
+      lower === "npm_lifecycle_script"
+    ) {
+      delete out[key];
+    }
+  }
+  if (isNpxPath(out.NPM_CONFIG_PREFIX)) {
+    delete out.NPM_CONFIG_PREFIX;
+  }
+  out.npm_config_yes = "true";
+  out.npm_config_fund = "false";
+  out.npm_config_audit = "false";
+  out.npm_config_update_notifier = "false";
+  return out;
+}
+
+export function globalWhobotEntry(prefix) {
+  if (process.platform === "win32") {
+    return path.join(prefix, `${COMMAND}.cmd`);
+  }
+  return path.join(prefix, "bin", COMMAND);
+}
+
+function spawnNpm(tools, args, env, timeoutMs) {
+  const opts = {
+    encoding: "utf8",
+    env,
+    timeout: timeoutMs,
+    windowsHide: true,
+    stdio: ["ignore", "pipe", "pipe"],
+  };
+  if (process.platform === "win32") {
+    return spawnSync("cmd.exe", ["/c", "npm", ...args], opts);
+  }
+  return spawnSync(tools.npm, args, opts);
+}
+
+export function readNpmGlobalPrefix(tools, env) {
+  const result = spawnNpm(tools, ["prefix", "-g"], env, 30_000);
+  const prefix = String(result.stdout || "").trim();
+  if (result.error) {
+    throw new InstallerError(`cannot resolve npm global prefix: ${result.error.message}`);
+  }
+  if (result.status !== 0 || prefix === "") {
+    throw new InstallerError(
+      `cannot resolve npm global prefix: ${String(result.stderr || result.stdout || "").trim()}`,
+    );
+  }
+  return prefix;
+}
+
+export function readGlobalPackageVersion(tools, env) {
+  const result = spawnNpm(
+    tools,
+    ["list", "-g", "--depth=0", "--json", pkg.name],
+    env,
+    30_000,
+  );
+  let parsed = {};
+  try {
+    parsed = JSON.parse(result.stdout || "{}");
+  } catch {
+    return null;
+  }
+  const ver = parsed?.dependencies?.[pkg.name]?.version;
+  return ver ? String(ver) : null;
+}
+
+function npmInstallGlobalFrom(tools, spec, env) {
+  const result = spawnNpm(
+    tools,
+    [
+      "install",
+      "-g",
+      "--yes",
+      "--no-fund",
+      "--no-audit",
+      "--foreground-scripts",
+      "--install-links",
+      spec,
+    ],
+    env,
+    120_000,
+  );
+  if (result.error) {
+    throw new InstallerError(`npm install -g failed: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    throw new InstallerError(
+      `npm install -g failed: ${String(result.stderr || result.stdout || "").trim()}`,
+    );
+  }
+}
+
+const CHANNEL_FILE = ".whobot-channel";
+const VERIFY_TIMEOUT_MS = 90_000;
+
+function parseChannelAndForward(argv) {
+  const forwarded = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--channel" || a.startsWith("--channel=")) {
+      throw new InstallerError("发行渠道由发行包内置，不接受 --channel", "CHANNEL_INVALID");
+    }
+    forwarded.push(a);
+  }
+  return { forwarded };
+}
+
+function positionalCommands(argv) {
+  const tokens = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") {
+      continue;
+    }
+    if (a === "-Q" || a === "--global-config" || a === "--channel" || a === "--target-version") {
+      i++;
+      continue;
+    }
+    if (
+      a.startsWith("--global-config=") ||
+      a.startsWith("-Q=") ||
+      a.startsWith("--channel=") ||
+      a.startsWith("-")
+    ) {
+      continue;
+    }
+    tokens.push(a);
+  }
+  return tokens;
+}
+
+export function isUpdateApply(argv) {
+  const cmds = positionalCommands(argv);
+  return cmds.length === 1 && cmds[0] === "update" && argv.some((a) => a === "--yes" || a === "--yes=true");
+}
+
+function confirmedTargetVersion(argv) {
+  const targets = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--target-version") targets.push(argv[++i]);
+    else if (argv[i].startsWith("--target-version=")) targets.push(argv[i].slice("--target-version=".length));
+  }
+  if (targets.length !== 1 || !STABLE_TARGET.test(targets[0] || "")) {
+    throw new InstallerError("请使用更新预览返回的含目标版本的 next.command", "UPDATE_VERIFY_FAILED");
+  }
+  return targets[0];
+}
+
+export function globalPackageDir(prefix, nodeOS = process.platform) {
+  if (nodeOS === "win32") {
+    return path.join(prefix, "node_modules", ...pkg.name.split("/"));
+  }
+  return path.join(prefix, "lib", "node_modules", ...pkg.name.split("/"));
+}
+
+export function packageNativeBinary(prefix, nodeOS = process.platform, nodeArch = process.arch) {
+  const platform = mapPlatform(nodeOS, nodeArch, bootstrap);
+  return path.join(globalPackageDir(prefix, nodeOS), "bin", platform.binary);
+}
+
+export function nativeBackupPath(nativePath) {
+  return `${nativePath}.old`;
+}
+
+async function unlinkIfExists(p) {
+  try {
+    await fs.unlink(p);
+  } catch (err) {
+    if (!err || err.code !== "ENOENT") {
+      throw err;
+    }
+  }
+}
+
+export async function prepareNativeReplace(nativePath, platform = process.platform) {
+  const noop = { restore: async () => {}, discard: async () => {} };
+  if (platform !== "win32") {
+    return noop;
+  }
+  const backup = nativeBackupPath(nativePath);
+  await unlinkIfExists(backup);
+  if (!(await isRegularFile(nativePath))) {
+    return noop;
+  }
+  await fs.rename(nativePath, backup);
+  return {
+    restore: async () => {
+      if (!(await isRegularFile(backup))) {
+        return;
+      }
+      await fs.rm(nativePath, { force: true }).catch(() => {});
+      await fs.rename(backup, nativePath);
+    },
+    discard: async () => {
+      await fs.rm(backup, { force: true }).catch(() => {});
+    },
+  };
+}
+
+export async function recoverNativeBackup(nativePath, platform = process.platform) {
+  if (platform !== "win32") {
+    return;
+  }
+  const backup = nativeBackupPath(nativePath);
+  if (!(await isRegularFile(backup))) {
+    return;
+  }
+  if (!(await isRegularFile(nativePath))) {
+    await fs.rename(backup, nativePath);
+    return;
+  }
+  const result = spawnSync(nativePath, ["version", "--json"], {
+    encoding: "utf8",
+    timeout: 10_000,
+    windowsHide: true,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (!result.error && result.status === 0) {
+    await fs.rm(backup, { force: true }).catch(() => {});
+    return;
+  }
+  await fs.rm(nativePath, { force: true }).catch(() => {});
+  await fs.rename(backup, nativePath);
+}
+
+function channelPath(root) {
+  return path.join(root, CHANNEL_FILE);
+}
+
+async function writeInstallChannel(root, channel) {
+  if (!channel) {
+    return;
+  }
+  await fs.mkdir(root, { recursive: true });
+  await fs.writeFile(channelPath(root), `${channel}\n`, {
+    encoding: "utf8",
+    mode: 0o644,
+  });
+}
+
+async function readInstallChannel(root) {
+  try {
+    return String(await fs.readFile(channelPath(root), "utf8")).trim();
+  } catch {
+    return "";
+  }
+}
+
+function readDistTags(tools, env) {
+  const result = spawnNpm(tools, ["view", pkg.name, "dist-tags", "--json"], env, 30_000);
+  if (result.error) {
+    throw new InstallerError(`cannot resolve npm dist-tags: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    throw new InstallerError(
+      `cannot resolve npm dist-tags for ${pkg.name}: ${String(result.stderr || result.stdout || "").trim()}`,
+    );
+  }
+  try {
+    const parsed = JSON.parse(result.stdout || "{}");
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    throw new InstallerError(`cannot parse npm dist-tags for ${pkg.name}`);
+  }
+}
+
+function rejectExternalChannel(env) {
+  if (String(env.WHOBOT_CLI_CHANNEL || "").trim()) {
+    throw new InstallerError("发行渠道由发行包内置，不接受 WHOBOT_CLI_CHANNEL", "CHANNEL_INVALID");
+  }
+}
+
+function verifyNpmEntryVersion(entry, wantVersion, env) {
+  const result = spawnSync(entry, ["version", "--json"], {
+    encoding: "utf8",
+    env,
+    timeout: VERIFY_TIMEOUT_MS,
+    windowsHide: true,
+    stdio: ["ignore", "pipe", "pipe"],
+    shell: process.platform === "win32" && /\.(cmd|bat)$/i.test(entry),
+  });
+  const combined = `${result.stdout || ""}\n${result.stderr || ""}`;
+  if (result.error) {
+    throw new InstallerError(
+      `in-package binary cannot be executed: ${result.error.message}`,
+      "UPDATE_VERIFY_FAILED",
+    );
+  }
+  if (result.status !== 0) {
+    if (/cannot be executed|not executable/i.test(combined)) {
+      throw new InstallerError(
+        combined.trim() || `in-package binary cannot be executed: ${entry}`,
+      );
+    }
+    if (/protocol/i.test(combined)) {
+      throw new InstallerError(combined.trim() || "protocol incompatible");
+    }
+    if (/checksum/i.test(combined)) {
+      throw new InstallerError(combined.trim() || "checksum mismatch");
+    }
+    if (/not installed|CLI_NOT_INSTALLED/i.test(combined)) {
+      throw new InstallerError(combined.trim());
+    }
+    throw new InstallerError(
+      `version --json verification failed: ${String(result.stderr || result.stdout || "").trim()}`,
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(String(result.stdout || "").trim());
+  } catch {
+    throw new InstallerError("version --json verification did not emit JSON");
+  }
+  if (parsed.ok !== true) {
+    throw new InstallerError("version --json verification ok=false");
+  }
+  if (parsed.meta?.protocol !== 2) {
+    throw new InstallerError(
+      `protocol ${parsed.meta?.protocol} is not 2`,
+    );
+  }
+  if (parsed.data?.version !== wantVersion) {
+    throw new InstallerError(
+      `installed version ${parsed.data?.version} does not match ${wantVersion}`,
+    );
+  }
+  return parsed;
+}
+
+async function repairAndVerifyNative(native, version, env) {
+  try {
+    verifyNpmEntryVersion(native, version, env);
+  } catch {
+    // npm registration can survive a missing, damaged or stale native file.
+    // Restore that exact package version, then verify the real executable.
+    await ensureNativeBinary(env, { force: true, dest: native, version });
+    verifyNpmEntryVersion(native, version, env);
+  }
+}
+
+export async function verifyInstalledCLI(tools, npmEnv, prefix, version, env, ignoreLauncher = "") {
+  const registered = readGlobalPackageVersion(tools, npmEnv);
+  if (registered !== version) {
+    throw new InstallerError(`npm registered version ${registered} does not match ${version}`, "UPDATE_VERIFY_FAILED");
+  }
+  const native = packageNativeBinary(prefix);
+  await repairAndVerifyNative(native, version, env);
+  const entry = globalWhobotEntry(prefix);
+  verifyNpmEntryVersion(entry, version, env);
+  const onPath = whichCommand(COMMAND, env, ignoreLauncher);
+  if (onPath && realpathSync(onPath) !== realpathSync(entry)) {
+    throw new InstallerError(`PATH resolves ${COMMAND} to another entry: ${onPath}; remove or replace it before using ${entry}`, "UPDATE_VERIFY_FAILED");
+  }
+  return { entry, native };
+}
+
+function parseExplicitInstallArgs(argv) {
+  const { forwarded } = parseChannelAndForward(argv);
+  for (const a of forwarded) {
+    if (a.startsWith("-")) {
+      throw new InstallerError(`unknown flag ${a}`);
+    }
+    throw new InstallerError(`unexpected argument ${a}`);
+  }
+}
+
+export async function runExplicitInstall(argv, env) {
+  rejectExternalChannel(env);
+  parseExplicitInstallArgs(argv);
+  bakedChannel();
+  if (!STABLE_TARGET.test(pkg.version)) {
+    throw new InstallerError("安装目标必须是完整的稳定 SemVer 版本", "UPDATE_VERIFY_FAILED");
+  }
+  const tools = findRuntimeTools(env);
+  if (tools.missing.length) {
+    throw new InstallerError(runtimeMissingMessage(tools.missing));
+  }
+  const npmEnv = globalNpmEnv(env);
+  const prefix = readNpmGlobalPrefix(tools, npmEnv);
+  const entry = globalWhobotEntry(prefix);
+  const registered = readGlobalPackageVersion(tools, npmEnv);
+  logStderr(`install target ${pkg.name}@${pkg.version} (channel ${bakedChannel()})`);
+  // Validate with the new reader before replacing the installed program.
+  // Published v1 updaters cannot validate the v2 output protocol.
+  const staging = await fs.mkdtemp(path.join(os.tmpdir(), "whobot-install-preflight-"));
+  const stagedNative = path.join(staging, path.basename(packageNativeBinary(prefix)));
+  const updateArgs = ["update", "--yes", "--target-version", pkg.version];
+  let prepared;
+  try {
+    await ensureNativeBinary(env, { force: true, dest: stagedNative, version: pkg.version });
+    verifyNpmEntryVersion(stagedNative, pkg.version, env);
+    runInstallPhase(stagedNative, ["update", "check-install", "--previous-binary", packageNativeBinary(prefix)], env, "binding", registered);
+    runInstallPhase(stagedNative, updateArgs, env, "preflight", registered);
+    prepared = await prepareNativeReplace(packageNativeBinary(prefix));
+    if (registered !== pkg.version || !(await pathExists(entry))) {
+      logStderr(registered ? `installing global ${pkg.name}@${pkg.version} (was ${registered})` : `installing global ${pkg.name}@${pkg.version}`);
+      npmInstallGlobalFrom(tools, pkgRoot, npmEnv);
+    }
+    // Ignore this npx cache launcher only, not other stale host PATH entries.
+    const ignoreLauncher = isNpxPath(pkgRoot) ? realpathSync(path.join(pkgRoot, "bin", "run.mjs")) : "";
+    const installed = await verifyInstalledCLI(tools, npmEnv, prefix, pkg.version, env, ignoreLauncher);
+    runInstallPhase(installed.native, updateArgs, env, "verify", registered);
+    await prepared.discard();
+    logStderr(`CLI 软件安装已完成；请更新 Skill 至对应渠道最新版，重载宿主或新建任务后重新预检。v2 后续更新请运行 ${COMMAND} update，并执行确认卡中的命令。`);
+    return entry;
+  } catch (err) {
+    if (prepared) await prepared.restore();
+    throw err;
+  } finally {
+    await fs.rm(staging, { recursive: true, force: true });
+  }
+}
+
+function runInstallPhase(native, args, env, phase, previous, wantVersion = pkg.version) {
+  const result = spawnSync(native, args, {
+    encoding: "utf8",
+    env: { ...env, WHOBOT_UPDATE_PHASE: phase, WHOBOT_UPDATE_LOCK_PID: String(process.pid), WHOBOT_UPDATE_PREVIOUS_VERSION: previous || "" },
+    windowsHide: true,
+  });
+  if (result.error || result.signal) throw new InstallerError(`安装${phase}检查未完成: ${result.error?.message || result.signal}`, "UPDATE_VERIFY_FAILED");
+  let response;
+  try { response = JSON.parse(result.stdout); } catch { throw new InstallerError("安装检查没有返回合法 JSON", "UPDATE_VERIFY_FAILED"); }
+  if (result.status !== 0 || !response.ok || response.next?.action !== "done" || response.data?.installedVersion !== wantVersion) {
+    throw new InstallerError(`安装未完成: ${response.error?.code || "UPDATE_VERIFY_FAILED"} ${response.error?.detail || response.error?.userMessage || "目标程序未通过验收"}；请按上述原因处理后重试，不要删除客户端安装身份。`, "UPDATE_VERIFY_FAILED");
+  }
+  return response;
+}
+
+export async function runExplicitUpdate(argv, env) {
+  rejectExternalChannel(env);
+  const { forwarded } = parseChannelAndForward(argv);
+  const tools = findRuntimeTools(env);
+  if (tools.missing.length) {
+    throw new InstallerError(runtimeMissingMessage(tools.missing));
+  }
+  const npmEnv = globalNpmEnv(env);
+  const prefix = readNpmGlobalPrefix(tools, npmEnv);
+  const entry = globalWhobotEntry(prefix);
+  const previous = readGlobalPackageVersion(tools, npmEnv);
+  const channel = bakedChannel();
+  const targetVersion = confirmedTargetVersion(argv);
+  const spec = `${pkg.name}@${targetVersion}`;
+  const replacing = previous !== targetVersion || !(await pathExists(entry));
+  const native = packageNativeBinary(prefix);
+  const staging = await fs.mkdtemp(path.join(os.tmpdir(), "whobot-update-target-"));
+  let prepared;
+  try {
+    const targetNative = path.join(staging, path.basename(native));
+    await ensureNativeBinary(env, { force: true, dest: targetNative, version: targetVersion });
+    const checkArgs = ["update", "check-install", "--previous-binary", native];
+    for (let i = 0; i < argv.length; i++) {
+      if (argv[i] === "--global-config" || argv[i] === "-Q") checkArgs.push(argv[i], argv[++i]);
+      else if (argv[i].startsWith("--global-config=") || argv[i].startsWith("-Q=")) checkArgs.push(argv[i]);
+    }
+    runInstallPhase(targetNative, checkArgs, env, "binding", previous, targetVersion);
+    prepared = replacing ? await prepareNativeReplace(native) : { restore: async () => {}, discard: async () => {} };
+    if (replacing) {
+      logStderr(
+        previous
+          ? `updating global ${spec} to ${targetVersion} (was ${previous})`
+          : `installing global ${spec} (${targetVersion})`,
+      );
+      npmInstallGlobalFrom(tools, spec, npmEnv);
+    } else {
+      logStderr(`global ${spec} already ${targetVersion}`);
+    }
+    if (!(await pathExists(entry))) {
+      throw new InstallerError(`global command entry is missing: ${entry}`);
+    }
+    await verifyInstalledCLI(tools, npmEnv, prefix, targetVersion, env);
+    await prepared.discard();
+    return {
+      entry,
+      native,
+      forwarded,
+      previous: previous || "",
+      installedVersion: targetVersion,
+      channel,
+    };
+  } catch (err) {
+    if (prepared) await prepared.restore();
+    throw err;
+  } finally {
+    await fs.rm(staging, { recursive: true, force: true });
+  }
+}
+
+function launcherExitCode(code) {
+  if (code === "CHANNEL_INVALID") {
+    return 2;
+  }
+  return 7;
+}
+
+function reportNativeFailure(dest, spawnErr, { jsonFailure = false } = {}) {
+  const message = spawnErr
+    ? `in-package binary cannot be executed: ${spawnErr.message}`
+    : `in-package binary cannot be executed: ${dest}`;
+  if (jsonFailure) {
+    writeJSONFailure("UPDATE_VERIFY_FAILED", message);
+    process.exitCode = 7;
+  } else {
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+  }
+}
+
+export function spawnNative(dest, argv, env, { jsonFailure = false } = {}) {
+  try {
+    accessSync(dest, constants.X_OK);
+  } catch {
+    reportNativeFailure(dest, null, { jsonFailure });
+    return;
+  }
+  const result = spawnSync(dest, argv, {
+    stdio: "inherit",
+    env,
+    windowsHide: false,
+  });
+  if (result.error) {
+    reportNativeFailure(dest, result.error, { jsonFailure });
+    return;
+  }
+  if (result.signal) {
+    process.kill(process.pid, result.signal);
+    return;
+  }
+  process.exit(result.status ?? 1);
+}
+
+export async function runWhobot(argv, env) {
+  if (argv[0] === "install") {
+    try {
+      const entry = await runExplicitInstall(argv.slice(1), env);
+      process.stdout.write(`${entry}\n`);
+      process.exitCode = 0;
+    } catch (err) {
+      process.stderr.write(`${err && err.message ? err.message : err}\n`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+  await recoverNativeBackup(nativeBinaryPath(pkgRoot));
+  if (isUpdateApply(argv)) {
+    try {
+      rejectExternalChannel(env);
+      parseChannelAndForward(argv);
+      confirmedTargetVersion(argv);
+      let currentNative = nativeBinaryPath(pkgRoot);
+      let preflightDir;
+      let pre;
+      try {
+        try {
+          verifyNpmEntryVersion(currentNative, pkg.version, env);
+        } catch {
+          // A broken current program cannot check activity. Run a verified
+          // copy from temporary storage without replacing the installed file.
+          preflightDir = await fs.mkdtemp(path.join(os.tmpdir(), "whobot-preflight-"));
+          currentNative = path.join(preflightDir, path.basename(currentNative));
+          await ensureNativeBinary(env, { force: true, dest: currentNative, version: pkg.version });
+        }
+        pre = spawnSync(currentNative, argv, {
+          encoding: "utf8",
+          env: {
+            ...env,
+            WHOBOT_UPDATE_PHASE: "preflight",
+            WHOBOT_UPDATE_LOCK_PID: String(process.pid),
+          },
+          windowsHide: false,
+        });
+      } finally {
+        if (preflightDir) await fs.rm(preflightDir, { recursive: true, force: true });
+      }
+      if (pre.stderr) {
+        process.stderr.write(pre.stderr);
+      }
+      if (pre.error || pre.signal) {
+        throw new InstallerError(`更新前检查未完成: ${pre.error?.message || pre.signal}`, "UPDATE_VERIFY_FAILED");
+      }
+      if (pre.status !== 0) {
+        if (pre.stdout) {
+          process.stdout.write(pre.stdout);
+        }
+        process.exitCode = pre.status ?? 1;
+        return;
+      }
+      const preflight = JSON.parse(pre.stdout);
+      if (!preflight.ok || preflight.data?.installedVersion !== pkg.version || preflight.next?.action !== "done") {
+        throw new InstallerError("更新前检查没有确认可以替换程序", "UPDATE_VERIFY_FAILED");
+      }
+      const updated = await runExplicitUpdate(argv, env);
+      spawnNative(
+        updated.native,
+        updated.forwarded,
+        {
+          ...env,
+          WHOBOT_UPDATE_PREVIOUS_VERSION: updated.previous,
+          WHOBOT_UPDATE_PHASE: "verify",
+          WHOBOT_UPDATE_LOCK_PID: String(process.pid),
+        },
+        { jsonFailure: true },
+      );
+    } catch (err) {
+      const code = err?.code === "CHANNEL_INVALID" ? "CHANNEL_INVALID" : "UPDATE_VERIFY_FAILED";
+      const message = err && err.message ? err.message : String(err);
+      writeJSONFailure(code, message);
+      process.stderr.write(`${message}\n`);
+      process.exitCode = launcherExitCode(code);
+    }
+    return;
+  }
+  let dest;
+  try {
+    dest = await ensureNativeBinary(env);
+  } catch (err) {
+    const message = err && err.message ? err.message : String(err);
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  spawnNative(dest, argv, env);
+}
+
+export async function runInstall(argv, env) {
+  const args = parseArgs(argv);
+  const version = resolveVersion(args.version, env, pkg.version);
+  const platform = mapPlatform(process.platform, process.arch, bootstrap);
+  const cwd = process.cwd();
+  const home = await resolveInstallHome(env, platform, cwd);
+  const dest = path.join(home, "bin", platform.binary);
+  const smokeStage = path.join(
+    path.dirname(dest),
+    `.${platform.binary}.stage.${process.pid}.${Math.random().toString(16).slice(2)}`,
+  );
+  const base = resolveDownloadBase(env);
+  const work = await makeWorkDir([tmpDirFromEnv(env), home, cwd]);
+  try {
+    const manifest = await fetchManifest(base, version, env);
+    const artifact = selectArtifact(manifest, version, platform, bootstrap);
+    const archivePath = path.join(work, artifact.name);
+    await downloadFile(
+      `${base}/${encodeURIComponent(version)}/${encodeURIComponent(artifact.name)}`,
+      archivePath,
+      artifact.size,
+      artifact.sha256,
+      env,
+    );
+    const archive = await fs.readFile(archivePath);
+    const entries = inspectAndExtract(archive, artifact.name);
+    const stagedBin = selectBinary(entries, platform);
+    await fs.writeFile(smokeStage, stagedBin.body, { mode: 0o755 });
+    await fs.chmod(smokeStage, 0o755);
+    smoke(smokeStage, version, home, env);
+    await replaceAtomically(smokeStage, dest);
+    smoke(dest, version, home, env);
+    await fs.writeFile(path.join(home, ".installer-managed"), `npx ${pkg.name}\n`, {
+      encoding: "utf8",
+      mode: 0o644,
+    });
+    return dest;
+  } finally {
+    await fs.unlink(smokeStage).catch(() => {});
+    await fs.rm(work, { recursive: true, force: true });
+  }
+}
+
+export function parseArgs(argv) {
+  let command = "";
+  let version;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--version") {
+      version = argv[++i];
+      if (version === undefined) {
+        throw new InstallerError("missing value for --version");
+      }
+      continue;
+    }
+    if (a.startsWith("--version=")) {
+      version = a.slice("--version=".length);
+      continue;
+    }
+    if (a.startsWith("-")) {
+      throw new InstallerError(`unknown flag ${a}`);
+    }
+    if (!command) {
+      command = a;
+      continue;
+    }
+    throw new InstallerError(`unexpected argument ${a}`);
+  }
+  if (!command) {
+    command = "install";
+  }
+  if (command !== "install") {
+    throw new InstallerError(`unknown command ${command}`);
+  }
+  return { command, version };
+}
+
+export function resolveVersion(flagVersion, env, packageVersion) {
+  const raw = firstNonEmpty(flagVersion, env.WHOBOT_INSTALLER_VERSION, packageVersion);
+  if (raw === undefined) {
+    throw new InstallerError(
+      "installer version is required; automation must pass a concrete SemVer (not latest)",
+    );
+  }
+  const v = String(raw).trim();
+  if (v === "") {
+    throw new InstallerError(
+      "installer version is required; automation must pass a concrete SemVer (not latest)",
+    );
+  }
+  if (DIST_TAGS.has(v.toLowerCase())) {
+    throw new InstallerError(
+      `refusing dist-tag ${v}; automation must use a concrete installer SemVer`,
+    );
+  }
+  if (!SEMVER.test(v)) {
+    throw new InstallerError(`invalid installer version ${v}; expected concrete SemVer`);
+  }
+  return v;
+}
+
+export function mapPlatform(nodeOS, nodeArch, known) {
+  const osName = OS_MAP[nodeOS];
+  const arch = ARCH_MAP[nodeArch];
+  if (!osName || !known.knownOs.includes(osName)) {
+    throw new InstallerError(`unsupported OS ${nodeOS}`);
+  }
+  if (!arch || !known.knownArch.includes(arch)) {
+    throw new InstallerError(`unsupported CPU ${nodeArch}`);
+  }
+  return {
+    os: osName,
+    arch,
+    binary: osName === "windows" ? BINARY_WINDOWS : BINARY_UNIX,
+  };
+}
+
+export function resolveHome(env, platform) {
+  const explicit = String(env.WHOBOT_AGENT_CLI_HOME || "").trim();
+  if (explicit) {
+    return path.resolve(explicit);
+  }
+  const home = lookupUserHome(env, platform);
+  if (!home) {
+    return HOME_NAME;
+  }
+  return path.join(home, HOME_NAME);
+}
+
+function lookupUserHome(env, platform) {
+  if (platform?.os === "windows") {
+    for (const key of ["USERPROFILE", "HOME"]) {
+      const v = String(env[key] || "").trim();
+      if (v) {
+        return v;
+      }
+    }
+    const drive = String(env.HOMEDRIVE || "").trim();
+    const homepath = env.HOMEPATH;
+    if (drive && String(homepath || "").trim()) {
+      return drive + homepath;
+    }
+  }
+  try {
+    const home = String(os.homedir() || "").trim();
+    return home;
+  } catch {
+    return "";
+  }
+}
+
+function tmpDirFromEnv(env) {
+  for (const key of ["TMPDIR", "TEMP", "TMP"]) {
+    const v = String(env[key] || "").trim();
+    if (v) {
+      return v;
+    }
+  }
+  return os.tmpdir();
+}
+
+async function dirWritable(dir) {
+  const probe = path.join(
+    dir,
+    `.whobot-write-probe.${process.pid}.${Math.random().toString(16).slice(2)}`,
+  );
+  try {
+    await fs.mkdir(dir, { recursive: true, mode: 0o755 });
+    await fs.writeFile(probe, "ok");
+    await fs.unlink(probe);
+    return true;
+  } catch {
+    await fs.unlink(probe).catch(() => {});
+    return false;
+  }
+}
+
+async function pathExists(p) {
+  try {
+    await fs.stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function resolveInstallHome(env, platform, cwd) {
+  const preferred = resolveHome(env, platform);
+  const dest = path.join(preferred, "bin", platform.binary);
+  const destExists = await pathExists(dest);
+  if (destExists || (await dirWritable(path.join(preferred, "bin")))) {
+    try {
+      return await fs.realpath(preferred);
+    } catch {
+      return path.resolve(preferred);
+    }
+  }
+  const fallback = path.resolve(cwd, HOME_NAME);
+  if (await dirWritable(path.join(fallback, "bin"))) {
+    return await fs.realpath(fallback);
+  }
+  throw new InstallerError(
+    `cannot write CLI Home ${preferred} or workspace fallback ${fallback}`,
+  );
+}
+
+export async function makeWorkDir(candidates) {
+  const errors = [];
+  const seen = new Set();
+  for (const root of candidates) {
+    if (!root) {
+      continue;
+    }
+    const resolved = path.resolve(root);
+    if (seen.has(resolved)) {
+      continue;
+    }
+    seen.add(resolved);
+    try {
+      await fs.mkdir(resolved, { recursive: true, mode: 0o755 });
+      return await fs.mkdtemp(path.join(resolved, "whobot-cli-installer-"));
+    } catch (err) {
+      errors.push(`${resolved}: ${err && err.message ? err.message : err}`);
+    }
+  }
+  throw new InstallerError(
+    `no writable directory for installer temp files (${errors.join("; ")})`,
+  );
+}
+
+function resolveDownloadBase(env) {
+  const override = String(env.WHOBOT_CLI_DOWNLOAD_BASE || "").trim();
+  const raw = override || String(bootstrap.downloadBase || "").trim();
+  if (!raw) {
+    throw new InstallerError(
+      "download base is not set; set WHOBOT_CLI_DOWNLOAD_BASE or bootstrap.json downloadBase",
+    );
+  }
+  return raw.replace(/\/+$/, "");
+}
+
+async function fetchManifest(base, version, env) {
+  const url = `${base}/${encodeURIComponent(version)}/manifest.json`;
+  const got = await httpGet(url, env, {});
+  let man;
+  try {
+    man = JSON.parse(got.body.toString("utf8"));
+  } catch {
+    throw new InstallerError("manifest is not valid JSON");
+  }
+  if (man.schemaVersion !== bootstrap.schemaVersion) {
+    throw new InstallerError(
+      `unknown manifest schemaVersion ${man.schemaVersion}; expected ${bootstrap.schemaVersion}`,
+    );
+  }
+  if (man.version !== version) {
+    throw new InstallerError(
+      `manifest version ${man.version} does not match requested ${version}`,
+    );
+  }
+  if (!Array.isArray(man.artifacts)) {
+    throw new InstallerError("manifest artifacts must be an array");
+  }
+  return man;
+}
+
+export function selectArtifact(manifest, version, platform, known) {
+  const seenNames = new Set();
+  const seenPlat = new Set();
+  let match;
+  for (const raw of manifest.artifacts) {
+    const art = normalizeArtifact(raw, known);
+    if (seenNames.has(art.name)) {
+      throw new InstallerError(`duplicate artifact name ${art.name}`);
+    }
+    seenNames.add(art.name);
+    const key = `${art.os}/${art.arch}`;
+    if (seenPlat.has(key)) {
+      throw new InstallerError(`duplicate artifact platform ${key}`);
+    }
+    seenPlat.add(key);
+    const expected = archiveFileName(version, art.os, art.arch);
+    if (art.name !== expected) {
+      throw new InstallerError(`unexpected artifact name ${art.name}`);
+    }
+    if (art.os === platform.os && art.arch === platform.arch) {
+      match = art;
+    }
+  }
+  if (!match) {
+    throw new InstallerError(
+      `no artifact for ${platform.os}/${platform.arch} in manifest`,
+    );
+  }
+  return match;
+}
+
+function normalizeArtifact(raw, known) {
+  if (!raw || typeof raw !== "object") {
+    throw new InstallerError("invalid artifact entry");
+  }
+  const osName = String(raw.os || "");
+  const arch = String(raw.arch || "");
+  if (!known.knownOs.includes(osName)) {
+    throw new InstallerError(`unknown artifact OS ${osName}`);
+  }
+  if (!known.knownArch.includes(arch)) {
+    throw new InstallerError(`unknown artifact arch ${arch}`);
+  }
+  const name = String(raw.name || raw.filename || "");
+  if (name === "" || name.includes("/") || name.includes("\\") || name.includes("..")) {
+    throw new InstallerError(`illegal artifact name ${name}`);
+  }
+  const sha = raw.sha256;
+  if (sha === undefined || sha === null || String(sha).trim() === "") {
+    throw new InstallerError("missing checksum");
+  }
+  if (!SHA256_HEX.test(String(sha))) {
+    throw new InstallerError(`invalid checksum for ${name}`);
+  }
+  const size = raw.size;
+  if (!Number.isInteger(size) || size <= 0) {
+    throw new InstallerError(`invalid size for ${name}`);
+  }
+  return { os: osName, arch, name, sha256: String(sha).toLowerCase(), size };
+}
+
+function archiveFileName(version, osName, arch) {
+  const ext = osName === "windows" ? ".zip" : ".tar.gz";
+  return `${COMMAND}_${version}_${osName}_${arch}${ext}`;
+}
+
+async function downloadFile(url, dest, expectedSize, expectedSHA, env) {
+  const got = await httpGet(url, env, { destFile: dest, expectedSize });
+  if (got.sha256 !== expectedSHA) {
+    throw new InstallerError(
+      `checksum mismatch: got ${got.sha256} want ${expectedSHA}`,
+    );
+  }
+}
+
+export function inspectAndExtract(bytes, filename) {
+  let entries;
+  if (filename.endsWith(".tar.gz")) {
+    entries = readTarGz(bytes);
+  } else if (filename.endsWith(".zip")) {
+    entries = readZip(bytes);
+  } else {
+    throw new InstallerError(`unsupported archive ${filename}`);
+  }
+  validateEntries(entries);
+  return entries;
+}
+
+function validateEntries(entries) {
+  const seen = new Set();
+  let hasBinary = false;
+  for (const e of entries) {
+    const clean = inspectName(e.name);
+    if (isScript(clean)) {
+      throw new InstallerError(`archive script ${e.name}`);
+    }
+    if (!ALLOWED_FILES.has(clean)) {
+      throw new InstallerError(`unexpected archive file ${e.name}`);
+    }
+    if (seen.has(clean)) {
+      throw new InstallerError(`duplicate archive name ${e.name}`);
+    }
+    seen.add(clean);
+    if (clean === BINARY_UNIX || clean === BINARY_WINDOWS) {
+      hasBinary = true;
+    }
+  }
+  if (!hasBinary) {
+    throw new InstallerError("missing expected binary");
+  }
+}
+
+export function inspectName(raw) {
+  let n = String(raw).replaceAll("\\", "/");
+  if (n.startsWith("./")) {
+    n = n.slice(2);
+  }
+  if (n === "" || n === ".") {
+    throw new InstallerError(`unexpected archive file ${raw}`);
+  }
+  if (n.startsWith("/")) {
+    throw new InstallerError(`path traversal ${raw}`);
+  }
+  const parts = n.split("/");
+  for (const p of parts) {
+    if (p === "..") {
+      throw new InstallerError(`path traversal ${raw}`);
+    }
+  }
+  if (parts.length !== 1) {
+    throw new InstallerError(`unexpected archive file ${raw}`);
+  }
+  if (parts[0].includes(":")) {
+    throw new InstallerError(`path traversal ${raw}`);
+  }
+  return parts[0];
+}
+
+function isScript(name) {
+  const lower = name.toLowerCase();
+  return lower.endsWith(".sh") || lower.endsWith(".ps1") || lower.endsWith(".bat");
+}
+
+function selectBinary(entries, platform) {
+  const found = entries.find((e) => inspectName(e.name) === platform.binary);
+  if (!found) {
+    throw new InstallerError(`archive missing ${platform.binary}`);
+  }
+  return found;
+}
+
+function readTarGz(bytes) {
+  let tar;
+  try {
+    tar = gunzipSync(bytes);
+  } catch (err) {
+    throw new InstallerError(`gzip: ${err.message}`);
+  }
+  return readTar(tar);
+}
+
+function readTar(buf) {
+  const files = [];
+  let offset = 0;
+  while (offset + 512 <= buf.length) {
+    const header = buf.subarray(offset, offset + 512);
+    if (isZeroBlock(header)) {
+      break;
+    }
+    const nameRaw = cstring(header.subarray(0, 100));
+    const prefix = cstring(header.subarray(345, 500));
+    const name = prefix ? `${prefix}/${nameRaw}` : nameRaw;
+    const size = parseOctal(header.subarray(124, 136));
+    const typeflag = header[156];
+    if (typeflag !== 0 && typeflag !== 0x30) {
+      throw new InstallerError(`unexpected archive file ${name}`);
+    }
+    offset += 512;
+    if (offset + size > buf.length) {
+      throw new InstallerError("truncated tar archive");
+    }
+    const body = Buffer.from(buf.subarray(offset, offset + size));
+    files.push({ name, body });
+    offset += size + ((512 - (size % 512)) % 512);
+  }
+  return files;
+}
+
+function isZeroBlock(buf) {
+  for (let i = 0; i < buf.length; i++) {
+    if (buf[i] !== 0) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function cstring(buf) {
+  const end = buf.indexOf(0);
+  return buf.subarray(0, end === -1 ? buf.length : end).toString("utf8").trimEnd();
+}
+
+function parseOctal(buf) {
+  const s = buf.toString("ascii").replace(/\0/g, " ").trim();
+  if (s === "") {
+    return 0;
+  }
+  return parseInt(s, 8);
+}
+
+function readZip(bytes) {
+  const directory = readZipCentralDirectory(bytes);
+  const files = [];
+  for (const entry of directory.entries) {
+    if (entry.flags & (ZIP_ENCRYPTED_FLAG | ZIP_STRONG_ENCRYPTION_FLAG)) {
+      throw new InstallerError(`encrypted zip entry ${entry.name}`);
+    }
+    if (entry.compressedSize === ZIP64_UINT32 || entry.uncompressedSize === ZIP64_UINT32) {
+      throw new InstallerError(`unsupported ZIP64 entry ${entry.name}`);
+    }
+
+    const local = readZipLocalHeader(bytes, entry, directory.offset);
+    const raw = bytes.subarray(local.dataStart, local.dataEnd);
+    let body;
+    if (entry.method === 0) {
+      body = Buffer.from(raw);
+    } else if (entry.method === 8) {
+      body = Buffer.from(inflateRawSync(raw));
+    } else {
+      throw new InstallerError(`unsupported zip method ${entry.method}`);
+    }
+    if (body.length !== entry.uncompressedSize) {
+      throw new InstallerError(`zip size mismatch ${entry.name}`);
+    }
+    if (crc32(body) !== entry.crc32) {
+      throw new InstallerError(`zip checksum mismatch ${entry.name}`);
+    }
+    if (entry.name.endsWith("/")) {
+      throw new InstallerError(`unexpected archive file ${entry.name}`);
+    }
+    files.push({ name: entry.name, body });
+  }
+  return files;
+}
+
+function readZipCentralDirectory(bytes) {
+  const eocd = findZipEndOfCentralDirectory(bytes);
+  const disk = bytes.readUInt16LE(eocd + 4);
+  const directoryDisk = bytes.readUInt16LE(eocd + 6);
+  const diskEntries = bytes.readUInt16LE(eocd + 8);
+  const totalEntries = bytes.readUInt16LE(eocd + 10);
+  const size = bytes.readUInt32LE(eocd + 12);
+  const offset = bytes.readUInt32LE(eocd + 16);
+  if (disk !== 0 || directoryDisk !== 0 || diskEntries !== totalEntries) {
+    throw new InstallerError("multi-disk zip archive is not supported");
+  }
+  if (totalEntries === 0xffff || size === ZIP64_UINT32 || offset === ZIP64_UINT32) {
+    throw new InstallerError("ZIP64 archive is not supported");
+  }
+  const end = offset + size;
+  if (!Number.isSafeInteger(end) || end !== eocd) {
+    throw new InstallerError("invalid zip central directory");
+  }
+
+  const entries = [];
+  let cursor = offset;
+  for (let i = 0; i < totalEntries; i++) {
+    if (cursor + ZIP_CENTRAL_HEADER_SIZE > end || bytes.readUInt32LE(cursor) !== 0x02014b50) {
+      throw new InstallerError("invalid zip central directory");
+    }
+    const flags = bytes.readUInt16LE(cursor + 8);
+    const method = bytes.readUInt16LE(cursor + 10);
+    const crc = bytes.readUInt32LE(cursor + 16);
+    const compressedSize = bytes.readUInt32LE(cursor + 20);
+    const uncompressedSize = bytes.readUInt32LE(cursor + 24);
+    const nameLen = bytes.readUInt16LE(cursor + 28);
+    const extraLen = bytes.readUInt16LE(cursor + 30);
+    const commentLen = bytes.readUInt16LE(cursor + 32);
+    const localOffset = bytes.readUInt32LE(cursor + 42);
+    const recordEnd = cursor + ZIP_CENTRAL_HEADER_SIZE + nameLen + extraLen + commentLen;
+    if (!Number.isSafeInteger(recordEnd) || recordEnd > end) {
+      throw new InstallerError("truncated zip central directory");
+    }
+    const name = bytes.subarray(cursor + ZIP_CENTRAL_HEADER_SIZE, cursor + ZIP_CENTRAL_HEADER_SIZE + nameLen).toString("utf8");
+    if (localOffset === ZIP64_UINT32) {
+      throw new InstallerError(`unsupported ZIP64 entry ${name}`);
+    }
+    entries.push({
+      name,
+      flags,
+      method,
+      crc32: crc,
+      compressedSize,
+      uncompressedSize,
+      localOffset,
+    });
+    cursor = recordEnd;
+  }
+  if (cursor !== end) {
+    throw new InstallerError("invalid zip central directory");
+  }
+  return { offset, entries };
+}
+
+function findZipEndOfCentralDirectory(bytes) {
+  const first = Math.max(0, bytes.length - ZIP_EOCD_SIZE - 0xffff);
+  for (let offset = bytes.length - ZIP_EOCD_SIZE; offset >= first; offset--) {
+    if (bytes.readUInt32LE(offset) !== 0x06054b50) {
+      continue;
+    }
+    const commentLen = bytes.readUInt16LE(offset + 20);
+    if (offset + ZIP_EOCD_SIZE + commentLen === bytes.length) {
+      return offset;
+    }
+  }
+  throw new InstallerError("missing zip end of central directory");
+}
+
+function readZipLocalHeader(bytes, entry, centralOffset) {
+  const offset = entry.localOffset;
+  if (offset + ZIP_LOCAL_HEADER_SIZE > centralOffset || bytes.readUInt32LE(offset) !== 0x04034b50) {
+    throw new InstallerError(`invalid zip local header ${entry.name}`);
+  }
+  const flags = bytes.readUInt16LE(offset + 6);
+  const method = bytes.readUInt16LE(offset + 8);
+  const nameLen = bytes.readUInt16LE(offset + 26);
+  const extraLen = bytes.readUInt16LE(offset + 28);
+  const nameStart = offset + ZIP_LOCAL_HEADER_SIZE;
+  const dataStart = nameStart + nameLen + extraLen;
+  const dataEnd = dataStart + entry.compressedSize;
+  if (
+    flags !== entry.flags ||
+    method !== entry.method ||
+    dataStart > centralOffset ||
+    dataEnd > centralOffset ||
+    !Number.isSafeInteger(dataEnd)
+  ) {
+    throw new InstallerError(`invalid zip local header ${entry.name}`);
+  }
+  const name = bytes.subarray(nameStart, nameStart + nameLen).toString("utf8");
+  if (name !== entry.name) {
+    throw new InstallerError(`invalid zip local header ${entry.name}`);
+  }
+  return { dataStart, dataEnd };
+}
+
+function crc32(bytes) {
+  let crc = 0xffffffff;
+  for (let i = 0; i < bytes.length; i++) {
+    crc ^= bytes[i];
+    for (let bit = 0; bit < 8; bit++) {
+      crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1));
+    }
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function smoke(binPath, version, home, env) {
+  const result = spawnSync(binPath, ["version", "--json"], {
+    encoding: "utf8",
+    timeout: SMOKE_TIMEOUT_MS,
+    env: {
+      ...env,
+      WHOBOT_AGENT_CLI_HOME: home,
+    },
+  });
+  if (result.error) {
+    throw new InstallerError(`version smoke failed: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    throw new InstallerError(
+      `version smoke exit ${result.status}: ${String(result.stderr || "").trim()}`,
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(result.stdout);
+  } catch {
+    throw new InstallerError("version smoke did not emit JSON");
+  }
+  if (parsed.ok !== true) {
+    throw new InstallerError("version smoke ok=false");
+  }
+  if (parsed.meta?.protocol !== 2) {
+    throw new InstallerError(
+      `protocol ${parsed.meta?.protocol} is not 2`,
+    );
+  }
+  if (parsed.data?.version !== version) {
+    throw new InstallerError(
+      `installed version ${parsed.data?.version} does not match ${version}`,
+    );
+  }
+}
+
+async function replaceAtomically(stagedPath, dest) {
+  await fs.mkdir(path.dirname(dest), { recursive: true, mode: 0o755 });
+  const tmp = `${dest}.tmp.${process.pid}.${Math.random().toString(16).slice(2)}`;
+  try {
+    await fs.copyFile(stagedPath, tmp);
+    await fs.chmod(tmp, 0o755);
+    const fd = openSync(tmp, "r+");
+    try {
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+    await fs.rename(tmp, dest);
+  } catch (err) {
+    await fs.unlink(tmp).catch(() => {});
+    throw err;
+  }
+}
+
+function firstNonEmpty(...vals) {
+  for (const v of vals) {
+    if (v !== undefined && v !== null) {
+      return v;
+    }
+  }
+  return undefined;
+}
+
+function envGet(env, names) {
+  for (const n of names) {
+    const v = env[n];
+    if (v !== undefined && String(v).trim() !== "") {
+      return String(v).trim();
+    }
+  }
+  return "";
+}
+
+function isLoopback(host) {
+  const h = String(host).replace(/^\[|\]$/g, "").toLowerCase();
+  return h === "localhost" || h === "127.0.0.1" || h === "::1" || h === "0:0:0:0:0:0:0:1";
+}
+
+function assertURLAllowed(url) {
+  if (url.protocol === "https:") {
+    return;
+  }
+  if (url.protocol === "http:" && isLoopback(url.hostname)) {
+    return;
+  }
+  throw new InstallerError(
+    "HTTP download is only allowed for loopback test origins",
+  );
+}
+
+function matchesNoProxy(hostname, noProxy) {
+  if (!noProxy) {
+    return false;
+  }
+  const host = hostname.toLowerCase();
+  for (const raw of noProxy.split(",")) {
+    const item = raw.trim().toLowerCase();
+    if (item === "" || item === "*") {
+      return item === "*";
+    }
+    if (item === host) {
+      return true;
+    }
+    if (item.startsWith(".") && (host.endsWith(item) || host === item.slice(1))) {
+      return true;
+    }
+    if (!item.startsWith(".") && host.endsWith(`.${item}`)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function proxyFor(url, env) {
+  if (matchesNoProxy(url.hostname, envGet(env, ["NO_PROXY", "no_proxy"]))) {
+    return null;
+  }
+  const raw =
+    url.protocol === "https:"
+      ? envGet(env, ["HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy"])
+      : envGet(env, ["HTTP_PROXY", "http_proxy"]);
+  if (!raw) {
+    return null;
+  }
+  return new URL(raw.includes("://") ? raw : `http://${raw}`);
+}
+
+async function httpGet(urlString, env, opts) {
+  let url = new URL(urlString);
+  assertURLAllowed(url);
+  for (let hop = 0; hop < 6; hop++) {
+    const res = await httpGetOnce(url, env, DOWNLOAD_TIMEOUT_MS);
+    if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+      res.resume();
+      const next = new URL(res.headers.location, url);
+      if (url.protocol === "https:" && next.protocol !== "https:") {
+        throw new InstallerError("refusing HTTPS to HTTP redirect");
+      }
+      assertURLAllowed(next);
+      url = next;
+      continue;
+    }
+    if (res.statusCode !== 200) {
+      res.resume();
+      throw new InstallerError(`download ${url.href} status ${res.statusCode}`);
+    }
+    return await readBody(res, opts.destFile, opts.expectedSize);
+  }
+  throw new InstallerError("too many redirects");
+}
+
+function httpGetOnce(url, env, timeoutMs) {
+  const proxy = proxyFor(url, env);
+  if (url.protocol === "https:") {
+    if (proxy) {
+      return httpsGetViaProxy(url, proxy, timeoutMs);
+    }
+    return requestOnce(
+      https,
+      {
+        hostname: url.hostname,
+        port: url.port || 443,
+        path: url.pathname + url.search,
+        method: "GET",
+        headers: { Host: url.host, Connection: "close" },
+        servername: url.hostname,
+        timeout: timeoutMs,
+      },
+      timeoutMs,
+    );
+  }
+  if (proxy) {
+    return requestOnce(
+      http,
+      {
+        hostname: proxy.hostname,
+        port: proxy.port || 80,
+        path: url.href,
+        method: "GET",
+        headers: { Host: url.host, Connection: "close" },
+        timeout: timeoutMs,
+      },
+      timeoutMs,
+    );
+  }
+  return requestOnce(
+    http,
+    {
+      hostname: url.hostname,
+      port: url.port || 80,
+      path: url.pathname + url.search,
+      method: "GET",
+      headers: { Host: url.host, Connection: "close" },
+      timeout: timeoutMs,
+    },
+    timeoutMs,
+  );
+}
+
+function requestOnce(mod, options, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const req = mod.request(options, (res) => resolve(res));
+    req.on("error", reject);
+    req.setTimeout(timeoutMs, () => {
+      req.destroy();
+      reject(new InstallerError("download timeout"));
+    });
+    req.end();
+  });
+}
+
+function httpsGetViaProxy(url, proxy, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const req = http.request({
+      hostname: proxy.hostname,
+      port: proxy.port || 80,
+      method: "CONNECT",
+      path: `${url.hostname}:${url.port || 443}`,
+      timeout: timeoutMs,
+    });
+    req.on("connect", (res, socket) => {
+      if (res.statusCode !== 200) {
+        socket.destroy();
+        reject(new InstallerError(`proxy CONNECT status ${res.statusCode}`));
+        return;
+      }
+      const tlsSock = tls.connect({
+        socket,
+        servername: url.hostname,
+        timeout: timeoutMs,
+      });
+      tlsSock.once("error", reject);
+      tlsSock.once("secureConnect", () => {
+        const creq = https.request(
+          {
+            hostname: url.hostname,
+            port: url.port || 443,
+            path: url.pathname + url.search,
+            method: "GET",
+            headers: { Host: url.host, Connection: "close" },
+            timeout: timeoutMs,
+            createConnection: () => tlsSock,
+          },
+          (cres) => resolve(cres),
+        );
+        creq.on("error", reject);
+        creq.end();
+      });
+    });
+    req.on("error", reject);
+    req.on("timeout", () => {
+      req.destroy();
+      reject(new InstallerError("proxy CONNECT timeout"));
+    });
+    req.end();
+  });
+}
+
+function readBody(res, destFile, expectedSize) {
+  return new Promise((resolve, reject) => {
+    const hash = createHash("sha256");
+    let size = 0;
+    const chunks = destFile ? null : [];
+    const out = destFile ? createWriteStream(destFile) : null;
+    let settled = false;
+    const fail = (err) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      res.destroy();
+      if (out) {
+        out.destroy();
+      }
+      reject(err);
+    };
+    res.on("data", (chunk) => {
+      size += chunk.length;
+      if (expectedSize != null && size > expectedSize) {
+        fail(new InstallerError("download exceeded manifest size"));
+        return;
+      }
+      hash.update(chunk);
+      if (out) {
+        out.write(chunk);
+      } else {
+        chunks.push(chunk);
+      }
+    });
+    res.on("error", fail);
+    res.on("end", () => {
+      const finish = () => {
+        if (settled) {
+          return;
+        }
+        if (expectedSize != null && size !== expectedSize) {
+          fail(
+            new InstallerError(
+              `download size ${size} does not match manifest ${expectedSize}`,
+            ),
+          );
+          return;
+        }
+        settled = true;
+        resolve({
+          sha256: hash.digest("hex"),
+          size,
+          body: chunks ? Buffer.concat(chunks) : null,
+        });
+      };
+      if (out) {
+        out.end(finish);
+        out.on("error", fail);
+      } else {
+        finish();
+      }
+    });
+  });
+}
+
+function launchedAsCli() {
+  if (typeof process.argv[1] !== "string") {
+    return false;
+  }
+  try {
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+  } catch {
+    return false;
+  }
+}
+
+if (launchedAsCli()) {
+  runInstall(process.argv.slice(2), process.env)
+    .then((dest) => {
+      process.stdout.write(`${dest}\n`);
+      process.exitCode = 0;
+    })
+    .catch((err) => {
+      process.stderr.write(`${err && err.message ? err.message : err}\n`);
+      process.exitCode = 1;
+    });
+}