fix(update): gate the npm cache before shutdown and stop persisting vendor output (replaces #557)

bin/ocx.mjs

@@ -17,6 +17,10 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { isRealBunBinary } from "../src/lib/bun-binary-validator.mjs";
 import { npmInvocation } from "../src/update/npm-invocation.mjs";
+import {
+  npmCachePreflightFailureMessage,
+  runNpmCachePreflight,
+} from "../src/update/npm-cache-preflight.mjs";
 import { handoffWindowsTrayForUpdate, planWindowsTrayUpdate } from "../src/update/tray-update-plan.mjs";
 
 const PKG = "@bitkyc08/opencodex";
@@ -136,6 +140,12 @@ function runNpmSelfUpdate() {
     process.exit(0);
   }
 
+  const cachePreflight = runNpmCachePreflight();
+  if (!cachePreflight.ok) {
+    console.error(`opencodex: ${npmCachePreflightFailureMessage(cachePreflight.reason)}. Aborting before stopping the proxy.`);
+    process.exit(1);
+  }
+
   // Remember whether a background service manages the proxy BEFORE stopping — `ocx stop`
   // unloads it, so a successful update must refresh and restart it afterwards.
   const serviceStatePath = join(configDir(), "service-state.json");

docs-site/src/content/docs/ja/reference/cli/lifecycle.md

@@ -212,7 +212,7 @@ Windows ステータス トレイ アイコンをインストールして制御
 
 ### `ocx update [--tag latest|preview]`
 
-npm から opencodex を自己更新します。安定したインストールでは `@latest` を使用します。 `--tag latest|preview` を渡さない限り、プレビュー インストールは `@preview` に残ります。ソース チェックアウトを検出し、代わりに `git pull && bun install` を使用するように指示しますが、そのタグの最新バージョンをすでに使用している場合は何もしません。実行中のプロキシは、ファイルが置き換えられる前に停止されます。インストールされたサービスは再構築されて自動的に開始されますが、フォアグラウンド インストールでは次のステップとして `ocx start` が出力されます。
+npm から opencodex を自己更新します。安定したインストールでは `@latest` を使用します。 `--tag latest|preview` を渡さない限り、プレビュー インストールは `@preview` に残ります。ソース チェックアウトを検出し、代わりに `git pull && bun install` を使用するように指示しますが、そのタグの最新バージョンをすでに使用している場合は何もしません。npm インストールでは、何かを停止する前に Unix キャッシュの所有権とアクセスを上限付きで検査します。ネストされたシンボリックリンクは `lstat` で確認しますが追跡しません。Windows では、この Unix 専用検査を明示的にスキップします。検査に失敗した場合、トレイとプロキシを実行したまま更新を中止します。その後、実行中のプロキシはファイルが置き換えられる前に停止されます。インストールされたサービスは再構築されて自動的に開始されますが、フォアグラウンド インストールでは次のステップとして `ocx start` が出力されます。ダッシュボードの更新記録では、保存前にプロファイル／キャッシュのパスと UID/GID 値が秘匿されます。
 
 ```bash
 ocx update

docs-site/src/content/docs/ko/reference/cli/lifecycle.md

@@ -274,8 +274,12 @@ Windows 상태 트레이 아이콘을 설치하고 제어합니다. Windows 로
 npm에서 opencodex를 자체 업데이트합니다. 안정판 설치는 `@latest`를 사용하고, 미리보기 설치는
 `--tag latest|preview`를 주지 않으면 `@preview`를 유지합니다. 소스 체크아웃을 감지하면 대신
 `git pull && bun install`을 실행하라고 안내하고, 해당 태그에서 이미 최신 버전이면 아무 동작도 하지
-않습니다. 실행 중인 프록시가 있으면 파일을 교체하기 전에 중지합니다. 설치된 서비스는 자동으로 다시
-빌드해 시작하며, 포그라운드 설치에서는 다음 단계로 `ocx start`를 출력합니다.
+않습니다. npm 설치에서는 어떤 프로세스도 중지하기 전에 Unix 캐시의 소유권과 접근 가능성을 제한된
+범위에서 검사합니다. 중첩 심볼릭 링크는 `lstat`으로 확인하되 따라가지 않으며, Windows에서는 이
+Unix 전용 검사를 명시적으로 건너뜁니다. 검사에 실패하면 트레이와 프록시가 실행 중인 상태에서
+업데이트를 중단합니다. 그 다음 실행 중인 프록시가 있으면 파일을 교체하기 전에 중지합니다. 설치된
+서비스는 자동으로 다시 빌드해 시작하며, 포그라운드 설치에서는 다음 단계로 `ocx start`를 출력합니다.
+대시보드 업데이트 기록은 저장 전에 프로필/캐시 경로와 UID/GID 값을 가립니다.
 
 ```bash
 ocx update

docs-site/src/content/docs/reference/cli/lifecycle.md

@@ -325,8 +325,12 @@ if it is not running.
 Self-update opencodex from npm. Stable installs use `@latest`; preview installs stay on `@preview`
 unless you pass `--tag latest|preview`. It detects a source checkout and tells you to
 `git pull && bun install` instead, and is a no-op if you are already on the newest version for that
-tag. A running proxy is stopped before files are replaced; an installed service is rebuilt and
-started automatically, while a foreground installation prints `ocx start` as the next step.
+tag. Before stopping anything, npm installations run a bounded Unix cache ownership and access
+check. Nested symlinks are checked with `lstat` but not followed; Windows explicitly skips this
+Unix-only check. A failure aborts while the tray and proxy are still running. A running proxy is
+then stopped before files are replaced; an installed service is rebuilt and started automatically,
+while a foreground installation prints `ocx start` as the next step. Dashboard update records
+redact profile/cache paths and UID/GID values before they are persisted.
 
 ```bash
 ocx update

docs-site/src/content/docs/ru/reference/cli/lifecycle.md

@@ -295,9 +295,13 @@ one-click управление прокси. `start` и `stop` управляю
 Самообновить opencodex из npm. Стабильные установки используют `@latest`; preview-установки
 остаются на `@preview`, если только вы не передадите `--tag latest|preview`. Команда распознаёт
 source checkout и предлагает вместо этого `git pull && bun install`, а если у вас уже новейшая
-версия для выбранного тега, становится no-op. Перед заменой файлов работающий прокси
-останавливается; установленная служба автоматически пересобирается и запускается заново, а для
-foreground-установки печатается подсказка `ocx start`.
+версия для выбранного тега, становится no-op. Для npm-установок до остановки каких-либо процессов
+выполняется ограниченная проверка владельца и доступности Unix-кэша. Вложенные символические ссылки
+проверяются через `lstat`, но переход по ним не выполняется; в Windows эта Unix-проверка явно
+пропускается. При ошибке обновление отменяется, пока трей и прокси ещё работают. Затем перед заменой
+файлов работающий прокси останавливается; установленная служба автоматически пересобирается и
+запускается заново, а для foreground-установки печатается подсказка `ocx start`. В записях обновления
+дашборда пути профиля/кэша и значения UID/GID скрываются до сохранения.
 
 ```bash
 ocx update

docs-site/src/content/docs/zh-cn/reference/cli/lifecycle.md

@@ -209,7 +209,7 @@ ocx codex-shim uninstall
 
 ### `ocx update [--tag latest|preview]`
 
-从 npm 自更新 opencodex。稳定版安装使用 `@latest`；预览版安装保持在 `@preview`，除非你传入 `--tag latest|preview`。它会检测源码检出，并提示你改为运行 `git pull && bun install`；如果你已经是该标签的最新版本，则不会执行任何操作。在替换文件之前会先停止正在运行的代理；已安装的服务会自动重建并启动，而前台安装则会打印 `ocx start` 作为下一步。
+从 npm 自更新 opencodex。稳定版安装使用 `@latest`；预览版安装保持在 `@preview`，除非你传入 `--tag latest|preview`。它会检测源码检出，并提示你改为运行 `git pull && bun install`；如果你已经是该标签的最新版本，则不会执行任何操作。对于 npm 安装，它会在停止任何进程之前，对 Unix 缓存的所有权和访问权限执行有界检查。嵌套符号链接会通过 `lstat` 检查但不会跟随；Windows 会明确跳过这项仅适用于 Unix 的检查。检查失败时，更新会在托盘和代理仍运行的情况下中止。随后才会在替换文件之前停止正在运行的代理；已安装的服务会自动重建并启动，而前台安装则会打印 `ocx start` 作为下一步。持久化前，仪表板更新记录会隐去用户配置文件/缓存路径以及 UID/GID 值。
 
 ```bash
 ocx update

src/update/index.ts

@@ -4,6 +4,10 @@ import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { getConfigDir, loadConfig, readPid, readRuntimePort } from "../config";
 import { npmInvocation } from "./npm-invocation.mjs";
+import {
+  npmCachePreflightFailureMessage,
+  runNpmCachePreflight,
+} from "./npm-cache-preflight.mjs";
 import { handoffWindowsTrayForUpdate, planWindowsTrayUpdate } from "./tray-update-plan.mjs";
 import { withProcessRuntimeProvenance } from "../lib/bun-runtime";
 
@@ -178,6 +182,14 @@ export async function runUpdate(): Promise<void> {
     console.log(`Verified ${PKG}@${latest} integrity metadata ${integrity.integrity.slice(0, 24)}…`);
   }
 
+  if (installer === "npm") {
+    const cachePreflight = runNpmCachePreflight();
+    if (!cachePreflight.ok) {
+      console.error(`⚠️  ${npmCachePreflightFailureMessage(cachePreflight.reason)}. Aborting before stopping the proxy.`);
+      process.exit(1);
+    }
+  }
+
   const { bin, args: cmdArgs } = updateCommand(installer, tag, latest);
   const target = updateSpawnTarget(bin, cmdArgs);
   if (!target) {