@techysy/10router 1.1.3 → 1.2.0

package/src/cli/i18n/locales/zh-CN/core.json

@@ -1,5 +1,5 @@
 {
-  "help.text": "用法: {bin} [选项]\n\n选项:\n  -p, --port <端口>   服务运行端口(默认: {port})\n  -H, --host <主机>   绑定地址(默认: {host})\n  -n, --no-browser    不自动打开浏览器\n  -l, --log           显示服务日志(默认隐藏)\n  -t, --tray          以系统托盘模式运行(后台)\n  --skip-update       跳过自动更新检查\n  -h, --help          显示本帮助\n  -v, --version       显示版本\n\n命令:\n  xai video --prompt \"...\" --output video.mp4\n                      通过运行中的网关生成 Grok Imagine 视频\n                      (见: {bin} xai video --help)",
+  "help.text": "用法: {bin} [选项]\n\n选项:\n  -p, --port <端口>   服务运行端口(默认: {port})\n  -H, --host <主机>   绑定地址(默认: {host})\n  -n, --no-browser    不自动打开浏览器\n  -l, --log           显示服务日志(默认隐藏)\n  -t, --tray          以系统托盘模式运行(后台)\n  --no-tray           不创建托盘图标(服务照常运行)\n  --skip-update       跳过自动更新检查\n  -h, --help          显示本帮助\n  -v, --version       显示版本\n\n命令:\n  xai video --prompt \"...\" --output video.mp4\n                      通过运行中的网关生成 Grok Imagine 视频\n                      (见: {bin} xai video --help)\n  doctor [--json] [--port <端口>]\n                      诊断当前安装 —— 版本、残留服务、数据库驱动、运行时依赖、端口(只读)",
 
   "error.standaloneMissing": "错误: 未找到 standalone 构建产物。",
   "error.standaloneHint": "请先运行 'npm run build:cli'。",
@@ -29,12 +29,52 @@
   "launcher.crashedRestarting": "\n⚠️  服务已退出(code={code}),将在 {seconds} 秒后重启...({attempt}/{max})",
   "launcher.crashLogHeader": "\n--- 服务崩溃日志 ---",
   "launcher.crashLogFooter": "--- 崩溃日志结束 ---",
+  "launcher.staleServerKilled": "\n🔁 检测到旧构建的服务进程仍在运行（运行 v{running}，磁盘已是 v{disk}）——正在停止它，让新构建接管端口。",
+  "launcher.staleServerNoPid": "\n⚠️ 一个不同构建的服务进程（v{running}）占着端口，但没有 PID 文件可安全停止——仍继续启动。若启动失败，请退出另一个实例后重试。",
 
+  "launcher.trayUnavailable": "托盘图标不可用({error})，服务继续在后台运行。",
+  "launcher.traySkipped": "已禁用托盘图标，服务继续在后台运行。",
   "menu.interfaceTitle": "选择界面 (v{version})",
   "menu.serverSubtitle": "🚀 服务地址: {url}",
   "menu.updateTo": "更新到 v{latest}(当前 v{current})",
   "menu.webUi": "Web 界面(在浏览器中打开)",
   "menu.terminalUi": "终端界面(交互式 CLI)",
   "menu.hideToTray": "隐藏到托盘(后台运行)",
-  "menu.exit": "退出"
+  "menu.exit": "退出",
+  "doctor.title": "10router doctor — {version}，端口 {port}",
+  "doctor.help": "用法: 10router doctor [选项]\n\n诊断当前安装: 版本、残留服务、数据库驱动、运行时依赖、端口与数据目录。\n全程只读 —— 不会安装、修复、重启或结束任何进程。\n\n选项:\n  --json              输出机器可读报告(结构稳定)\n  -p, --port <端口>   要检查的端口(默认: 20128)\n  -h, --help          显示本帮助\n\n任一项标红时退出码为 1，否则为 0。",
+  "doctor.summaryOk": "全部通过 —— {ok} 项正常，{yellow} 项提醒。",
+  "doctor.summaryRed": "发现 {red} 个问题、{yellow} 项提醒。标 ❌ 的行才是要处理的。",
+  "doctor.readOnlyHint": "只读: 本命令没有改动任何东西。",
+  "doctor.version.ok": "版本: 启动器 {launcher}、磁盘 {disk}、运行中 {server}",
+  "doctor.version.no-server-version": "版本: 端口 {port} 有服务在应答，但没有返回 10router 的版本号",
+  "doctor.version.mismatch": "版本不一致: 启动器 {launcher}、磁盘 {disk}、运行中 {server}",
+  "doctor.stale-process.ok": "无残留服务: 端口 {port} 上没有在服务其他构建的进程",
+  "doctor.stale-process.unverified": "pid 文件记录了 {pidFilePid}，但端口 {port} 没有任何版本应答 —— 无法确认它是否陈旧",
+  "doctor.stale-process.no-marker": "缺少版本标记 {file}: 仍在运行的旧构建无法察觉磁盘已更新(运行中 {server}，启动器 {disk})",
+  "doctor.stale-process.stale": "陈旧构建: 端口 {port} 在服务 {server}，而磁盘上是 {disk} —— 重启以加载新构建",
+  "doctor.stale-process.pid-mismatch": "pid 文件记录 {pidFilePid}，但端口 {port} 由 {owners} 占用",
+  "doctor.build.ok": "构建: {dir} 完整({version})",
+  "doctor.build.missing-files": "构建不完整: {dir} 缺少 {missing} —— 上次升级没走完",
+  "doctor.build.no-version": "构建 {dir} 里没有可读的 package.json —— 请重新安装",
+  "doctor.build.version-mismatch": "磁盘构建是 {version}，启动器是 {launcher} —— 升级只做了一半",
+  "doctor.driver.ok": "数据库: 驱动 {driver}",
+  "doctor.driver.no-health": "数据库: /api/health 无应答 —— 服务没在运行，或版本太旧不上报驱动",
+  "doctor.driver.no-driver": "数据库: 没有可用驱动，runtime 里也没有 better-sqlite3 副本。最后一次驱动报错: {error}",
+  "doctor.driver.not-initialized": "数据库: 尚未确定驱动 —— 属正常，/api/health 故意不初始化数据库，首次查询后会填上",
+  "doctor.driver.fallback": "数据库: 正在使用降级驱动 {driver} —— 首选驱动被跳过: {error}",
+  "doctor.runtime-deps.ok": "运行时依赖: 已安装并登记在 {dir}",
+  "doctor.runtime-deps.no-runtime": "运行时依赖: {dir} 还不存在 —— 首次启动时会创建",
+  "doctor.runtime-deps.unregistered": "运行时依赖: {orphaned} 已装在 {dir}，但没登记进它的 package.json —— 下次在该目录 npm install 会被删掉",
+  "doctor.runtime-deps.missing": "运行时依赖: {dir} 里未安装 {missing}(有降级方案兜底)",
+  "doctor.runtime-deps.broken-artifact": "运行时依赖: {broken} 已装在 {dir} 但不可用 —— 它需要的编译产物缺失，而 npm 仍认为它装好了。请重装(或删除 {dir}/node_modules 后重启)。",
+  "doctor.port.ok": "端口 {port}: 空闲，或由本安装占用",
+  "doctor.port.orphan-pidfile": "端口 {port} 已空闲，但 {file} 还记着 pid {pidFilePid}",
+  "doctor.port.foreign": "端口 {port} 被其他进程占用(pid {owners})",
+  "doctor.tray.ok": "托盘: 当前平台可用({platform})",
+  "doctor.tray.missing": "托盘: 未安装 systray2 —— 无托盘也能正常提供服务",
+  "doctor.data-dir.ok": "数据目录: {dir}",
+  "doctor.data-dir.missing": "数据目录 {dir} 还不存在 —— 首次启动时创建",
+  "doctor.data-dir.not-writable": "数据目录 {dir} 不可写",
+  "doctor.data-dir.legacy-pending": "旧的 9Router 数据还在 {legacy} —— 下次启动会迁移进 {dir}"
 }

