@chorus-aidlc/chorus 0.19.1 → 0.20.0

package/cli/process-killer.mjs

@@ -3,8 +3,9 @@
 // channel (子3 — daemon-interrupt-resume, Tech Design "Killer contract"). When an
 // authorized interrupt is verified, the daemon must STOP a running headless-Claude
 // subprocess — first gracefully (SIGINT, so the model can flush in-progress work),
-// then forcefully if it does not exit within a configurable window. Plain ESM, ZERO
-// new npm deps (CLAUDE.md pitfall #9) and Bash-3.2-safe (no shell touched).
+// then forcefully if it does not exit within a configurable window. Plain ESM,
+// zero new npm deps. Codex's Windows protocol path uses fixed, noninteractive
+// PowerShell/CIM queries to retain process identities across graceful root exit.
 //
 // Why a process TREE, not just the direct child:
 //   • POSIX: Claude may itself spawn children. Linux does NOT cascade a signal to a
@@ -28,8 +29,24 @@
 // (every signal/spawn is try/caught), and LOGS visibly (memory: no-silent-errors).
 
 import { spawn as nodeSpawn } from "node:child_process";
+import { getProcessStopHook } from "./process-stop-hooks.mjs";
+import { WindowsProcessTree } from "./windows-process-tree.mjs";
 
 const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
