@bitkyc08/opencodex 2.10.2 → 2.11.0

package/src/update/job.ts

@@ -37,6 +37,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";
@@ -238,9 +243,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 {
@@ -254,6 +402,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 = {
@@ -495,8 +650,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) {
@@ -509,7 +663,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.",
     );
   });
@@ -517,6 +671,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, {
@@ -526,11 +694,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.
@@ -598,7 +926,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
@@ -1187,7 +1515,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;
@@ -1222,18 +1554,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" };
 }
@@ -1375,9 +1711,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.
@@ -1422,7 +1785,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;
@@ -1439,6 +1802,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");
@@ -1455,7 +1829,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;
       }
@@ -1466,7 +1840,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 {
@@ -1509,7 +1883,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),
     });
   }
 }

package/src/update/npm-cache-preflight.d.mts

@@ -0,0 +1,47 @@
+import type { spawnSync } from "node:child_process";
+
+export type NpmCachePreflightReason =
+  | "cache_accessible"
+  | "cache_entry_foreign_owner"
+  | "cache_entry_inaccessible"
+  | "cache_path_malformed"
+  | "inspection_incomplete"
+  | "npm_config_failed"
+  | "npm_unavailable"
+  | "windows_skip"
+  | "worker_failed"
+  | "worker_output_malformed"
+  | "worker_timeout";
+
+export interface NpmCachePreflightResult {
+  ok: boolean;
+  reason: NpmCachePreflightReason;
+}
+
+export interface NpmCacheInspectionOptions {
+  expectedUid?: number;
+  maxDepth?: number;
+  maxEntries?: number;
+  nowMs?: () => number;
+  /** Test seam: resolve a symlinked cache root. Defaults to realpathSync. */
+  realpathFn?: (path: string) => string;
+  /** Test seam: resolve an entry's owner uid. Defaults to the lstat result. */
+  uidOf?: (path: string, stat: { uid: number }) => number;
+  timeoutMs?: number;
+}
+
+export interface NpmCachePreflightOptions {
+  env?: NodeJS.ProcessEnv;
+  execPath?: string;
+  platform?: NodeJS.Platform;
+  spawnSyncFn?: typeof spawnSync;
+  timeoutMs?: number;
+}
+
+export function inspectNpmCacheDirectory(
+  cachePath: string,
+  options?: NpmCacheInspectionOptions,
+): NpmCachePreflightResult;
+
+export function runNpmCachePreflight(options?: NpmCachePreflightOptions): NpmCachePreflightResult;
+export function npmCachePreflightFailureMessage(reason: NpmCachePreflightReason): string;