package/src/cli/i18n/locales/zh-CN/settings.json

@@ -14,7 +14,7 @@
   "menus.settings.tunnelOff": "关闭隧道",
   "menus.settings.rtkToggle": "Token Saver (RTK): {state} → 点击切换",
   "menus.settings.headroomToggle": "Token Saver (Headroom): {state} → 点击切换",
-  "menus.settings.resetPassword": "🔑 重置密码为默认值",
+  "menus.settings.resetPassword": "🔑 重置密码",
   "menus.settings.authModeAlready": "🔓 重置认证模式(当前已是密码模式)",
   "menus.settings.authModeReset": "🔓 重置认证模式为密码(当前: {mode})",
   "menus.settings.resetAuthConfirm": "确定将认证模式重置为密码(禁用 OIDC)吗？",
@@ -29,7 +29,7 @@
   "menus.settings.tokenSaverDisabled": "Token Saver 已关闭",
   "menus.settings.headroomEnabledMsg": "Headroom 已开启",
   "menus.settings.headroomDisabledMsg": "Headroom 已关闭",
-  "menus.settings.resetPwConfirm": "确定将仪表盘密码重置为默认值「{default}」吗？",
-  "menus.settings.resetPwDone": "密码已重置,默认值: {default}",
+  "menus.settings.resetPwConfirm": "确定重置仪表盘密码吗？将生成一个新的随机密码，并在此显示一次。",
+  "menus.settings.resetPwDone": "密码已重置。新密码: {password} —— 只显示这一次，请立即保存",
   "menus.settings.resetPwFailed": "重置密码失败: {error}"
 }

