@iislee/opencodex 2.11.0 → 2.35.0

package/src/update/job.ts

@@ -6,13 +6,17 @@ import {
   atomicWriteFile,
   getConfigDir,
   loadConfig,
+} from "../config";
+import {
   readPid,
   readRuntimePort,
   removePid,
   removeRuntimePort,
   verifyPidIdentity,
-} from "../config";
+} from "../config/process-state";
 import { isProcessAlive, killProxy } from "../lib/process-control";
+import { selfLaunchArgv } from "../lib/self-launch-argv";
+import { killWindowsSchedulerWrappers } from "../lib/windows-service-wrappers";
 import {
   buildWindowsElevatedArgumentList,
   resolveTrustedWindowsPowerShellExe,
@@ -37,6 +41,11 @@ import {
 import { isNewer } from "./notify";
 import { isRealBunBinary } from "../lib/bun-binary-validator.mjs";
 import { handoffWindowsTrayForUpdate, planWindowsTrayUpdate } from "./tray-update-plan.mjs";
+import {
+  npmCachePreflightFailureMessage,
+  runNpmCachePreflight,
+  type NpmCachePreflightReason,
+} from "./npm-cache-preflight.mjs";
 
 const RELEASE_NOTES_URL = "https://github.com/lidge-jun/opencodex/releases/latest";
 const UPDATE_JOB_FILENAME = "update-job.json";
@@ -244,9 +253,152 @@ function ensureJobDir(): void {
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
 }
 
+/**
+ * Describe external text without reproducing it.
+ *
+ * Use this wherever an `Error.message`, a vendor stream, or any string this module did not
+ * compose would otherwise be interpolated into a persisted field. The result names the error's
+ * TYPE and size — enough to tell a reader what class of failure occurred — and never its text,
+ * which is where the paths and account names live.
+ */
+/**
+ * A version string we are willing to repeat in a persisted field.
+ *
+ * Semver plus an optional prerelease/build tail, capped in length. Anything else is dropped
+ * rather than logged: `/healthz` is answered by whatever holds the port, so its `version` is
+ * external input on the same footing as an error message.
+ */
+function isVersionLike(value: unknown): value is string {
+  return typeof value === "string"
+    && value.length <= 64
+    && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(value);
+}
+
+function withheldSummary(error: unknown): string {
+  // `error.name` is writable, so it is external text like the message. A fixed classification
+  // is the only part of an unknown error we can state without repeating something we were
+  // handed: `new Error(...)` with `error.name = "Jane Doe"` was persisting the name verbatim.
+  const name = error instanceof Error ? "Error" : typeof error;
+  // NO MESSAGE TEXT, ever. An earlier version kept messages that carried no path, which sounds
+  // reasonable and is wrong: `spawn denied for Jane Doe` has no path in it and still names a
+  // person. There is no test on message CONTENT that separates a diagnostic from an identity,
+  // so the message does not cross this boundary at all.
+  const code = (error as { code?: unknown } | null)?.code;
+  // Only recognized codes — an arbitrary uppercase `error.code` can be attacker-shaped too.
+  const codeNote = typeof code === "string" && NPM_ERROR_CODES.has(code) ? ` ${code}` : "";
+  const text = error instanceof Error ? error.message : String(error ?? "");
+  // Node's own errors are structured the same way npm's output is: `syscall` and `errno` are
+  // named properties, not prose. Reading those gives a user the actual cause —
+  // `Error EACCES · syscall: mkdir · errno: -13` — without repeating a message that could name
+  // a person or a path. Both are shape-validated: a syscall is a short lowercase identifier and
+  // an errno is an integer, so neither can carry arbitrary text.
+  const parts = [`${name}${codeNote}`];
+  const syscall = (error as { syscall?: unknown } | null)?.syscall;
+  // Same explicit vocabulary as the npm field: a shape check accepts `janedoe`.
+  if (typeof syscall === "string" && POSIX_SYSCALLS.has(syscall)) parts.push(`syscall: ${syscall}`);
+  const errno = (error as { errno?: unknown } | null)?.errno;
+  if (typeof errno === "number" && Number.isInteger(errno)) parts.push(`errno: ${errno}`);
+  parts.push(`${Buffer.byteLength(text, "utf8")} bytes withheld`);
+  return parts.join(" · ");
+}
+
+/**
+ * Decide, per field, whether the value is ours to keep.
+ *
+ * `log` and `error` are composed from this module's own templates; every place that would have
+ * interpolated external text now calls `withheldSummary()` first, so the strings arriving here
+ * are ours by construction. `releaseNotesUrl` is compared against the module constant rather
+ * than pattern-matched, which is what stops a URL-shaped value from smuggling a path.
+ * `command` is rendered from validated parts.
+ */
+function brandOwnComposedText(key: string, value: unknown): unknown {
+  if (key === "releaseNotesUrl") {
+    return value === RELEASE_NOTES_URL ? value : "";
+  }
+  if (key === "command") {
+    // Render the command shape first, then apply the same path test as every other field. The
+    // renderer only understands space-separated arguments; anything else reaching this field is
+    // not a command we built and must not be trusted because of where it was stored.
+    return typeof value === "string" ? withholdIfPathBearing(renderSafeCommand(value)) : value;
+  }
+  // `log` and `error` are ours by construction, but a caller can still slip external text in by
+  // interpolating it. Withhold any value that carries an absolute path of any form — that is a
+  // narrow, unambiguous test on strings we already control, not the free-text classification
+  // that failed nine times.
+  if (typeof value === "string") return withholdIfPathBearing(value);
+  if (Array.isArray(value)) return value.map(item => (typeof item === "string" ? withholdIfPathBearing(item) : item));
+  return value;
+}
+
+/** Absolute paths cannot appear in text this module composed; if one does, it came from outside. */
+function withholdIfPathBearing(value: string): string {
+  const pathBearing = /[A-Za-z]:[\\/]/.test(value)          // C:\ or C:/
+    || /\\\\/.test(value)                                    // \\server\share
+    || /\\/.test(value)                                      // any backslash
+    || /~[\w.-]*\//.test(value)                              // ~/ or ~user/ anywhere
+    || /[%$][A-Za-z_]/.test(value)                           // %APPDATA%, $HOME
+    || /\/[\w.\-~%]+\//.test(value)                          // any two-segment path run
+    || /\b(?:Users|home|Documents and Settings|AppData|Profiles)\b/i.test(value)
+    || /\r?\n/.test(value);                                  // multi-line vendor output
+  if (!pathBearing) return value;
+  return `<withheld: ${Buffer.byteLength(value, "utf8")} bytes, may contain local paths>`;
+}
+
+/**
+ * Keep a command readable without persisting the launcher path it contains.
+ *
+ * The real npm worker command is `node /Users/<name>/.../bin/ocx.mjs update --tag latest`, so
+ * the account name is inside it by construction. Absolute path arguments are replaced with a
+ * placeholder and everything else — the binary name, the flags, the tag — is kept, which is the
+ * part a reader actually needs.
+ */
+function renderSafeCommand(value: string): string {
+  if (!value) return value;
+  // Rebuild from a recognized shape rather than filtering the string we were handed. Content
+  // cannot distinguish `npm install Mary-Jane` — an account name — from a legitimate package
+  // argument, so anything that is not this exact shape is withheld by the caller's path test.
+  const parts = value.trim().split(/\s+/);
+  const tool = parts[0] === "$" ? parts[1] : parts[0];
+  if (tool !== undefined && /^(?:npm|bun|pnpm|yarn|node)$/.test(tool)) {
+    const rendered = parts.map(part =>
+      /^(?:[A-Za-z]:[\\/]|[\\/]|~|\\\\)/.test(part) ? "<path>" : part);
+    // Only fixed flags, our own package spec, and placeholders survive; a bare word that is not
+    // one of those is treated as unknown input and the whole value is withheld.
+    const allowed = rendered.every(part =>
+      part === "$" || part === "<path>"
+      || /^(?:npm|bun|pnpm|yarn|node)$/.test(part)
+      || /^-{1,2}[\w-]+$/.test(part)
+      || /^(?:install|add|update|i)$/.test(part)
+      || /^opencodex(?:@[\w.\-]+)?$/.test(part)
+      || /^(?:latest|preview|next|beta)$/.test(part)
+      || /^\d[\w.\-]*$/.test(part));
+    if (allowed) return rendered.join(" ");
+  }
+  return `<withheld: ${Buffer.byteLength(value, "utf8")} bytes, unrecognized command shape>`;
+}
+
+/**
+ * Fields that can carry free-form text and therefore need checking at the write boundary.
+ *
+ * The rest of the record is a closed vocabulary — statuses, channels, installers, versions, an
+ * id, timestamps — so checking it only risks mangling values that were never a disclosure
+ * route. Naming the risky fields keeps the boundary narrow and auditable.
+ */
+const FREE_TEXT_JOB_FIELDS = new Set(["command", "error", "log", "releaseNotesUrl"]);
+
+/** Apply the per-field rule at the single point where a job reaches disk. */
+function sanitizePersistedUpdateJob(job: UpdateJobState): UpdateJobState {
+  return Object.fromEntries(
+    Object.entries(job).map(([key, item]) => [
+      key,
+      FREE_TEXT_JOB_FIELDS.has(key) ? brandOwnComposedText(key, item) : item,
+    ]),
+  ) as UpdateJobState;
+}
+
 function writeJob(job: UpdateJobState): void {
   ensureJobDir();
-  atomicWriteFile(updateJobPath(), `${JSON.stringify(job, null, 2)}\n`);
+  atomicWriteFile(updateJobPath(), `${JSON.stringify(sanitizePersistedUpdateJob(job), null, 2)}\n`);
 }
 
 export function readUpdateJob(jobId?: string | null): UpdateJobState | null {
@@ -260,6 +412,13 @@ export function readUpdateJob(jobId?: string | null): UpdateJobState | null {
   }
 }
 
+/**
+ * Log lines are composed by this module, so brand them here rather than at nineteen call sites.
+ *
+ * The one thing a caller must never do is interpolate external text into a log line — an
+ * `Error.message`, a vendor stream, a path we were handed. Those go through
+ * `withheldSummary()`, which produces a branded description WITHOUT the text itself.
+ */
 function updateJob(job: UpdateJobState, patch: Partial<UpdateJobState>, logLine?: string): UpdateJobState {
   const current = readUpdateJob(job.id) ?? job;
   const next = {
@@ -306,7 +465,9 @@ export function restartCommand(
   const startArgs = pinPort
     ? [launcher, "start", "--port", String(Math.trunc(port))]
     : [launcher, "start"];
-  const svcArgs = serviceInstalled ? [launcher, ...(serviceArgs ?? ["service", "install"])] : startArgs;
+  // Default to the non-registering refresh: an update path reaching here has an already
+  // installed service, and `install` would demand elevation on Windows scheduler backends.
+  const svcArgs = serviceInstalled ? [launcher, ...(serviceArgs ?? ["service", "repair"])] : startArgs;
   if (installer === "npm") {
     const bin = nodeBin();
     const args = svcArgs;
@@ -400,14 +561,12 @@ export function spawnGuiUpdateWorker(
   channel: Channel,
   restart: boolean,
 ): UpdateWorkerProcess {
-  const script = process.argv[1];
-  const args = [
-    script,
+  const args = selfLaunchArgv([
     "__gui-update-worker",
     jobId,
     channel,
     restart ? "restart" : "no-restart",
-  ];
+  ]);
   if (process.platform !== "win32") {
     return spawn(process.execPath, args, {
       detached: true,
@@ -429,7 +588,7 @@ export function spawnGuiUpdateWorker(
   ].join("; ");
   const launched = spawnSync(
     resolveTrustedWindowsPowerShellExe(),
-    ["-NoProfile", "-NoLogo", "-NonInteractive", "-WindowStyle", "Hidden", "-Command", ps],
+    ["-NoProfile", "-NoLogo", "-NonInteractive", "-Command", ps],
     { encoding: "utf8", windowsHide: true, timeout: 15_000 },
   );
   const pid = Number(String(launched.stdout ?? "").trim().split(/\r?\n/).pop());
@@ -501,8 +660,7 @@ export function startUpdateJob(
   try {
     child = resolvedDeps.spawnWorkerFn(id, channel, restart);
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    updateJob(job, { status: "failed", error: `Could not start update worker: ${message}` }, "Update worker failed to start.");
+    updateJob(job, { status: "failed", error: `Could not start update worker: ${withheldSummary(error)}` }, "Update worker failed to start.");
     throw new UpdateJobError("Could not start update worker", 500, "update_worker_start_failed");
   }
   if (typeof child.pid !== "number" || !Number.isSafeInteger(child.pid) || child.pid <= 0) {
@@ -515,7 +673,7 @@ export function startUpdateJob(
     if (!current || current.pid !== child.pid || (current.status !== "running" && current.status !== "restarting")) return;
     updateJob(
       current,
-      { status: "failed", error: `Update worker failed to start: ${error.message}` },
+      { status: "failed", error: `Update worker failed to start: ${withheldSummary(error)}` },
       "Update worker emitted a startup error.",
     );
   });
@@ -523,6 +681,20 @@ export function startUpdateJob(
   return startedJob;
 }
 
+/**
+ * Run an update step and record WHAT HAPPENED, not what the tool printed.
+ *
+ * Raw installer output used to be persisted verbatim, which put local paths and account names
+ * into a stored file. Six rounds of trying to sanitize it after the fact each produced a new
+ * leak — a wrap inside the keyword, a wrap inside the account name, an indented continuation,
+ * three consecutive wraps, an empty continuation line. Every fix was an attempt to reconstruct
+ * arbitrary multi-line text well enough to match it, and that is not a problem a redactor can
+ * win: the leak surface is whatever npm decides to print.
+ *
+ * So the raw stream is no longer persisted at all. The job keeps the command, its exit status,
+ * and a bounded, structured summary — enough to tell a user which step failed and how, with no
+ * free-form vendor text passing through the boundary. Detailed output stays ephemeral.
+ */
 function runLoggedCommand(job: UpdateJobState, bin: string, args: string[], timeout: number): { status: number | null; signal: NodeJS.Signals | null } {
   job = updateJob(job, {}, `$ ${formatCommand(bin, args)}`);
   const result = spawnSync(bin, args, {
@@ -532,11 +704,171 @@ function runLoggedCommand(job: UpdateJobState, bin: string, args: string[], time
   });
   const stdout = typeof result.stdout === "string" ? result.stdout.trim() : "";
   const stderr = typeof result.stderr === "string" ? result.stderr.trim() : "";
-  if (stdout) job = updateJob(job, {}, stdout.slice(-4000));
-  if (stderr) updateJob(job, {}, stderr.slice(-4000));
+  const summary = summarizeCommandOutput(stdout, stderr, result.status, result.signal);
+  if (summary) updateJob(job, {}, summary);
   return { status: result.status, signal: result.signal };
 }
 
+/**
+ * Recognized npm/libc error codes, as an explicit set.
+ *
+ * A shape pattern like `E[A-Z]{3,}` is NOT a vocabulary: `C:\Users\ERROR\.npm` matches it, and
+ * the summary then re-emits the username the withheld output was protecting. Only codes on this
+ * list are surfaced, and only when they appear in npm's canonical `code <CODE>` position.
+ */
+const NPM_ERROR_CODES = new Set([
+  "EACCES", "EPERM", "ENOENT", "EEXIST", "ENOTDIR", "EISDIR", "EMFILE", "ENFILE",
+  "ENOSPC", "EROFS", "EXDEV", "ELOOP", "ENAMETOOLONG", "ENOTEMPTY", "EBUSY",
+  "EAGAIN", "ECONNRESET", "ECONNREFUSED", "ETIMEDOUT", "ENOTFOUND", "EAI_AGAIN",
+  "EPROTO", "ECONNABORTED", "EHOSTUNREACH", "ENETUNREACH", "EPIPE",
+  "E401", "E403", "E404", "E409", "E429", "E500", "E503",
+  "EINTEGRITY", "ERESOLVE", "ETARGET", "EPUBLISHCONFLICT", "ENEEDAUTH",
+  "EUSAGE", "EJSONPARSE", "EOTP", "EINVALIDTYPE", "ELIFECYCLE",
+  "ERR_SOCKET_TIMEOUT", "ERR_INVALID_ARG_TYPE", "ERR_MODULE_NOT_FOUND",
+]);
+
+/** npm prints `npm ERR! code EACCES`; anchor on that position rather than scanning free text. */
+const NPM_CODE_RECORD = /^\s*npm\s+ERR!\s+code\s+([A-Z][A-Z0-9_]{2,})\s*$/gm;
+
+/**
+ * npm's failure output is STRUCTURED, not prose: `npm error <field> <value>`, one field per
+ * line (`npm ERR!` on npm 9 and earlier). That is what makes a useful summary possible without
+ * reproducing text — we can read named fields and keep the ones whose value cannot be a path.
+ *
+ * Fields kept, with a real example of each:
+ *   code     E404, EACCES, ETARGET      the single most useful line for diagnosis
+ *   syscall  mkdir, open, getaddrinfo   what npm was doing
+ *   errno    -13                        the OS errno
+ *   notarget No matching version ...    version-resolution explanation, no path
+ *   404      404 Not Found - GET <url>  registry URL, no local path
+ *
+ * Deliberately NOT kept: `path`, `dest`, `file`, `stack`, and the bare `Error: ...` line —
+ * every one of those is a filesystem path by definition. `A complete log of this run can be
+ * found in: <path>` is dropped for the same reason.
+ */
+const NPM_FIELD_LINE = /^\s*npm\s+(?:error|ERR!)\s+([a-z0-9]+)\s+(.*)$/gim;
+
+/**
+ * POSIX syscall names npm actually reports. An explicit vocabulary, not a shape.
+ *
+ * `^[a-z][a-z0-9_]{1,20}$` accepts `janedoe`, which is the whole problem: allowlisting the
+ * FIELD NAME while leaving its VALUE free-form just moves the leak one level in.
+ */
+const POSIX_SYSCALLS = new Set([
+  "open", "openat", "close", "read", "write", "stat", "lstat", "fstat", "mkdir", "rmdir",
+  "unlink", "rename", "symlink", "readlink", "link", "chmod", "chown", "utimes", "access",
+  "scandir", "readdir", "copyfile", "realpath", "futime", "ftruncate", "fchmod", "fchown",
+  "connect", "getaddrinfo", "getnameinfo", "socket", "bind", "listen", "accept", "send",
+  "recv", "shutdown", "spawn", "spawnSync", "kill", "watch", "lchown", "lutimes", "mkdtemp",
+]);
+
+/** Per-field value contracts. A field is only kept when its value satisfies its own rule. */
+const KNOWN_REGISTRY_HOSTS = new Set([
+  "registry.npmjs.org",
+  "registry.yarnpkg.com",
+  "registry.npmmirror.com",
+  "npm.pkg.github.com",
+]);
+
+const NPM_FIELD_VALIDATORS: Record<string, (value: string) => string | null> = {
+  // A recognized code, nothing else.
+  code: value => (NPM_ERROR_CODES.has(value) ? value : null),
+  // A known syscall name, nothing else.
+  syscall: value => (POSIX_SYSCALLS.has(value) ? value : null),
+  // An integer, rendered from the parsed number so the original string never passes through.
+  errno: value => (/^-?\d{1,10}$/.test(value) ? String(Number(value)) : null),
+  // Version resolution: the FACT only.
+  //
+  // Two narrowing attempts failed here and the second is the instructive one. Extracting any
+  // `name@version` also matched `jane.doe@example.com`. Pinning the NAME to our own package
+  // still left the VERSION free: `@bitkyc08/opencodex@99.99.99-JaneDoe` is a valid-looking
+  // spec, and a semver prerelease identifier can encode anything — the same lesson the
+  // `/healthz` version taught in round 13.
+  //
+  // There is no trusted resolved version available at this call site, so the spec is not
+  // rendered at all. `code: ETARGET` plus this fact already tells a user their requested
+  // version does not exist, which is the diagnostic that matters.
+  notarget: () => "no matching version",
+};
+
+/**
+ * HTTP status lines carry a registry URL. Render it from parsed parts rather than echoing the
+ * line: a URL can embed userinfo (`https://Jane:pw@host/`) or a path, and the raw text also
+ * defeats the path test because `https:/` looks like a drive letter.
+ */
+function npmHttpStatusValue(field: string, value: string): string | null {
+  const url = /\bhttps?:\/\/[^\s]+/.exec(value)?.[0];
+  if (!url) return `HTTP ${field}`;
+  let parsed: URL;
+  try { parsed = new URL(url); } catch { return `HTTP ${field}`; }
+  // Only hosts we can name in advance. A shape check (`^[\w.-]+$`) accepts
+  // `janedoe.example`, a numeric host, or a punycode host — an arbitrary hostname is a
+  // disclosure channel, not a diagnostic. Knowing it was the public registry versus "some
+  // other host" is the part that helps, and that fits in an allowlist.
+  return KNOWN_REGISTRY_HOSTS.has(parsed.hostname.toLowerCase()) && !parsed.username && !parsed.password
+    ? `HTTP ${field} from ${parsed.hostname.toLowerCase()}`
+    : `HTTP ${field}`;
+}
+
+/**
+ * Extract the diagnostic fields npm names explicitly.
+ *
+ * Each kept value still passes `withholdIfPathBearing` before it is used: a registry URL is
+ * fine, but `syscall` and friends are only safe by convention, and a convention is not a
+ * guarantee. Values are length-capped so a hostile responder cannot pad the record.
+ */
+function npmDiagnosticFields(text: string): string[] {
+  const seen = new Map<string, string>();
+  for (const match of text.matchAll(NPM_FIELD_LINE)) {
+    const field = match[1]!.toLowerCase();
+    const value = match[2]!.trim();
+    if (seen.has(field) || !value || value.length > 160) continue;
+    // Every kept field is RENDERED from a validated value, never echoed. Allowlisting the field
+    // name alone left the value free-form, so `npm error syscall janedoe` walked straight
+    // through — the field was recognized and the value was never checked against anything.
+    const validate = NPM_FIELD_VALIDATORS[field];
+    const rendered = validate
+      ? validate(value)
+      : (/^(?:404|401|403|409|429)$/.test(field) ? npmHttpStatusValue(field, value) : null);
+    if (rendered === null) continue;
+    seen.set(field, rendered);
+  }
+  return [...seen].map(([field, value]) => `${field}: ${value}`);
+}
+
+/**
+ * Build a structured, path-free summary of a command's result.
+ *
+ * Only three things cross the boundary: how the process ended, how much it printed, and any
+ * recognized error codes. None of those can carry a filesystem path or an account name.
+ */
+export function summarizeCommandOutput(
+  stdout: string,
+  stderr: string,
+  status: number | null,
+  signal: NodeJS.Signals | null,
+): string | null {
+  if (!stdout && !stderr && status === 0) return null;
+
+  const parts: string[] = [];
+  parts.push(signal ? `terminated by ${signal}` : `exit ${status ?? "null"}`);
+
+  // Read npm's own named fields rather than reproducing its text. This is what makes a failed
+  // update diagnosable again: `code: E404 · 404: 404 Not Found - GET https://registry...` tells
+  // a user exactly what happened, and none of it can be a local path.
+  const fields = npmDiagnosticFields(`${stderr}\n${stdout}`);
+  if (fields.length > 0) parts.push(...fields);
+
+  const bytes = Buffer.byteLength(stdout, "utf8") + Buffer.byteLength(stderr, "utf8");
+  if (bytes > 0) {
+    parts.push(fields.length > 0
+      ? `${bytes} bytes of full output withheld`
+      : `${bytes} bytes of output withheld (no recognized diagnostic fields)`);
+  }
+
+  return parts.join(" · ");
+}
+
 /**
  * Tear down anything that would make `ocx start` exit 1 with "already running"
  * (service wrapper respawn, stale pidfile + live /healthz) before a pinned spawn.
@@ -604,7 +936,7 @@ function spawnDetachedStart(
   });
   child.once("error", err => {
     try {
-      updateJob(job, {}, `Pinned start spawn error: ${err instanceof Error ? err.message : String(err)}`);
+      updateJob(job, {}, `Pinned start spawn error: ${withheldSummary(err)}`);
     } catch { /* best-effort */ }
   });
   // Foreground `ocx start` keeps the listen process; EADDRINUSE/ghost races exit quickly
@@ -656,6 +988,8 @@ export interface RestartIo {
   serviceHealthTimeoutMs?: number;
   sleepMs?: (ms: number) => Promise<void>;
   now?: () => number;
+  /** Test seam — defaults to process.platform so the Windows-only branch is reachable off Windows. */
+  platform?: NodeJS.Platform;
   /** Service-mode install/reinstall command (defaults to spawnSync via runLoggedCommand). */
   runService?: (
     job: UpdateJobState,
@@ -790,11 +1124,17 @@ async function restartAfterUpdate(
     const preServiceAllow = reclaimKillAllowlist();
     const freed = await waitFn(port, hostname, reclaimOptsFor(preServiceAllow));
     let skipServiceInstall = false;
-    // Windows GUI update worker sets OCX_SERVICE=1 and is never elevated.
-    // `schtasks /create` will UAC-fail and can race the subsequent direct start.
-    // Keep systemd/launchd reinstall on non-Windows supervisors.
-    if (process.platform === "win32" && process.env.OCX_SERVICE === "1") {
-      updateJob(job, {}, "Skipping service reinstall from the non-elevated update worker; falling back to a direct proxy start.");
+    // This skip existed because the refresh ran `ocx service install`, whose Windows
+    // scheduler path always reaches `schtasks /create` — elevation the GUI update worker
+    // (OCX_SERVICE=1) never has. `service repair` rewrites the wrapper assets and
+    // restarts the EXISTING task with no `/create`, so the reason no longer applies and
+    // skipping would leave the dashboard-triggered update — the most common Windows
+    // path — with a stale service it could have refreshed.
+    //
+    // Only a caller that still passes install argv keeps the old behavior.
+    const refreshRegisters = (svcArgs ?? []).includes("install");
+    if ((io.platform ?? process.platform) === "win32" && process.env.OCX_SERVICE === "1" && refreshRegisters) {
+      updateJob(job, {}, "Skipping service re-registration from the non-elevated update worker; falling back to a direct proxy start.");
       skipServiceInstall = true;
     }
     if (!freed && !skipServiceInstall) {
@@ -804,8 +1144,16 @@ async function restartAfterUpdate(
         `Port ${port} still busy after ${Math.trunc(RESTART_PORT_RECLAIM_MS / 1000)}s; refusing to hop — reinstall may fail until the port is free.`
           + ` ${formatPortHolders(port, listPids, verifyOcx, preServiceAllow)}`,
       );
-      const liveAfter = listPids(port).filter(pid => pid !== process.pid && aliveFn(pid));
-      if (liveAfter.length === 0) {
+      const liveScan: ListenPidScan = io.scanListenPidsFn
+        ? io.scanListenPidsFn(port)
+        : io.listListenPidsFn
+          // Test seam: an injected list represents a successful scan.
+          ? { ok: true, pids: io.listListenPidsFn(port) }
+          : scanListenPids(port);
+      const liveAfter = liveScan.ok
+        ? liveScan.pids.filter(pid => pid !== process.pid && aliveFn(pid))
+        : null;
+      if (liveAfter !== null && liveAfter.length === 0) {
         // Non-elevated `service install` will UAC-fail anyway; skip straight to
         // the direct-start fallthrough instead of burning another minute on it.
         updateJob(job, {}, "Skipping service reinstall after reclaim timeout with no live holders; falling back to a direct proxy start.");
@@ -821,24 +1169,17 @@ async function restartAfterUpdate(
         const result = run(job, cmd.bin, cmd.args);
         serviceOk = result.status === 0;
         if (!serviceOk) {
-          // On Windows, `schtasks /create` requires an elevated token. The update worker
-          // inherits the (non-admin) proxy's privileges, so a service-managed install
-          // updated from the GUI or a normal terminal fails here with access denied.
-          // Falling back to a direct proxy start keeps the update from leaving the proxy
-          // stopped; the stale service manager can be refreshed later with an admin
-          // `ocx service install`.
-          //
-          // That advice is Windows-only, and on macOS/Linux it now actively misleads:
-          // `ocx service install` gained a non-zero exit for a service that registers
-          // but does not serve, so this branch fires there for a reason elevation
-          // cannot fix. Point at the command that prints the real reason instead.
+          // The refresh that just failed was `ocx service repair` (serviceReinstallArgs),
+          // which needs no elevation because it never calls `schtasks /create`. Advising
+          // `install` here would send the user to re-registration — a UAC prompt on
+          // Windows and a possible WinSW-to-scheduler backend switch — to fix a service
+          // that is already registered. Point at the same command that failed so its
+          // output explains why, on every platform.
           updateJob(
             job,
             {},
-            `Service reinstall failed (exit ${result.status ?? "?"}); falling back to a direct proxy start.`
-            + (process.platform === "win32"
-              ? " Run 'ocx service install' as administrator to refresh the background service manager."
-              : " Run 'ocx service install' by hand to see the reason, then 'ocx service status'."),
+            `Service refresh failed (exit ${result.status ?? "?"}); falling back to a direct proxy start.`
+            + " Run 'ocx service repair' by hand to see the reason, then 'ocx service status'.",
           );
         }
       } finally {
@@ -1041,26 +1382,16 @@ function stopWindowsServiceWrappersBestEffort(): void {
  * Best-effort termination of surviving Windows scheduler launcher/wrapper processes.
  * `schtasks /end` ends the task instance but often leaves wscript/cmd running the
  * `:loop` batch, which brings the proxy back during post-update reclaim.
+ *
+ * This used to match the bare filenames with -like '*name*', which could stop a
+ * wrapper belonging to a DIFFERENT OpenCodex home under the same account. The
+ * shared killer scopes to this home's canonical paths as complete tokens.
  */
 function killWindowsServiceWrapperProcesses(): void {
-  if (process.platform !== "win32") return;
-  try {
-    const ps = [
-      "$pats = @('opencodex-service.cmd','opencodex-service-launcher.vbs');",
-      "Get-CimInstance Win32_Process | Where-Object {",
-      "  if ($_.ProcessId -eq $PID) { return $false };",
-      "  $c = $_.CommandLine; if (-not $c) { return $false };",
-      "  foreach ($p in $pats) { if ($c -like ('*' + $p + '*')) { return $true } };",
-      "  $false",
-      "} | ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }",
-    ].join(" ");
-    spawnSync(resolveTrustedWindowsPowerShellExe(), [
-      "-NoProfile", "-NoLogo", "-NonInteractive", "-WindowStyle", "Hidden",
-      "-Command", ps,
-    ], { stdio: "ignore", timeout: 5000, windowsHide: true });
-  } catch {
-    /* best-effort */
-  }
+  killWindowsSchedulerWrappers({
+    scriptPath: join(getConfigDir(), "opencodex-service.cmd"),
+    launcherPath: join(getConfigDir(), "opencodex-service-launcher.vbs"),
+  });
 }
 
 /** Exposed for tests: drives the non-service restart path with injected io. */
@@ -1076,7 +1407,7 @@ function restartFailureHint(port: number): string {
   return `Update installed, but the restarted proxy did not stay healthy on port ${port}. `
     + `Try 'ocx start --port ${port}'. `
     + "If the update log shows bun postinstall or EPERM warnings, "
-    + "reinstall with 'npm install -g --allow-scripts=bun @iislee/opencodex'.";
+    + "reinstall with 'npm install -g --allow-scripts=bun @bitkyc08/opencodex'.";
 }
 
 type AwaitHealthyResult =
@@ -1192,7 +1523,11 @@ async function defaultProbeProxyIdentity(
     if (!isOpencodexHealthz(body)) return null;
     return {
       pid: typeof body?.pid === "number" ? body.pid : null,
-      ...(typeof body?.version === "string" ? { version: body.version } : {}),
+      // Validate the shape at the boundary where the value ENTERS, not where it is logged.
+      // `/healthz` is answered by whatever is listening on that port, so a hostile or confused
+      // responder can return any string here — and the restart-evidence reasons below
+      // interpolate it into a persisted field. A version is a version or it is nothing.
+      ...(isVersionLike(body?.version) ? { version: body.version } : {}),
     };
   } catch {
     return null;
@@ -1227,18 +1562,22 @@ export function npmSelfUpdateRestartEvidence(
     }
     if (livePid !== null) {
       if (expected !== null && identity.version && identity.version !== expected) {
-        return { ok: false, reason: `new pid but version ${identity.version} !== expected ${expected}` };
+        // Never echo the REPORTED version: `/healthz` is answered by whatever holds the port,
+        // and `2.7.41-JaneDoe` is valid semver. Say that it mismatched, and name only the
+        // version we expected — which is ours.
+        return { ok: false, reason: `new pid but reported version did not match expected ${expected}` };
       }
       return { ok: true, detail: `pid changed ${oldPid}→${livePid}` };
     }
     // Pre-update PID known but healthz omitted pid — only accept matching target version.
-    if (versionMatches) return { ok: true, detail: `version ${identity.version}` };
+    // On a match the reported value equals `expected`, so render the trusted one.
+    if (versionMatches) return { ok: true, detail: `version ${expected}` };
     return { ok: false, reason: "no PID in healthz and version did not match the update target" };
   }
 
-  if (versionMatches) return { ok: true, detail: `version ${identity.version}` };
+  if (versionMatches) return { ok: true, detail: `version ${expected}` };
   if (expected !== null && identity.version && identity.version !== expected) {
-    return { ok: false, reason: `version ${identity.version} !== expected ${expected}` };
+    return { ok: false, reason: `reported version did not match expected ${expected}` };
   }
   return { ok: false, reason: "no pre-update PID capture and no expected-version match" };
 }
@@ -1380,9 +1719,36 @@ async function confirmNpmExplicitRestart(
   return true;
 }
 
-export async function runGuiUpdateWorker(jobId: string, channel: Channel, restart: boolean): Promise<void> {
+/**
+ * Test seams for the GUI update worker.
+ *
+ * The cache pre-flight and the install/stop step were previously reached only through module
+ * globals, so "the gate runs before the stop" could only be asserted by comparing source-string
+ * positions — a test that stays green even if the call is unreachable. These make the ordering
+ * observable: a failed pre-flight must leave `runCommand` untouched.
+ */
+export interface GuiUpdateWorkerIo {
+  cachePreflightFn?: () => { ok: boolean; reason: string };
+  /** Force the resolved update target. A source checkout otherwise aborts before the npm branch. */
+  checkForUpdateFn?: (channel: Channel) => ReturnType<typeof checkForUpdate>;
+  /** Bypass the registry integrity probe, which runs before the cache gate and needs network. */
+  integrityFn?: (version: string | null) => ReturnType<typeof checkUpdatePackageIntegrity>;
+  runCommandFn?: (
+    job: UpdateJobState,
+    bin: string,
+    args: string[],
+    timeout: number,
+  ) => { status: number | null; signal: NodeJS.Signals | null };
+}
+
+export async function runGuiUpdateWorker(
+  jobId: string,
+  channel: Channel,
+  restart: boolean,
+  io: GuiUpdateWorkerIo = {},
+): Promise<void> {
   let job = readUpdateJob(jobId);
-  const check = checkForUpdate(channel);
+  const check = (io.checkForUpdateFn ?? checkForUpdate)(channel);
   const now = new Date().toISOString();
   // Capture the live listen target BEFORE the update command runs: the stop-first update
   // flow clears pid/runtime state, so this is the last moment the real port is knowable.
@@ -1427,7 +1793,7 @@ export async function runGuiUpdateWorker(jobId: string, channel: Channel, restar
     // Pre-flight integrity metadata check (same lanes as the CLI): anomalous registry
     // metadata for a resolved version fails the job BEFORE anything is spawned or the
     // proxy is stopped; transient registry failure degrades to a logged skip.
-    const integrity = checkUpdatePackageIntegrity(check.latestVersion);
+    const integrity = (io.integrityFn ?? checkUpdatePackageIntegrity)(check.latestVersion);
     if (integrity.ok === false) {
       updateJob(job, { status: "failed", error: integrity.reason });
       return;
@@ -1444,6 +1810,17 @@ export async function runGuiUpdateWorker(jobId: string, channel: Channel, restar
       command: cmd.display,
     }, integrityLine);
 
+    if (check.installer === "npm") {
+      const cachePreflight = (io.cachePreflightFn ?? runNpmCachePreflight)();
+      if (!cachePreflight.ok) {
+        updateJob(job, {
+          status: "failed",
+          error: npmCachePreflightFailureMessage(cachePreflight.reason as NpmCachePreflightReason),
+        }, "Update aborted before stopping the proxy because the npm cache pre-flight failed.");
+        return;
+      }
+    }
+
     if (process.platform === "win32") {
       try {
         const { getWindowsTrayStatus, startWindowsTray, stopWindowsTray } = await import("../tray/windows");
@@ -1460,7 +1837,7 @@ export async function runGuiUpdateWorker(jobId: string, channel: Channel, restar
       } catch (error) {
         updateJob(job, {
           status: "failed",
-          error: `Could not stop the Windows tray; aborting before package replacement: ${error instanceof Error ? error.message : String(error)}`,
+          error: `Could not stop the Windows tray; aborting before package replacement: ${withheldSummary(error)}`,
         });
         return;
       }
@@ -1471,7 +1848,7 @@ export async function runGuiUpdateWorker(jobId: string, channel: Channel, restar
     - 대안 분석: (1) 서버에서 runUpdate 직접 호출: process.exit/stdio/실행 파일 교체 위험. (2) GUI에서 CLI 명령 안내만 제공: 자동 업데이트 UX 부족. (3) 숨은 worker가 Node launcher/Bun 전역 명령을 실행: 상태 추적과 안전한 재시작이 가능.
     - 선택 근거: 현재 CLI의 npm self-update 우회를 재사용하면서도 GUI 서버 요청 생명주기와 설치 작업을 분리할 수 있어 가장 안정적이다.
     */
-    const result = runLoggedCommand(job, cmd.bin, cmd.args, UPDATE_TIMEOUT_MS);
+    const result = (io.runCommandFn ?? runLoggedCommand)(job, cmd.bin, cmd.args, UPDATE_TIMEOUT_MS);
     if (result.status !== 0) {
       if (trayWasRunning) {
         try {
@@ -1489,11 +1866,11 @@ export async function runGuiUpdateWorker(jobId: string, channel: Channel, restar
     }
 
     if (trayWasInstalled) {
-      const trayArgs = [process.argv[1], ...planWindowsTrayUpdate({ installed: trayWasInstalled, running: trayWasRunning }).installArgs];
+      const trayArgs = selfLaunchArgv(planWindowsTrayUpdate({ installed: trayWasInstalled, running: trayWasRunning }).installArgs);
       const tray = runLoggedCommand(job, process.execPath, trayArgs, 20_000);
       if (tray.status !== 0) {
         updateJob(job, {}, "Windows tray refresh failed; run 'ocx tray install'.");
-        if (trayWasRunning) runLoggedCommand(job, process.execPath, [process.argv[1], "tray", "start"], 15_000);
+        if (trayWasRunning) runLoggedCommand(job, process.execPath, selfLaunchArgv(["tray", "start"]), 15_000);
       }
     }
 
@@ -1514,7 +1891,7 @@ export async function runGuiUpdateWorker(jobId: string, channel: Channel, restar
     }
     updateJob(job, {
       status: "failed",
-      error: err instanceof Error ? err.message : String(err),
+      error: withheldSummary(err),
     });
   }
 }