+const protocolStops = new WeakMap();
+
+/** Bound even an uncooperative hook; consume late rejection and clear the timer. */
+async function withinDeadline(work, deadline) {
+  let timer;
+  try {
+    return await Promise.race([
+      Promise.resolve(work).then(() => true, () => false),
+      new Promise((resolve) => { timer = setTimeout(() => resolve(false), Math.max(0, deadline - Date.now())); }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
 
 /** Default escalation window before a forceful kill (Tech Design / spec: 10s). */
 export const DEFAULT_SIGINT_TIMEOUT_MS = 10_000;
@@ -98,6 +115,66 @@ export async function killProcessTree(child, opts = {}) {
   const sigintTimeoutMs = opts.sigintTimeoutMs ?? DEFAULT_SIGINT_TIMEOUT_MS;
   const isWin = platform === "win32";
 
+  const hook = !opts.skipStopHook && getProcessStopHook(child);
+  if (hook) {
+    const existing = protocolStops.get(child);
+    const deadline = existing?.deadline ?? Date.now() + sigintTimeoutMs;
+    const protocolDeadline = existing?.protocolDeadline ??
+      (isWin ? deadline - Math.min(2500, Math.floor(Math.max(0, sigintTimeoutMs) / 4)) : deadline);
+    const windowsTree = isWin && typeof child.pid === "number"
+      ? existing?.windowsTree ?? new WindowsProcessTree(child, {
+        deadline, spawnImpl, snapshotImpl: opts.windowsSnapshotImpl,
+      }) : null;
+    // Invoke synchronously even during an existing normal cleanup: cancellation
+    // must latch before any pending setup/turn-start continuation can execute.
+    let work;
+    try {
+      work = hook({
+        deadline, protocolDeadline, reason: opts.reason ?? "interrupt",
+        beforeClose: windowsTree ? () => windowsTree.capture() : undefined,
+      });
+    } catch {
+      work = Promise.reject(new Error("Protocol stop failed"));
+    }
+    const attempt = withinDeadline(work, deadline);
+    if (existing) {
+      await attempt;
+      return existing.promise;
+    }
+    const promise = (async () => {
+      const graceful = await attempt;
+      if (!graceful) logger.warn("[Chorus] protocol stop failed or exceeded its cleanup deadline");
+      const exited = graceful && await waitForChildExit(child, Math.max(0, protocolDeadline - Date.now()), opts, logger);
+      if (windowsTree) {
+        let cleanup = { cleanupFailed: true, escalated: false };
+        const settled = await withinDeadline(windowsTree.cleanup().then(result => { cleanup = result; }), deadline);
+        const cleanupFailed = !settled || cleanup.cleanupFailed;
+        if (cleanupFailed) logger.warn("[Chorus] Windows process-tree cleanup could not be verified within its deadline.");
+        return { signaled: false, killed: !cleanupFailed, escalated: windowsTree.escalated,
+          ...(cleanupFailed ? { cleanupFailed: true } : {}) };
+      }
+      // A leader exit does not prove its process group is gone.
+      let treeRemains = !exited;
+      if (exited && typeof child.pid === "number") {
+        if (opts.hasTree) treeRemains = safeBool(opts.hasTree, logger);
+        else if (!isWin) {
+          try { killImpl(-child.pid, 0); treeRemains = true; }
+          catch (err) { treeRemains = err?.code !== "ESRCH"; }
+        }
+      }
+      const forced = treeRemains
+        ? await killProcessTree(child, { ...opts, skipStopHook: true, sigintTimeoutMs: 0, forceOnly: true, cleanupDeadline: deadline })
+        : null;
+      return { signaled: false, killed: true, escalated: Boolean(treeRemains),
+        ...(forced?.cleanupFailed ? { cleanupFailed: true } : {}) };
+    })();
+    protocolStops.set(child, { deadline, protocolDeadline, promise, windowsTree });
+    // Retain the completed operation while this child is reachable. A spawner's
+    // final cleanup can arrive just after escalation; it must reuse that deadline
+    // and result instead of starting a second stop. Weak keys require no disposal.
+    return await promise;
+  }
+
   if (!child || typeof child.pid !== "number") {
     // No live process to target — log and no-op (never throw into the wake path).
     logger.warn("[Chorus] killProcessTree: no child pid to target; ignoring");
@@ -106,8 +183,10 @@ export async function killProcessTree(child, opts = {}) {
   const pid = child.pid;
 
   // --- Stage 1: graceful SIGINT ---
-  let signaled;
-  if (isWin) {
+  let signaled = false;
+  if (opts.forceOnly) {
+    // The protocol path already spent its one shared graceful deadline.
+  } else if (isWin) {
     // Windows: deliver SIGINT to the direct child only (best-effort). Node maps
     // SIGINT to a console-stop on Windows; it cannot reach a tree there.
     try {
@@ -123,13 +202,14 @@ export async function killProcessTree(child, opts = {}) {
   }
 
   // --- Wait for graceful exit within the window ---
-  const exitedGracefully = await waitForChildExit(child, sigintTimeoutMs, opts, logger);
+  const exitedGracefully = !opts.forceOnly && await waitForChildExit(child, sigintTimeoutMs, opts, logger);
   if (exitedGracefully) {
     logger.info(`[Chorus] interrupt: pid ${pid} exited gracefully within ${sigintTimeoutMs}ms`);
     return { signaled, killed: true, escalated: false };
   }
 
   // --- Stage 2: forceful tree kill ---
+  let cleanupFailed = false;
   if (isWin) {
     // taskkill /PID <pid> /T /F — /T ends the tree (child processes), /F forces it.
     try {
@@ -137,17 +217,59 @@ export async function killProcessTree(child, opts = {}) {
         stdio: "ignore",
         windowsHide: true,
       });
-      // taskkill failures are logged, never thrown.
-      tk?.on?.("error", (err) => logger.warn(`[Chorus] taskkill spawn error: ${err}`));
+      // Protocol cleanup certifies settlement, unlike legacy fire-and-forget
+      // escalation. Use only the time remaining in the original stop budget.
+      if (opts.forceOnly) {
+        cleanupFailed = !await waitForTaskkill(tk, opts.cleanupDeadline ?? Date.now(), logger);
+      } else {
+        tk?.on?.("error", (err) => logger.warn(`[Chorus] taskkill spawn error: ${err}`));
+      }
       logger.info(`[Chorus] interrupt: escalated — taskkill /PID ${pid} /T /F (windows)`);
     } catch (err) {
-      logger.warn(`[Chorus] taskkill escalation failed for pid ${pid}: ${err}`);
+      cleanupFailed = true;
+      logger.warn(opts.forceOnly
+        ? "[Chorus] Codex process-tree cleanup could not start taskkill."
+        : `[Chorus] taskkill escalation failed for pid ${pid}: ${err}`);
     }
   } else {
-    signalGroup(pid, "SIGKILL", killImpl, logger);
+    const delivered = signalGroup(pid, "SIGKILL", killImpl, logger);
+    if (!delivered && opts.forceOnly) {
+      try { killImpl(-pid, 0); cleanupFailed = true; }
+      catch (err) { cleanupFailed = err?.code !== "ESRCH"; }
+    }
     logger.info(`[Chorus] interrupt: escalated — SIGKILL to process group -${pid} (posix)`);
   }
-  return { signaled, killed: true, escalated: true };
+  return { signaled, killed: true, escalated: true,
+    ...(opts.forceOnly && cleanupFailed ? { cleanupFailed: true } : {}) };
+}
+
+/** Bounded Windows termination acknowledgement; never includes tool output. */
+function waitForTaskkill(child, deadline, logger) {
+  return new Promise(resolve => {
+    let settled = false;
+    const finish = ok => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child?.removeListener?.("exit", onExit);
+      // Keep the payload-blind error guard until close: spawn errors can arrive
+      // after the deadline. It retains no provider/stdio data.
+      if (!ok) logger.warn("[Chorus] Codex process-tree cleanup taskkill failed or exceeded its deadline.");
+      resolve(ok);
+    };
+    const onExit = (code, signal) => finish(code === 0 && !signal);
+    const onError = () => finish(false);
+    const onClose = code => {
+      finish(code === 0);
+      child?.removeListener?.("error", onError);
+    };
+    const timer = setTimeout(() => finish(false), Math.max(0, deadline - Date.now()));
+    child?.once?.("exit", onExit);
+    child?.once?.("close", onClose);
+    child?.on?.("error", onError);
+    if (!child?.once) finish(false);
+    else if (child.exitCode !== null && child.exitCode !== undefined) finish(child.exitCode === 0);
+  });
 }
 
 /**
@@ -170,7 +292,7 @@ async function waitForChildExit(child, ms, opts, logger) {
   const hasExited =
     typeof opts.hasExited === "function"
       ? safeBool(opts.hasExited, logger)
-      : child.exitCode !== null && child.exitCode !== undefined;
+      : (child.exitCode !== null && child.exitCode !== undefined) || Boolean(child.signalCode);
   if (hasExited) return true;
 
   return await new Promise((resolve) => {
@@ -179,14 +301,17 @@ async function waitForChildExit(child, ms, opts, logger) {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
+      child.removeListener?.("exit", onExit);
+      child.removeListener?.("close", onExit);
       resolve(value);
     };
+    const onExit = () => finish(true);
     const timer = setTimeout(() => finish(false), ms);
     // unref so a pending timer never keeps the daemon process alive on shutdown.
     timer?.unref?.();
     try {
-      child.once?.("exit", () => finish(true));
-      child.once?.("close", () => finish(true));
+      child.once?.("exit", onExit);
+      child.once?.("close", onExit);
     } catch (err) {
       logger.warn(`[Chorus] failed to attach exit listener: ${err}`);
       finish(false);

package/cli/process-stop-hooks.mjs

@@ -0,0 +1,13 @@
+// Process-local capabilities: never serialized into execution snapshots.
+const hooks = new WeakMap();
+
+export function registerProcessStopHook(child, hook) {
+  hooks.set(child, hook);
+  return () => {
+    if (hooks.get(child) === hook) hooks.delete(child);
+  };
+}
+
+export function getProcessStopHook(child) {
+  return child && hooks.get(child);
+}

package/cli/upgrade-plugins.mjs

@@ -0,0 +1,202 @@
+import * as fs from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join, posix, win32 } from "node:path";
+import { overlayAgentEnv, getAgentEnv, validateAgentCliConfig, rejectSharedCliConfig } from "./agent-cli-config.mjs";
+import { resolveBinaryPath } from "./agent-launcher.mjs";
+import { readClaudeInstallState } from "./init/adapters.mjs";
+import { installClaude, installCodex, installKiro, readCodexInstallState } from "./init/install-methods.mjs";
+import { normalizeAssetBase } from "./init/file-template.mjs";
+import { runUpgradeCommand, sanitizeUpgradeOutput, upgradeFailure } from "./upgrade-process.mjs";
+
+const HOSTS = {
+  claude: { binary: "claude", variable: "CLAUDE_CONFIG_DIR", dir: [".claude"] },
+  codex: { binary: "codex", variable: "CODEX_HOME", dir: [".codex"] },
+  kiro: { binary: "kiro-cli", variable: "KIRO_DIR", dir: [".kiro"] },
+  pi: { binary: "pi", variable: "PI_CODING_AGENT_DIR", dir: [".pi", "agent"] },
+};
+const text = (v) => typeof v === "string" && v.trim() ? v.trim() : undefined;
+const object = (v) => v && typeof v === "object" && !Array.isArray(v);
+
+// Resolve existing ancestors too: two not-yet-created config dirs under aliased
+// homes still share a destination. No directory is created during planning.
+function canonical(path, io, p) {
+  try { return io.realpathSync(path); } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+    const parent = p.dirname(path);
+    if (parent === path) return path;
+    return p.join(canonical(parent, io, p), p.basename(path));
+  }
+}
+
+export function planPluginTargets(config, deps = {}) {
+  const io = deps.fs ?? fs, platform = deps.platform ?? process.platform;
+  const p = platform === "win32" ? win32 : posix;
+  const base = deps.env ?? process.env;
+  if (!object(config) || (config.agents !== undefined && !Array.isArray(config.agents))) throw new Error("invalid config");
+  rejectSharedCliConfig(config);
+  const rows = config.agents ?? (Object.keys(config).length ? [config] : []);
+  const targets = new Map(), results = [];
+  rows.forEach((row, i) => {
+    // Stable indices associate every row without echoing untrusted names/keys.
+    const label = `agents[${i}]`;
+    if (!object(row)) { results.push({ target: label, complete: false, detail: "Malformed agent record." }); return; }
+    const rawType = text(row.agentType) ?? text(config.agent);
+    const type = rawType === "claude-code" ? "claude" : rawType;
+    const host = Object.hasOwn(HOSTS, type) ? HOSTS[type] : undefined;
+    if (!host) { results.push({ target: label, complete: false, detail: "Skipped: offline, unknown or missing explicit host type." }); return; }
+    try {
+      const overrides = validateAgentCliConfig({ env: row.env }, type, label).env;
+      let env = overlayAgentEnv(base, overrides, platform);
+      // Normalize Windows case aliases for existing installer readers.
+      for (const name of ["HOME", "USERPROFILE", "PATH", ...Object.values(HOSTS).map((h) => h.variable)]) {
+        const value = getAgentEnv(env, name, platform);
+        if (value !== undefined) env = overlayAgentEnv(env, { [name]: value }, platform);
+      }
+      const homeOverride = getAgentEnv(overrides, "HOME", platform) ||
+        getAgentEnv(overrides, "USERPROFILE", platform);
+      const home = p.resolve(homeOverride || env.HOME || env.USERPROFILE || homedir());
+      env.HOME = home;
+      if (platform === "win32") env.USERPROFILE = home;
+      const destination = canonical(p.resolve(env[host.variable] || p.join(home, ...host.dir)), io, p);
+      env[host.variable] = destination;
+      // Do not inherit an interactive Claude nesting guard into its plugin CLI.
+      delete env.CLAUDECODE;
+      delete env.CLAUDE_CODE_ENTRYPOINT;
+      const key = `${type}:${platform === "win32" ? destination.toLowerCase() : destination}`;
+      let source;
+      if (type === "kiro") {
+        source = normalizeAssetBase(text(row.url) ?? text(config.url) ?? env.CHORUS_URL);
+        const url = new URL(source);
+        if (url.username || url.password || url.search || url.hash) throw new Error("invalid source");
+      }
+      const existing = targets.get(key);
+      if (existing) {
+        existing.labels.push(label);
+        if (existing.source !== source) existing.conflict = true;
+      } else targets.set(key, { type, host, destination, env, source, labels: [label] });
+    } catch {
+      results.push({ target: label, complete: false, detail: "Invalid environment, destination or Chorus source URL." });
+    }
+  });
+  return { targets: [...targets.values()], results };
+}
+
+function readJson(path, io) {
+  try { return JSON.parse(io.readFileSync(path, "utf8")); }
+  catch (e) { if (e.code === "ENOENT") return undefined; throw e; }
+}
+
+// Verified against installed pi update/install --help (2026-09-30). Probe the
+// actual target host as older releases have only the all-extension updater.
+export function upgradePi(target, { run, fs: io = fs }) {
+  const settings = readJson(join(target.destination, "settings.json"), io);
+  if (settings !== undefined && (!object(settings) || (settings.packages !== undefined && !Array.isArray(settings.packages)))) {
+    throw new Error("invalid Pi settings");
+  }
+  const packages = settings?.packages ?? [];
+  let complete = true, changed = false, constrained = false;
+  const help = run("pi", ["update", "--help"]);
+  const targeted = help.ok && /--extension\s+<source>/.test(help.stdout) && /--no-approve\b/.test(help.stdout);
+  let installHelp;
+  for (const spec of ["npm:pi-mcp-adapter", "npm:@chorus-aidlc/chorus-pi"]) {
+    const sources = packages.map((entry) => {
+      const source = typeof entry === "string" ? entry : entry?.source;
+      return source;
+    }).filter((source) => source === spec || (typeof source === "string" && source.startsWith(`${spec}@`)));
+    const present = sources.length > 0;
+    // Pi updates by identity but retains configured constraints. Pinned versions
+    // are a successful no-op; ranges/tags can also exclude the latest release.
+    // Preserve those settings and report incomplete rather than silently unpin.
+    if (sources.some((source) => source !== spec && source !== `${spec}@latest`)) {
+      complete = false;
+      constrained = true;
+      continue;
+    }
+    if (present && !targeted) { complete = false; continue; }
+    if (!present) {
+      installHelp ??= run("pi", ["install", "--help"]);
+      if (!installHelp.ok || !/--no-approve\b/.test(installHelp.stdout)) { complete = false; continue; }
+    }
+    const r = run("pi", present ? ["update", "--extension", spec, "--no-approve"] : ["install", spec, "--no-approve"]);
+    changed = true; // A failed command can still leave a partial change.
+    if (!r.ok) complete = false;
+  }
+  return {
+    complete, changed,
+    detail: complete ? "Refreshed Chorus and pi-mcp-adapter only."
+      : constrained ? "Pi refresh incomplete: configured package version constraints were preserved; remove those constraints to permit latest updates. Other eligible components were attempted."
+        : "Pi refresh incomplete: targeted update/install unsupported or failed; no all-extension update was run.",
+  };
+}
+
+export async function upgradePlugins(deps = {}) {
+  const io = deps.fs ?? fs, env = deps.env ?? process.env, platform = deps.platform ?? process.platform;
+  const p = platform === "win32" ? win32 : posix;
+  const configPath = deps.configPath ?? p.join(getAgentEnv(env, "HOME", platform) || getAgentEnv(env, "USERPROFILE", platform) || homedir(), ".chorus", "daemon.json");
+  let plan;
+  try {
+    const config = readJson(configPath, io);
+    if (config === undefined) return [{ target: "plugins", complete: true, detail: "No daemon configuration; no configured plugins." }];
+    plan = planPluginTargets(config, deps);
+  } catch {
+    return [{ target: "plugins", complete: false, detail: "Cannot read or validate daemon configuration." }];
+  }
+  const results = plan.results;
+  if (!plan.targets.length && !results.length) return [{ target: "plugins", complete: true, detail: "No configured plugins." }];
+  for (const target of plan.targets) {
+    const label = `${target.type} (${target.labels.join(", ")})`;
+    if (target.conflict) {
+      results.push({ target: label, complete: false, detail: "Conflicting Chorus URLs for one Kiro destination; no update attempted." });
+      continue;
+    }
+    if (!(deps.resolveBinary ?? resolveBinaryPath)(target.host.binary, { env: target.env, platform })) {
+      results.push({ target: label, complete: false, detail: "Skipped: host executable missing from this record's PATH." });
+      continue;
+    }
+    let scratch;
+    let changed = false;
+    const failures = [];
+    const safe = (text) => sanitizeUpgradeOutput(text, { env: target.env });
+    try {
+      // Package commands must not discover project-local plugin configuration.
+      scratch = io.mkdtempSync(join(tmpdir(), "chorus-upgrade-"));
+      const run = (cmd, args) => {
+        if (!args.includes("--help")) changed = true;
+        const result = (deps.run ?? runUpgradeCommand)(cmd, args, { env: target.env, platform, cwd: scratch, timeoutMs: 120_000 });
+        if (!result.ok) failures.push(`${cmd} ${args.slice(0, 2).join(" ")}: ${upgradeFailure(result, { env: target.env })}`);
+        return result;
+      };
+      if (target.type === "pi") {
+        const result = upgradePi(target, { run, fs: io });
+        results.push({ target: label, ...result, detail: safe([result.detail, ...failures].join("\n")) });
+        continue;
+      }
+      const state = target.type === "claude"
+        ? readClaudeInstallState({ env: target.env, home: target.env.HOME, readJson: (path) => readJson(path, io) })
+        : target.type === "codex" ? readCodexInstallState({ env: target.env }) : {};
+      const install = (deps.installers ?? { claude: installClaude, codex: installCodex, kiro: installKiro })[target.type];
+      const outcome = await install({
+        env: target.env, platform, run,
+        flags: { updateInstalled: true, pluginOnly: true, url: target.source },
+        adapter: { readInstallState: () => state },
+        backup: (path) => {
+          if (io.existsSync(path)) io.copyFileSync(path, `${path}.chorus-upgrade.bak`);
+        },
+        // Keep the deadline active while response bodies are consumed too.
+        fetch: (url) => (deps.fetch ?? globalThis.fetch)(url, { signal: AbortSignal.timeout(30_000) }),
+      });
+      const complete = ["installed", "repaired"].includes(outcome.action);
+      changed ||= complete;
+      results.push({
+        target: label, complete, changed,
+        detail: complete ? (target.source ? `Refreshed Chorus templates from ${target.source}.` : "Chorus plugin refreshed.")
+          : safe([outcome.detail || "Plugin update failed or is unsupported.", ...failures].join("\n")),
+      });
+    } catch (error) {
+      results.push({ target: label, complete: false, changed, detail: safe(`Plugin update failed: ${error?.message || "unknown error"}\n${failures.join("\n")}`) });
+    } finally {
+      if (scratch) io.rmSync(scratch, { recursive: true, force: true });
+    }
+  }
+  return results;
+}

package/cli/upgrade-process.mjs

@@ -0,0 +1,159 @@
+// Queries are bounded; npm installation streams sanitized progress without a
+// deadline that could interrupt replacement of the running package.
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { stripVTControlCharacters } from "node:util";
+import { win32, posix } from "node:path";
+import { resolveBinaryPath } from "./agent-launcher.mjs";
+import { getAgentEnv } from "./agent-cli-config.mjs";
+
+export function sanitizeUpgradeOutput(value, { env = process.env, secrets = [] } = {}) {
+  let text = stripVTControlCharacters(String(value ?? ""));
+  const values = [...secrets, ...Object.entries(env)
+    .filter(([key]) => /key|token|secret|password|credential|auth/i.test(key))
+    .map(([, v]) => v)].filter((v) => typeof v === "string" && v.length > 0);
+  // Streaming emits complete lines before the next line arrives. Protect each
+  // nonempty line of multiline credentials, including whitespace-normalized
+  // output, as well as whole-value JSON/URL representations in diagnostics.
+  const forms = new Set();
+  for (const value of values) {
+    for (const part of [value, ...value.split(/\r?\n/)]) {
+      for (const secret of [part, part.trim()]) {
+        if (!secret) continue;
+        forms.add(secret);
+        forms.add(JSON.stringify(secret).slice(1, -1));
+        forms.add(encodeURIComponent(secret));
+      }
+    }
+  }
+  for (const form of [...forms].sort((a, b) => b.length - a.length)) text = text.split(form).join("[redacted]");
+  return text
+    .replace(/\b(?:cho_|npm_|gh[pousr]_|sk-)[A-Za-z0-9_-]+/g, "[redacted]")
+    .replace(/\b(authorization["']?\s*[:=]\s*["']?)(?:bearer\s+|basic\s+)?[^"'\s,;]+/gi, "$1[redacted]")
+    .replace(/((?:["']?[\w.-]*(?:token|password|secret|api[_-]?key|_auth)[\w.-]*["']?)\s*[:=]\s*)(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|[^\s,;]+)/gi, "$1[redacted]")
+    .replace(/https?:\/\/[^\s"'<>]+/gi, (url) => {
+      try {
+        const parsed = new URL(url);
+        if (parsed.username || parsed.password) { parsed.username = "[redacted]"; parsed.password = ""; }
+        for (const key of [...parsed.searchParams.keys()]) parsed.searchParams.set(key, "[redacted]");
+        if (parsed.hash) parsed.hash = "[redacted]";
+        return parsed.toString();
+      } catch { return "[redacted URL]"; }
+    })
+    .replace(/[\x00-\x08\x0b-\x1f\x7f]/g, "");
+}
+
+export function upgradeFailure(result, opts = {}) {
+  const status = Number.isInteger(result?.code) ? `exit ${result.code}`
+    : result?.signal ? `signal ${result.signal}` : result?.reason || "command failed";
+  const sanitized = sanitizeUpgradeOutput(result?.stderr || result?.error || result?.stdout || "", opts);
+  const permission = sanitized.match(/\b(?:EACCES|EPERM)\b/)?.[0];
+  const detail = sanitized.trim().split("\n").slice(-6).join("\n").slice(-2000);
+  return `${status}${permission ? ` (${permission})` : ""}${detail ? `: ${detail}` : ""}`;
+}
+
+function processResult(r, opts) {
+  return {
+    ok: !r.error && r.status === 0,
+    code: r.status ?? null, signal: r.signal ?? null,
+    stdout: sanitizeUpgradeOutput(r.stdout, opts),
+    stderr: sanitizeUpgradeOutput(r.stderr, opts),
+    error: sanitizeUpgradeOutput(r.error?.message || r.error?.code, opts),
+    reason: r.error?.code === "ETIMEDOUT" ? "timed out" : "command failed",
+  };
+}
+
+export function commandForUpgrade(binary, args, {
+  platform = process.platform, env = process.env, node = process.execPath,
+  exists = existsSync, realpath = realpathSync,
+} = {}) {
+  const p = platform === "win32" ? win32 : posix;
+  if (platform !== "win32" || !/\.(cmd|bat)$/i.test(binary)) {
+    return { command: binary, args };
+  }
+  if (/^npm\.(cmd|bat)$/i.test(p.basename(binary))) {
+    const cli = p.join(p.dirname(binary), "node_modules", "npm", "bin", "npm-cli.js");
+    if (!exists(cli)) throw new Error("npm shim has no npm-cli.js");
+    return { command: node, args: [realpath(cli), ...args] };
+  }
+  // Native host binaries use argv directly. For a Windows command shim, quote
+  // spaces and reject cmd expansion/control characters rather than interpolate.
+  const tokens = [binary, ...args];
+  if (tokens.some((s) => /["%!^&|<>()\r\n\0]/.test(s))) {
+    throw new Error("Unsupported characters in Windows command shim");
+  }
+  return {
+    command: getAgentEnv(env, "COMSPEC", platform) || "cmd.exe",
+    args: ["/d", "/s", "/c", `"${tokens.map((s) => `"${s}"`).join(" ")}"`],
+    windowsVerbatimArguments: true,
+  };
+}
+
+export function runUpgradeCommand(cmd, args = [], opts = {}) {
+  const env = opts.env ?? process.env;
+  const platform = opts.platform ?? process.platform;
+  try {
+    const binary = (opts.resolveBinary ?? resolveBinaryPath)(cmd, { env, platform });
+    if (!binary) return { ok: false, reason: "missing executable" };
+    const launch = commandForUpgrade(binary, args, { ...opts, env, platform });
+    const r = (opts.spawnSync ?? spawnSync)(launch.command, launch.args, {
+      env, cwd: opts.cwd, shell: false, windowsHide: true,
+      windowsVerbatimArguments: launch.windowsVerbatimArguments,
+      stdio: ["ignore", "pipe", "pipe"], encoding: "utf8",
+      timeout: opts.timeoutMs ?? 120_000, killSignal: "SIGKILL", maxBuffer: 2 * 1024 * 1024,
+    });
+    return processResult(r, { ...opts, env });
+  } catch (error) {
+    return processResult({ error }, { ...opts, env });
+  }
+}
+
+export async function runUpgradeInstall(cmd, args = [], opts = {}) {
+  const env = opts.env ?? process.env, platform = opts.platform ?? process.platform;
+  try {
+    const binary = (opts.resolveBinary ?? resolveBinaryPath)(cmd, { env, platform });
+    if (!binary) return { ok: false, reason: "missing executable" };
+    const launch = commandForUpgrade(binary, args, { ...opts, env, platform });
+    return await new Promise((resolve) => {
+      const child = (opts.spawn ?? spawn)(launch.command, launch.args, {
+        env, cwd: opts.cwd, shell: false, windowsHide: true,
+        windowsVerbatimArguments: launch.windowsVerbatimArguments,
+        stdio: ["ignore", "pipe", "pipe"],
+        // No timeout, timer or automatic kill: let npm complete/roll back.
+      });
+      const buffers = { stdout: "", stderr: "" };
+      const tails = { stdout: "", stderr: "" };
+      const dropping = { stdout: false, stderr: false };
+      const emit = (name, line) => {
+        const safe = sanitizeUpgradeOutput(line, { ...opts, env });
+        tails[name] = (tails[name] + safe + "\n").slice(-4000);
+        if (safe) opts.onOutput?.(safe);
+      };
+      for (const name of ["stdout", "stderr"]) {
+        child[name].setEncoding("utf8");
+        child[name].on("data", (chunk) => {
+          for (const part of chunk.match(/[^\n]*\n|[^\n]+$/g) ?? []) {
+            const ended = part.endsWith("\n");
+            if (!dropping[name]) buffers[name] += part;
+            if (buffers[name].length > 16_384) {
+              buffers[name] = "";
+              dropping[name] = true; // Never emit a fragment of a long secret.
+            }
+            if (ended) {
+              emit(name, dropping[name] ? "[overlong output line omitted]" : buffers[name].trimEnd());
+              buffers[name] = ""; dropping[name] = false;
+            }
+          }
+        });
+      }
+      let error;
+      child.on("error", (e) => { error = e; });
+      child.on("close", (status, signal) => {
+        for (const name of ["stdout", "stderr"]) {
+          if (dropping[name] || buffers[name]) emit(name, dropping[name] ? "[overlong output line omitted]" : buffers[name]);
+        }
+        resolve(processResult({ status, signal, error, ...tails }, { ...opts, env }));
+      });
+    });
+  } catch (error) { return processResult({ error }, { ...opts, env }); }
+}