package/src/cli/i18n/locales/zh-TW/core.json

@@ -1,5 +1,5 @@
 {
-  "help.text": "用法: {bin} [選項]\n\n選項:\n  -p, --port <連接埠>   服務執行連接埠(預設: {port})\n  -H, --host <主機>     綁定位址(預設: {host})\n  -n, --no-browser      不自動開啟瀏覽器\n  -l, --log             顯示服務日誌(預設隱藏)\n  -t, --tray            以系統列模式執行(背景)\n  --skip-update         略過自動更新檢查\n  -h, --help            顯示本說明\n  -v, --version         顯示版本\n\n命令:\n  xai video --prompt \"...\" --output video.mp4\n                      透過執行中的閘道產生 Grok Imagine 影片\n                      (見: {bin} xai video --help)",
+  "help.text": "用法: {bin} [選項]\n\n選項:\n  -p, --port <連接埠>   服務執行連接埠(預設: {port})\n  -H, --host <主機>     綁定位址(預設: {host})\n  -n, --no-browser      不自動開啟瀏覽器\n  -l, --log             顯示服務日誌(預設隱藏)\n  -t, --tray            以系統列模式執行(背景)\n  --no-tray             不建立托盤圖示(服務照常執行)\n  --skip-update         略過自動更新檢查\n  -h, --help            顯示本說明\n  -v, --version         顯示版本\n\n命令:\n  xai video --prompt \"...\" --output video.mp4\n                      透過執行中的閘道產生 Grok Imagine 影片\n                      (見: {bin} xai video --help)\n  doctor [--json] [--port <連接埠>]\n                      診斷目前安裝 —— 版本、殘留服務、資料庫驅動、執行階段相依、連接埠(唯讀)",
 
   "error.standaloneMissing": "錯誤: 未找到 standalone 建置產物。",
   "error.standaloneHint": "請先執行 'npm run build:cli'。",
@@ -29,12 +29,52 @@
   "launcher.crashedRestarting": "\n⚠️  服務已結束(code={code}),將於 {seconds} 秒後重新啟動...({attempt}/{max})",
   "launcher.crashLogHeader": "\n--- 服務當機日誌 ---",
   "launcher.crashLogFooter": "--- 當機日誌結束 ---",
+  "launcher.staleServerKilled": "\n🔁 偵測到舊建置的服務行程仍在執行（執行 v{running}，磁碟已是 v{disk}）——正在停止它，讓新建置接管連接埠。",
+  "launcher.staleServerNoPid": "\n⚠️ 一個不同建置的服務行程（v{running}）占用連接埠，但沒有 PID 檔案可安全停止——仍繼續啟動。若啟動失敗，請結束另一個實例後重試。",
 
+  "launcher.trayUnavailable": "托盤圖示無法使用({error})，服務繼續在背景下執行。",
+  "launcher.traySkipped": "已停用托盤圖示，服務繼續在背景下執行。",
   "menu.interfaceTitle": "選擇介面 (v{version})",
   "menu.serverSubtitle": "🚀 服務位址: {url}",
   "menu.updateTo": "更新至 v{latest}(目前 v{current})",
   "menu.webUi": "Web 介面(在瀏覽器中開啟)",
   "menu.terminalUi": "終端機介面(互動式 CLI)",
   "menu.hideToTray": "隱藏到系統列(背景執行)",
-  "menu.exit": "結束"
+  "menu.exit": "結束",
+  "doctor.title": "10router doctor — {version}，連接埠 {port}",
+  "doctor.help": "用法: 10router doctor [選項]\n\n診斷目前安裝: 版本、殘留服務、資料庫驅動、執行階段相依、連接埠與資料目錄。\n全程唯讀 —— 不會安裝、修復、重啟或結束任何行程。\n\n選項:\n  --json              輸出機器可讀報告(結構穩定)\n  -p, --port <連接埠>   要檢查的連接埠(預設: 20128)\n  -h, --help          顯示本說明\n\n任一項標紅時離開碼為 1，否則為 0。",
+  "doctor.summaryOk": "全部通過 —— {ok} 項正常，{yellow} 項提醒。",
+  "doctor.summaryRed": "發現 {red} 個問題、{yellow} 項提醒。標 ❌ 的行才是要處理的。",
+  "doctor.readOnlyHint": "唯讀: 本命令沒有變更任何東西。",
+  "doctor.version.ok": "版本: 啟動器 {launcher}、磁碟 {disk}、執行中 {server}",
+  "doctor.version.no-server-version": "版本: 連接埠 {port} 有服務在回應，但沒有回報 10router 的版本",
+  "doctor.version.mismatch": "版本不一致: 啟動器 {launcher}、磁碟 {disk}、執行中 {server}",
+  "doctor.stale-process.ok": "無殘留服務: 連接埠 {port} 上沒有在服務其他建置的行程",
+  "doctor.stale-process.unverified": "pid 檔記錄了 {pidFilePid}，但連接埠 {port} 沒有任何版本回應 —— 無法確認它是否陳舊",
+  "doctor.stale-process.no-marker": "缺少版本標記 {file}: 仍在執行的舊建置無法察覺磁碟已更新(執行中 {server}，啟動器 {disk})",
+  "doctor.stale-process.stale": "陳舊建置: 連接埠 {port} 在服務 {server}，而磁碟上是 {disk} —— 重啟以載入新建置",
+  "doctor.stale-process.pid-mismatch": "pid 檔記錄 {pidFilePid}，但連接埠 {port} 由 {owners} 占用",
+  "doctor.build.ok": "建置: {dir} 完整({version})",
+  "doctor.build.missing-files": "建置不完整: {dir} 缺少 {missing} —— 上次升級沒走完",
+  "doctor.build.no-version": "建置 {dir} 裡沒有可讀的 package.json —— 請重新安裝",
+  "doctor.build.version-mismatch": "磁碟建置是 {version}，啟動器是 {launcher} —— 升級只做了一半",
+  "doctor.driver.ok": "資料庫: 驅動 {driver}",
+  "doctor.driver.no-health": "資料庫: /api/health 無回應 —— 服務沒在執行，或版本太舊不回報驅動",
+  "doctor.driver.no-driver": "資料庫: 沒有可用驅動，runtime 裡也沒有 better-sqlite3 副本。最後一次驅動錯誤: {error}",
+  "doctor.driver.not-initialized": "資料庫: 尚未確定驅動 —— 屬正常，/api/health 刻意不初始化資料庫，首次查詢後會補上",
+  "doctor.driver.fallback": "資料庫: 正在使用降級驅動 {driver} —— 首選驅動被略過: {error}",
+  "doctor.runtime-deps.ok": "執行階段相依: 已安裝並登記在 {dir}",
+  "doctor.runtime-deps.no-runtime": "執行階段相依: {dir} 還不存在 —— 首次啟動時會建立",
+  "doctor.runtime-deps.unregistered": "執行階段相依: {orphaned} 已裝在 {dir}，但沒登記進它的 package.json —— 下次在該目錄 npm install 會被刪掉",
+  "doctor.runtime-deps.missing": "執行階段相依: {dir} 裡未安裝 {missing}(有降級方案涵蓋)",
+  "doctor.runtime-deps.broken-artifact": "執行階段相依: {broken} 已裝在 {dir} 但無法使用 —— 它需要的編譯產物缺失，而 npm 仍認為它裝好了。請重裝(或刪除 {dir}/node_modules 後重啟)。",
+  "doctor.port.ok": "連接埠 {port}: 空閒，或由本安裝占用",
+  "doctor.port.orphan-pidfile": "連接埠 {port} 已空閒，但 {file} 還記著 pid {pidFilePid}",
+  "doctor.port.foreign": "連接埠 {port} 被其他行程占用(pid {owners})",
+  "doctor.tray.ok": "托盤: 目前平台可用({platform})",
+  "doctor.tray.missing": "托盤: 未安裝 systray2 —— 無托盤也能正常提供服務",
+  "doctor.data-dir.ok": "資料目錄: {dir}",
+  "doctor.data-dir.missing": "資料目錄 {dir} 還不存在 —— 首次啟動時建立",
+  "doctor.data-dir.not-writable": "資料目錄 {dir} 不可寫入",
+  "doctor.data-dir.legacy-pending": "舊的 9Router 資料還在 {legacy} —— 下次啟動會遷移進 {dir}"
 }

package/src/cli/i18n/locales/zh-TW/settings.json

@@ -14,7 +14,7 @@
   "menus.settings.tunnelOff": "關閉隧道",
   "menus.settings.rtkToggle": "Token Saver (RTK): {state} → 點選切換",
   "menus.settings.headroomToggle": "Token Saver (Headroom): {state} → 點選切換",
-  "menus.settings.resetPassword": "🔑 重設密碼為預設值",
+  "menus.settings.resetPassword": "🔑 重設密碼",
   "menus.settings.authModeAlready": "🔓 重設驗證模式(目前已是密碼模式)",
   "menus.settings.authModeReset": "🔓 重設驗證模式為密碼(目前: {mode})",
   "menus.settings.resetAuthConfirm": "確定將驗證模式重設為密碼(停用 OIDC)嗎？",
@@ -29,7 +29,7 @@
   "menus.settings.tokenSaverDisabled": "Token Saver 已關閉",
   "menus.settings.headroomEnabledMsg": "Headroom 已開啟",
   "menus.settings.headroomDisabledMsg": "Headroom 已關閉",
-  "menus.settings.resetPwConfirm": "確定將儀表板密碼重設為預設值「{default}」嗎？",
-  "menus.settings.resetPwDone": "密碼已重設,預設值: {default}",
+  "menus.settings.resetPwConfirm": "確定要重設儀表板密碼嗎？將產生一組新的隨機密碼，並在此顯示一次。",
+  "menus.settings.resetPwDone": "密碼已重設。新密碼: {password} —— 只顯示這一次，請立即保存",
   "menus.settings.resetPwFailed": "重設密碼失敗: {error}"
 }

package/src/cli/menus/settings.js

@@ -14,7 +14,13 @@ const COLORS = {
   cyan: "\x1b[36m"
 };
 
-const DEFAULT_PASSWORD = "123456";
+// Fresh random dashboard password for the reset flow. Deliberately not a
+// literal: resetting used to restore the old public default, which is the
+// resurrection path the issue #9 audit called out (a guessable password plus a
+// 0.0.0.0 listener).
+function generatePassword() {
+  return require("crypto").randomBytes(12).toString("base64url");
+}
 
 /**
  * Show settings menu (tunnel + RTK + reset password)
@@ -182,22 +188,34 @@ async function toggleHeadroom(currentlyOn) {
 }
 
 /**
- * Reset dashboard password to default via server API (writes the live SQLite DB).
- * After reset, user can log in with the default password "123456".
+ * Reset the dashboard password: clear the stored hash through the local-only
+ * server route, then set a freshly generated random one and show it exactly
+ * once. The route itself never returns a password, so the CLI mints it here -
+ * the whole point is that nobody, including the operator, knows it in advance.
  */
 async function resetPassword() {
-  const ok = await confirm(t("menus.settings.resetPwConfirm", { default: DEFAULT_PASSWORD }));
+  const ok = await confirm(t("menus.settings.resetPwConfirm"));
   if (!ok) {
     showStatus(t("menus.settings.cancelled"), "info");
     await pause();
     return;
   }
 
-  const result = await api.resetPassword();
-  if (result.success) {
-    showStatus(t("menus.settings.resetPwDone", { default: DEFAULT_PASSWORD }), "success");
+  const cleared = await api.resetPassword();
+  if (!cleared.success) {
+    showStatus(t("menus.settings.resetPwFailed", { error: cleared.error }), "error");
+    await pause();
+    return;
+  }
+
+  // With no hash stored the settings PATCH takes the first-set branch, so no
+  // current password is required here.
+  const generated = generatePassword();
+  const saved = await api.updateSettings({ newPassword: generated });
+  if (saved && saved.error) {
+    showStatus(t("menus.settings.resetPwFailed", { error: saved.error }), "error");
   } else {
-    showStatus(t("menus.settings.resetPwFailed", { error: result.error }), "error");
+    showStatus(t("menus.settings.resetPwDone", { password: generated }), "success");
   }
   await pause();
 }

package/src/cli/staleServer.js

@@ -0,0 +1,216 @@
+"use strict";
+
+/**
+ * Stale-build self-heal.
+ *
+ * `npm i -g @techysy/10router@latest` (or an fpk / desktop update) replaces the
+ * package directory on disk, but a server spawned by the *previous* version is
+ * `detached` and keeps running: it still owns the port and serves an HTML shell
+ * that references chunk hashes the new package no longer ships, so every chunk
+ * request 500s and the dashboard goes blank (ChunkLoadError). The launcher had
+ * no way to notice — it only ever spawned a server, never probed for one that
+ * was already there.
+ *
+ * The probe is deliberately narrow: we only kill when the port *answers*
+ * /api/version AND reports a version different from ours. Everything else (no
+ * answer, same version, an unrelated service on the port) leaves the previous
+ * behaviour untouched, so a recycled PID can never be killed on a guess.
+ *
+ * All process/DNS/fetch side effects are injectable so the logic is unit
+ * testable without spawning or killing anything.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const DEFAULT_PROBE_TIMEOUT_MS = 2000;
+const DEFAULT_RELEASE_TIMEOUT_MS = 5000;
+const RELEASE_POLL_INTERVAL_MS = 150;
+
+function pidFilePath(dataDir) {
+  return path.join(dataDir, "server.pid");
+}
+
+function diskVersionPath(dataDir) {
+  return path.join(dataDir, ".disk-version");
+}
+
+function readPidFile(dataDir) {
+  try {
+    const pid = parseInt(fs.readFileSync(pidFilePath(dataDir), "utf8").trim(), 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+function writePidFile(dataDir, pid) {
+  try {
+    fs.mkdirSync(dataDir, { recursive: true });
+    fs.writeFileSync(pidFilePath(dataDir), String(pid), "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function removePidFile(dataDir) {
+  try {
+    fs.unlinkSync(pidFilePath(dataDir));
+  } catch {
+    /* already gone / never written */
+  }
+}
+
+// The version the package directory currently holds. Written on install and on
+// every launcher start, so a still-running OLD server can report "the disk has
+// moved on" even though it cannot read the new package's code.
+function writeDiskVersion(dataDir, version) {
+  try {
+    fs.mkdirSync(dataDir, { recursive: true });
+    fs.writeFileSync(diskVersionPath(dataDir), String(version), "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readDiskVersion(dataDir) {
+  try {
+    const v = fs.readFileSync(diskVersionPath(dataDir), "utf8").trim();
+    return v || null;
+  } catch {
+    return null;
+  }
+}
+
+// Inequality only — never an ordering. `1.1.1` vs `1.1.2` and `1.1.2` vs
+// `1.1.2-test.3` are both "disk moved on", and `1.1.2-test.3` vs `1.1.2` is not
+// (a test build of the same release must not look stale against itself).
+function isVersionMismatch(runningVersion, diskVersion) {
+  if (!runningVersion || !diskVersion) return false;
+  return String(runningVersion) !== String(diskVersion);
+}
+
+/**
+ * Probe http://127.0.0.1:<port>/api/version.
+ * @returns {Promise<{reachable: boolean, version: string|null}>}
+ *   reachable=false → nothing is listening (normal cold start).
+ *   reachable=true, version=null → something is there but not our server / no JSON.
+ */
+async function probeServerVersion(port, { fetchImpl = globalThis.fetch, timeoutMs = DEFAULT_PROBE_TIMEOUT_MS } = {}) {
+  if (typeof fetchImpl !== "function") return { reachable: false, version: null };
+  const controller = typeof AbortController === "function" ? new AbortController() : null;
+  const timer = controller ? setTimeout(() => controller.abort(), timeoutMs) : null;
+  try {
+    const res = await fetchImpl(`http://127.0.0.1:${port}/api/version`, {
+      signal: controller ? controller.signal : undefined,
+      cache: "no-store",
+    });
+    if (!res || !res.ok) return { reachable: true, version: null };
+    const data = await res.json();
+    return { reachable: true, version: data && data.currentVersion ? String(data.currentVersion) : null };
+  } catch {
+    return { reachable: false, version: null };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/** Kill a pid. POSIX uses SIGKILL on the group leader; win32 taskkills the tree. */
+function killPid(pid, { platform = process.platform, killImpl, taskkillImpl } = {}) {
+  if (!pid) return false;
+  try {
+    if (platform === "win32") {
+      const run =
+        taskkillImpl ||
+        ((p) => require("child_process").spawnSync("taskkill", ["/PID", String(p), "/F", "/T"], {
+          stdio: "ignore",
+          windowsHide: true,
+          timeout: 5000,
+        }));
+      run(pid);
+      return true;
+    }
+    const kill = killImpl || ((p) => process.kill(p, "SIGKILL"));
+    kill(pid);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Poll until nothing answers on the port (or timeout). */
+async function waitForPortRelease(port, options = {}) {
+  const {
+    timeoutMs = DEFAULT_RELEASE_TIMEOUT_MS,
+    intervalMs = RELEASE_POLL_INTERVAL_MS,
+    probe = probeServerVersion,
+  } = options;
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const { reachable } = await probe(port, options.probeOptions || {});
+    if (!reachable) return true;
+    if (Date.now() >= deadline) return false;
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+}
+
+/**
+ * Detect and clear a server left over from a different build.
+ *
+ * @returns {Promise<{action: "none"|"warn"|"killed", reason: string, running?: string, pid?: number|null}>}
+ */
+async function healStaleServer({
+  port,
+  version,
+  dataDir,
+  log: _log = () => {},
+  fetchImpl,
+  probeTimeoutMs,
+  releaseTimeoutMs,
+  platform,
+  killImpl,
+  taskkillImpl,
+} = {}) {
+  const probeOptions = { fetchImpl, timeoutMs: probeTimeoutMs };
+  const probe = await probeServerVersion(port, probeOptions);
+
+  if (!probe.reachable) return { action: "none", reason: "unreachable" };
+  if (!probe.version) return { action: "none", reason: "no-version" };
+  // Same build ⇒ this is our own server on a re-run; leave it alone (the
+  // previous behaviour on an occupied port is preserved).
+  if (!isVersionMismatch(probe.version, version)) return { action: "none", reason: "same-version" };
+
+  const pid = readPidFile(dataDir);
+  if (!pid) {
+    // Proved it is our server (it answered /api/version) but we have no pid to
+    // kill safely — a version that predates the pidfile. Report and carry on.
+    return { action: "warn", reason: "stale-without-pidfile", running: probe.version, pid: null };
+  }
+
+  killPid(pid, { platform, killImpl, taskkillImpl });
+  removePidFile(dataDir);
+  await waitForPortRelease(port, {
+    timeoutMs: releaseTimeoutMs,
+    probeOptions,
+    probe: (p, o) => probeServerVersion(p, o || {}),
+  });
+
+  return { action: "killed", reason: "stale-killed", running: probe.version, pid };
+}
+
+module.exports = {
+  healStaleServer,
+  isVersionMismatch,
+  killPid,
+  pidFilePath,
+  diskVersionPath,
+  probeServerVersion,
+  readDiskVersion,
+  readPidFile,
+  removePidFile,
+  waitForPortRelease,
+  writeDiskVersion,
+  writePidFile,
+};