zen-gitsync 2.16.33 → 2.16.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zen-gitsync",
-  "version": "2.16.33",
+  "version": "2.16.34",
   "description": "Auto commit, scheduled sync, and visual GUI for Git. Run `g` in any repo for one-key commit & push, AI commit messages, scheduled background sync, and a drag-and-drop workflow builder.",
   "main": "index.js",
   "type": "module",

package/src/ui/server/utils/startServerOnAvailablePort.js

@@ -1,134 +1,265 @@
-// Copyright 2026 xz333221
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-//
-import logger from './logger.js'
-
-// 监听地址：默认只绑回环地址。
-// GUI 服务没有任何认证层，绑 0.0.0.0 等于把 /api/exec-stream（命令执行）、
-// /api/add-npm-script（写 package.json scripts）、/api/open-file（用系统
-// 关联程序打开任意文件）等接口裸奔在局域网上，同网段任何主机都可调用。
-// 确有远程访问 / WSL 跨环境需求时，用 ZEN_HOST=0.0.0.0 显式放开。
-const DEFAULT_HOST = '127.0.0.1'
-
-function normalizeHost(raw) {
-  const value = typeof raw === 'string' ? raw.trim() : ''
-  return value || DEFAULT_HOST
-}
-
-export async function startServerOnAvailablePort({
-  httpServer,
-  startPort,
-  chalk,
-  open,
-  noOpen,
-  isGitRepo,
-  savePortToFile,
-  fsSync,
-  maxTries = 100,
-  callbackExecutedRef,
-  host
-}) {
-  const bindHost = normalizeHost(host ?? process.env.ZEN_HOST)
-  let currentPort = startPort;
-  const maxPort = startPort + maxTries;
-  const getCallbackExecuted = () => {
-    if (callbackExecutedRef && typeof callbackExecutedRef === 'object' && 'value' in callbackExecutedRef) {
-      return Boolean(callbackExecutedRef.value);
-    }
-    return false;
-  };
-
-  const setCallbackExecuted = (value) => {
-    if (callbackExecutedRef && typeof callbackExecutedRef === 'object' && 'value' in callbackExecutedRef) {
-      callbackExecutedRef.value = Boolean(value);
-    }
-  };
-
-  while (currentPort < maxPort) {
-    try {
-      if (currentPort > startPort) {
-        await new Promise(resolve => setTimeout(resolve, 800));
-        logger.info(`尝试端口 ${currentPort}...`);
-      }
-
-      await new Promise((resolve, reject) => {
-        const errorHandler = (err) => {
-          httpServer.removeListener('error', errorHandler);
-          reject(err);
-        };
-
-        httpServer.once('error', errorHandler);
-
-        httpServer.listen(currentPort, bindHost, () => {
-          if (getCallbackExecuted()) return;
-          setCallbackExecuted(true);
-
-          httpServer.removeListener('error', errorHandler);
-
-          console.log(chalk.green('======================================'));
-          console.log(chalk.green(`  Zen GitSync 服务器已启动`));
-          console.log(chalk.green(`  访问地址: http://localhost:${currentPort}`));
-          console.log(chalk.green(`  启动时间: ${new Date().toLocaleString()}`));
-          // 非回环地址才提示，默认情况保持安静（避免每次启动都刷警告）
-          if (bindHost !== DEFAULT_HOST) {
-            console.log(chalk.yellow(`  监听地址: ${bindHost}（已放开非本地访问，请确认网络环境可信）`));
-          }
-
-          if (isGitRepo) {
-            console.log(chalk.green(`  当前目录是Git仓库`));
-          } else {
-            console.log(chalk.yellow(`  当前目录不是Git仓库，文件监控未启动`));
-          }
-
-          console.log(chalk.green('======================================'));
-
-          savePortToFile(currentPort);
-
-          // 自拉起重启通知：父进程 spawn 时设置了 ZEN_RESTART_NOTIFY_PATH
-          // 子进程成功 bind 端口后,把端口写到该文件作为"已就绪"信号
-          // （instanceRegistry 在 EPERM 环境下不可用,这是回退通道）
-          const notifyPath = process.env.ZEN_RESTART_NOTIFY_PATH;
-          if (notifyPath && fsSync) {
-            try {
-              fsSync.writeFileSync(notifyPath, String(currentPort), 'utf8');
-            } catch (_) {
-              // 通知写失败不影响主流程
-            }
-          }
-
-          if (!noOpen) {
-            setTimeout(() => {
-              open(`http://localhost:${currentPort}`);
-            }, 0);
-          }
-
-          resolve();
-        });
-      });
-
-      return currentPort;
-    } catch (err) {
-      if (err.code === 'EADDRINUSE') {
-        logger.info(`端口 ${currentPort} 被占用，尝试下一个端口...`);
-        currentPort++;
-      } else {
-        logger.error('启动服务器失败:', err);
-        process.exit(1);
-      }
-    }
-  }
-
-  logger.error(`无法找到可用端口 (尝试范围: ${startPort}-${maxPort - 1})`);
-  process.exit(1);
-}
+// Copyright 2026 xz333221
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+import { execFileSync } from 'node:child_process'
+import logger from './logger.js'
+
+// Windows 会把成块的端口划进"排除范围"（Hyper-V / Docker / WSL 预留，或系统保留的
+// 动态端口块）。落在这些段里的端口，listen() 报的是 EACCES 而不是 EADDRINUSE ——
+// 端口明明没人占，系统就是不让绑。查看方式：
+//   netsh int ip show excludedportrange protocol=tcp
+// 这些段通常连续上百个端口，靠 +1 逐个撞过去极慢（旧实现每个端口还要 sleep 800ms，
+// 撞进一段 100 端口的保留区就是 80 秒）。所以这里懒加载一次并缓存：
+// 只有真撞到 EACCES 时才去查 netsh，正常启动路径零开销。
+let excludedRanges = null
+
+/**
+ * 解析 `netsh int ip show excludedportrange protocol=tcp` 的输出。
+ * 纯函数，单独导出以便测试（表头随系统语言变化，解析规则必须稳）。
+ * @param {string} output netsh 原始输出
+ * @returns {Array<[number, number]>} 保留端口段 [起始, 结束] 列表
+ */
+export function parseExcludedPortRanges(output) {
+  const ranges = []
+  if (typeof output !== 'string' || !output) return ranges
+
+  // 表头随系统语言变化（开始端口/结束端口 vs Start Port/End Port），
+  // 只认数据行：行尾跟着两个十进制数，行尾的 * 表示"管理的端口排除"
+  const re = /(\d{1,5})\s+(\d{1,5})\s*\**\s*$/gm
+  let match
+  while ((match = re.exec(output)) !== null) {
+    const start = Number(match[1])
+    const end = Number(match[2])
+    if (Number.isInteger(start) && Number.isInteger(end) && start > 0 && end >= start && end < 65536) {
+      ranges.push([start, end])
+    }
+  }
+  return ranges
+}
+
+function getExcludedPortRanges() {
+  if (excludedRanges !== null) return excludedRanges
+  excludedRanges = []
+
+  if (process.platform !== 'win32') return excludedRanges
+
+  try {
+    const output = execFileSync(
+      'netsh',
+      ['int', 'ip', 'show', 'excludedportrange', 'protocol=tcp'],
+      { encoding: 'utf8', timeout: 3000, windowsHide: true }
+    )
+    excludedRanges = parseExcludedPortRanges(output)
+    if (excludedRanges.length) {
+      logger.info(`检测到 ${excludedRanges.length} 个系统保留端口段，启动时将自动跳过`)
+    }
+  } catch (err) {
+    // 查不到（非 Windows / netsh 不可用 / 超时）就退化成逐个 +1 试，不影响主流程
+    logger.info(`查询系统保留端口段失败，退化为逐端口探测: ${err?.message || err}`)
+  }
+
+  return excludedRanges
+}
+
+/**
+ * 端口是否落在系统保留段内，是则返回该段，否则返回 null。
+ * 注意：内部会触发 netsh 查询，只在确认需要时调用。
+ */
+function findExcludedRange(port) {
+  return getExcludedPortRanges().find(([start, end]) => port >= start && port <= end) || null
+}
+
+// 监听地址：默认只绑回环地址。
+// GUI 服务没有任何认证层，绑 0.0.0.0 等于把 /api/exec-stream（命令执行）、
+// /api/add-npm-script（写 package.json scripts）、/api/open-file（用系统
+// 关联程序打开任意文件）等接口裸奔在局域网上，同网段任何主机都可调用。
+// 确有远程访问 / WSL 跨环境需求时，用 ZEN_HOST=0.0.0.0 显式放开。
+const DEFAULT_HOST = '127.0.0.1'
+
+// 浏览器访问地址不要使用 localhost：Windows 上它可能优先解析到 ::1，
+// 而另一个程序恰好占用 IPv6 同端口时，页面会被打开到错误的服务。
+// 默认服务明确绑定 IPv4 回环，因此浏览器也必须使用同一个地址。
+function getBrowserHost(bindHost) {
+  return bindHost === DEFAULT_HOST ? DEFAULT_HOST : 'localhost'
+}
+
+function normalizeHost(raw) {
+  const value = typeof raw === 'string' ? raw.trim() : ''
+  return value || DEFAULT_HOST
+}
+
+export async function startServerOnAvailablePort({
+  httpServer,
+  startPort,
+  chalk,
+  open,
+  noOpen,
+  isGitRepo,
+  savePortToFile,
+  fsSync,
+  maxTries = 100,
+  callbackExecutedRef,
+  host
+}) {
+  const bindHost = normalizeHost(host ?? process.env.ZEN_HOST)
+  let currentPort = startPort;
+  const maxPort = startPort + maxTries;
+  const getCallbackExecuted = () => {
+    if (callbackExecutedRef && typeof callbackExecutedRef === 'object' && 'value' in callbackExecutedRef) {
+      return Boolean(callbackExecutedRef.value);
+    }
+    return false;
+  };
+
+  const setCallbackExecuted = (value) => {
+    if (callbackExecutedRef && typeof callbackExecutedRef === 'object' && 'value' in callbackExecutedRef) {
+      callbackExecutedRef.value = Boolean(value);
+    }
+  };
+
+  let lastErrorCode = null;
+
+  while (currentPort < maxPort) {
+    try {
+      if (currentPort > startPort) {
+        // 系统保留端口（EACCES）不会随时间释放，没必要等；
+        // 只有"被占用"（EADDRINUSE）才需要给端口一点时间释放
+        if (lastErrorCode !== 'EACCES') {
+          await new Promise(resolve => setTimeout(resolve, 800));
+        }
+        logger.info(`尝试端口 ${currentPort}...`);
+      }
+
+      // 本次尝试要绑的端口。回调里必须用它校验，不能用外层的 currentPort：
+      // 闭包捕获的是同一个变量，重试时它的值早就变了
+      const attemptPort = currentPort;
+
+      await new Promise((resolve, reject) => {
+        // 每次尝试独立的 settled。失败之后即便平台补发了 listening 回调，也不再响应
+        let settled = false;
+
+        const cleanup = () => {
+          httpServer.removeListener('error', errorHandler);
+          httpServer.removeListener('listening', listeningHandler);
+        };
+
+        const errorHandler = (err) => {
+          if (settled) return;
+          settled = true;
+          cleanup();
+          reject(err);
+        };
+
+        const listeningHandler = () => {
+          // 过期回调防护。server.listen(port, host, cb) 的 cb 会被注册成
+          // once('listening', cb)，而 listen 失败时只 emit 'error'，这个 cb
+          // 摘不掉。等后面某次 listen 成功 emit 'listening'，历史残留的 cb
+          // 会和新 cb 一起被依次触发 —— 残留 cb 抢先执行会把防重入标志置位，
+          // 本次真正成功的回调就会直接 return，await 永久挂起，服务起不来。
+          // 这里用"本次是否已 settle"+"实际监听端口是否为本次目标"双重拦截。
+          if (settled) return;
+          const addr = httpServer.address();
+          if (addr && addr.port !== attemptPort) return;
+
+          settled = true;
+          cleanup();
+
+          if (getCallbackExecuted()) return;
+          setCallbackExecuted(true);
+
+          console.log(chalk.green('======================================'));
+          console.log(chalk.green(`  Zen GitSync 服务器已启动`));
+          const browserHost = getBrowserHost(bindHost);
+          console.log(chalk.green(`  访问地址: http://${browserHost}:${attemptPort}`));
+          console.log(chalk.green(`  启动时间: ${new Date().toLocaleString()}`));
+          // 非回环地址才提示，默认情况保持安静（避免每次启动都刷警告）
+          if (bindHost !== DEFAULT_HOST) {
+            console.log(chalk.yellow(`  监听地址: ${bindHost}（已放开非本地访问，请确认网络环境可信）`));
+          }
+
+          if (isGitRepo) {
+            console.log(chalk.green(`  当前目录是Git仓库`));
+          } else {
+            console.log(chalk.yellow(`  当前目录不是Git仓库，文件监控未启动`));
+          }
+
+          console.log(chalk.green('======================================'));
+
+          savePortToFile(attemptPort);
+
+          // 自拉起重启通知：父进程 spawn 时设置了 ZEN_RESTART_NOTIFY_PATH
+          // 子进程成功 bind 端口后,把端口写到该文件作为"已就绪"信号
+          // （instanceRegistry 在 EPERM 环境下不可用,这是回退通道）
+          const notifyPath = process.env.ZEN_RESTART_NOTIFY_PATH;
+          if (notifyPath && fsSync) {
+            try {
+              fsSync.writeFileSync(notifyPath, String(attemptPort), 'utf8');
+            } catch (_) {
+              // 通知写失败不影响主流程
+            }
+          }
+
+          if (!noOpen) {
+            setTimeout(() => {
+              open(`http://${browserHost}:${attemptPort}`);
+            }, 0);
+          }
+
+          resolve();
+        };
+
+        // 不把成功回调挂在 listen() 的第三个参数上：那样它会被注册成
+        // once('listening', cb)，而 listen 失败时只 emit 'error'，这个 cb
+        // 摘不掉。显式注册后，失败路径的 cleanup() 能把它清理干净。
+        httpServer.once('error', errorHandler);
+        httpServer.once('listening', listeningHandler);
+        httpServer.listen(attemptPort, bindHost);
+      });
+
+      return currentPort;
+    } catch (err) {
+      lastErrorCode = err?.code || null;
+
+      if (err.code === 'EADDRINUSE') {
+        logger.info(`端口 ${currentPort} 被占用，尝试下一个端口...`);
+        currentPort++;
+      } else if (err.code === 'EACCES') {
+        // 端口不让绑：Windows 上绝大多数情况落在系统保留段里。
+        // 命中整段就直接跳到段尾之后，否则逐个撞过去会非常慢。
+        const range = findExcludedRange(currentPort);
+        if (range) {
+          logger.info(`端口 ${currentPort} 位于系统保留段 ${range[0]}-${range[1]}，跳到 ${range[1] + 1}...`);
+          currentPort = range[1] + 1;
+        } else {
+          logger.info(`端口 ${currentPort} 无监听权限（可能被系统保留），尝试下一个端口...`);
+          currentPort++;
+        }
+      } else {
+        logger.error('启动服务器失败:', err);
+        process.exit(1);
+      }
+    }
+  }
+
+  logger.error(`无法找到可用端口 (尝试范围: ${startPort}-${maxPort - 1})`);
+  if (process.platform === 'win32' && getExcludedPortRanges().length) {
+    logger.error(
+      `已跳过的系统保留端口段: ${getExcludedPortRanges()
+        .map(([s, e]) => `${s}-${e}`)
+        .join(', ')}`
+    );
+    logger.error('可用 netsh int ip show excludedportrange protocol=tcp 复核；也可用 PORT 环境变量指定其它端口');
+  }
+  process.exit(1);
+}

package/src/ui/server/utils/startServerOnAvailablePort.test.js

@@ -14,36 +14,58 @@
 //
 // startServerOnAvailablePort 单元测试。
 //
-// 这里只锁一件事：监听地址。
-// GUI 服务没有认证层，listen() 不传 host 就会绑到 0.0.0.0，等于把
-// /api/exec-stream（命令执行）、/api/add-npm-script（写 package.json）
-// 等接口裸奔在局域网上。默认必须是回环地址，只有显式设置 ZEN_HOST
-// 或显式传 host 参数才放开。这组测试就是防止有人图省事改回 0.0.0.0。
+// 这里锁两件事：
+//
+// 1. 监听地址。GUI 服务没有认证层，listen() 不传 host 就会绑到 0.0.0.0，等于把
+//    /api/exec-stream（命令执行）、/api/add-npm-script（写 package.json）等接口
+//    裸奔在局域网上。默认必须是回环地址，只有显式设置 ZEN_HOST 或显式传 host
+//    参数才放开。这组测试防止有人图省事改回 0.0.0.0。
+//
+// 2. 端口重试不能把自己挂死。server.listen(port, host, cb) 的 cb 实际被注册成
+//    once('listening', cb)，而 listen 失败时只 emit 'error'，这个 cb 摘不掉。
+//    等后面某次 listen 成功 emit 'listening'，历史残留的 cb 会和新 cb 一起被
+//    依次触发。残留 cb 抢先跑完会把防重入标志置位，本次真正成功的回调就直接
+//    return，await 永久挂起 —— 服务表现为"卡住起不来"。
+//    Windows 上 EACCES（系统保留端口）顺延时必现。下面第 2 组测试专门盯这个。
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
-import { startServerOnAvailablePort } from './startServerOnAvailablePort.js'
+import {
+  startServerOnAvailablePort,
+  parseExcludedPortRanges
+} from './startServerOnAvailablePort.js'
 
 // 极简 chalk：只需要 .green / .yellow / .cyan 能把原串返回
 const chalk = new Proxy({}, { get: () => (s) => String(s) })
 
-/** 最小 httpServer mock，只记录 listen 的入参 */
-function createFakeHttpServer() {
+/**
+ * 模拟真实 http.Server 的 listen 语义。
+ *
+ * 重点复刻上面提到的那个坑：listen 失败时只 emit 'error'，已注册的 listening
+ * 回调一个都不摘；等某次 listen 成功，所有历史残留回调会和新回调一起被触发。
+ *
+ * @param {object} [opts]
+ * @param {number[]} [opts.failPorts] 这些端口上让 listen 失败
+ * @param {string} [opts.errorCode] 失败时注入的 errno
+ */
+function createFakeHttpServer({ failPorts = [], errorCode = 'EACCES' } = {}) {
   const calls = []
-  const handlers = new Map()
+  const listening = []
+  const errors = []
   const server = {
     calls,
     once(event, fn) {
-      if (!handlers.has(event)) handlers.set(event, [])
-      handlers.get(event).push(fn)
+      if (event === 'listening') listening.push(fn)
+      else if (event === 'error') errors.push(fn)
     },
-    on(event, fn) { server.once(event, fn) },
     removeListener(event, fn) {
-      const list = handlers.get(event) || []
+      const list = event === 'listening' ? listening : errors
       const i = list.indexOf(fn)
       if (i >= 0) list.splice(i, 1)
     },
+    address() {
+      return server._addr || null
+    },
     listen(...args) {
-      // 同时兼容 listen(port, cb) 与 listen(port, host, cb) 两种形态
       const port = args[0]
       let host
       let cb
@@ -54,48 +76,72 @@ function createFakeHttpServer() {
         cb = args[2]
       }
       calls.push({ port, host })
-      if (cb) setImmediate(cb)
+      // Node 的真实语义：回调被注册成 once('listening', cb)
+      if (cb) listening.push(cb)
+
+      setImmediate(() => {
+        if (failPorts.includes(port)) {
+          // 失败：只 emit 'error'，listening 回调一个都不摘（关键）
+          const err = new Error(`${errorCode} ${port}`)
+          err.code = errorCode
+          errors.splice(0).forEach((fn) => fn(err))
+          return
+        }
+        server._addr = { address: host || '127.0.0.1', port }
+        // 成功：触发全部 listening 回调，包含历史失败残留的那些
+        listening.splice(0).forEach((fn) => fn())
+      })
     }
   }
   return server
 }
 
 /**
- * 跑一次启动流程，返回 listen 的调用记录。
- * @param {object} opts
- * @param {string|null} [opts.zenHost] 本次运行时 ZEN_HOST 的取值；null 表示删除该变量
- * @param {object} [opts.rest] 直接透传给 startServerOnAvailablePort 的参数（如 host）
+ * 跑一次启动流程。
+ *
+ * 端口默认取 47000 且 maxTries 给足：万一真撞进系统保留段触发"整段跳跃"，
+ * 也有足够回旋空间试到成功，不至于让测试因为耗尽尝试次数而退出。
+ *
+ * @param {object} [opts]
+ * @param {number[]} [opts.failPorts] 让哪些端口的 listen 失败
+ * @param {string} [opts.errorCode] 注入的 errno
+ * @param {string|null} [opts.zenHost] ZEN_HOST 取值；null 表示删除该变量
+ * @param {object} [opts.rest] 直接透传给 startServerOnAvailablePort 的参数
  */
-async function listenOnce(opts = {}) {
-  const httpServer = createFakeHttpServer()
+async function startOnce({
+  failPorts = [],
+  errorCode = 'EACCES',
+  zenHost = null,
+  startPort = 47000,
+  maxTries = 20,
+  rest = {}
+} = {}) {
+  const httpServer = createFakeHttpServer({ failPorts, errorCode })
   const envBak = process.env.ZEN_HOST
   const notifyBak = process.env.ZEN_RESTART_NOTIFY_PATH
-  // 清掉重启通知路径，避免测试真的往 tmpdir 写文件
+  // 清掉重启通知路径，避免测试真的往环境里写文件
   delete process.env.ZEN_RESTART_NOTIFY_PATH
-
-  if ('zenHost' in opts) {
-    if (opts.zenHost === null) delete process.env.ZEN_HOST
-    else process.env.ZEN_HOST = opts.zenHost
-  }
+  if (zenHost === null) delete process.env.ZEN_HOST
+  else process.env.ZEN_HOST = zenHost
 
   // 启动成功时会 console.log 一大段横幅，静音掉以保持测试输出干净
   const logBak = console.log
   console.log = () => {}
 
   try {
-    await startServerOnAvailablePort({
+    const port = await startServerOnAvailablePort({
       httpServer,
-      startPort: 4000,
+      startPort,
       chalk,
       open: async () => {},
       noOpen: true,
       isGitRepo: true,
       savePortToFile: () => {},
-      maxTries: 1,
+      maxTries,
       callbackExecutedRef: { value: false },
-      ...(opts.rest || {})
+      ...rest
     })
-    return httpServer.calls
+    return { port, calls: httpServer.calls }
   } finally {
     console.log = logBak
     if (envBak === undefined) delete process.env.ZEN_HOST
@@ -105,77 +151,131 @@ async function listenOnce(opts = {}) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// 1. 监听地址：默认是回环，不能退化成 0.0.0.0
+// ---------------------------------------------------------------------------
+
 test('默认监听 127.0.0.1，不会绑到 0.0.0.0', async () => {
-  const calls = await listenOnce({ zenHost: null })
+  const { calls } = await startOnce()
   assert.equal(calls.length, 1)
-  assert.equal(calls[0].port, 4000)
+  assert.equal(calls[0].port, 47000)
   assert.equal(calls[0].host, '127.0.0.1')
 })
 
 test('ZEN_HOST=0.0.0.0 时放开到所有网卡', async () => {
-  const calls = await listenOnce({ zenHost: '0.0.0.0' })
+  const { calls } = await startOnce({ zenHost: '0.0.0.0' })
   assert.equal(calls[0].host, '0.0.0.0')
 })
 
 test('显式传 host 参数优先于环境变量', async () => {
-  const calls = await listenOnce({ zenHost: '0.0.0.0', rest: { host: '127.0.0.1' } })
+  const { calls } = await startOnce({ zenHost: '0.0.0.0', rest: { host: '127.0.0.1' } })
   assert.equal(calls[0].host, '127.0.0.1')
 })
 
 test('ZEN_HOST 为空串或纯空白时回落默认回环地址', async () => {
-  assert.equal((await listenOnce({ zenHost: '' }))[0].host, '127.0.0.1')
-  assert.equal((await listenOnce({ zenHost: '   ' }))[0].host, '127.0.0.1')
+  assert.equal((await startOnce({ zenHost: '' })).calls[0].host, '127.0.0.1')
+  assert.equal((await startOnce({ zenHost: '   ' })).calls[0].host, '127.0.0.1')
 })
 
-test('端口占用时顺延到下一个端口，且每次都带上 host', async () => {
-  const httpServer = createFakeHttpServer()
-  // 第一次 listen 触发 EADDRINUSE，第二次成功
-  let first = true
-  httpServer.listen = (...args) => {
-    httpServer.calls.push({ port: args[0], host: args[1] })
-    const cb = typeof args[1] === 'function' ? args[1] : args[2]
-    const handlers = httpServer._errorHandlers || []
-    if (first) {
-      first = false
-      setImmediate(() => {
-        const err = new Error('busy')
-        err.code = 'EADDRINUSE'
-        handlers.forEach((fn) => fn(err))
-      })
-    } else if (cb) {
-      setImmediate(cb)
-    }
-  }
-  const origOnce = httpServer.once.bind(httpServer)
-  httpServer.once = (event, fn) => {
-    if (event === 'error') {
-      httpServer._errorHandlers = httpServer._errorHandlers || []
-      httpServer._errorHandlers.push(fn)
-    }
-    return origOnce(event, fn)
-  }
+// ---------------------------------------------------------------------------
+// 2. 端口重试：不能挂死，且每次尝试都必须带 host
+// ---------------------------------------------------------------------------
 
-  const logBak = console.log
-  console.log = () => {}
-  try {
-    await startServerOnAvailablePort({
-      httpServer,
-      startPort: 4000,
-      chalk,
-      open: async () => {},
-      noOpen: true,
-      isGitRepo: true,
-      savePortToFile: () => {},
-      maxTries: 5,
-      callbackExecutedRef: { value: false }
-    })
-  } finally {
-    console.log = logBak
-  }
+test('端口被占用(EADDRINUSE)时顺延到下一个端口，且每次都带上 host', async () => {
+  const { port, calls } = await startOnce({
+    failPorts: [47000],
+    errorCode: 'EADDRINUSE'
+  })
 
-  assert.ok(httpServer.calls.length >= 2, '应该有端口重试')
+  assert.equal(port, 47001)
+  assert.ok(calls.length >= 2, '应该有端口重试')
   // 每一次尝试都必须带 host，否则重试那一次又会退化成 0.0.0.0
-  for (const call of httpServer.calls) {
+  for (const call of calls) {
+    assert.equal(call.host, '127.0.0.1')
+  }
+})
+
+test('端口无监听权限(EACCES)时顺延重试，不会直接退出进程', async () => {
+  // 系统保留端口（Windows 排除段）上报的就是 EACCES：端口没人占，就是不让绑。
+  // 修复前这条路径走 else 分支 process.exit(1)，服务直接起不来。
+  const { port, calls } = await startOnce({
+    failPorts: [47000, 47001],
+    errorCode: 'EACCES'
+  })
+
+  assert.equal(port, 47002)
+  assert.ok(calls.length >= 3, `应重试直到成功，实际只尝试了 ${calls.length} 次`)
+
+  for (const call of calls) {
     assert.equal(call.host, '127.0.0.1')
   }
+
+  // 端口必须严格递增。"整段跳过保留区"若写错（比如跳回段首）会死循环，这里兜住
+  const ports = calls.map((c) => c.port)
+  for (let i = 1; i < ports.length; i++) {
+    assert.ok(ports[i] > ports[i - 1], `端口应严格递增，实际: ${ports.join(' -> ')}`)
+  }
+})
+
+test('前一次失败留下的 listening 残留回调，不会让本次成功卡死', async (t) => {
+  // 这是最容易复现、也最致命的一个坑：
+  // listen 失败只 emit 'error'，之前注册的 listening 回调摘不掉。等下一个端口
+  // listen 成功 emit 'listening'，历史残留回调会先跑一遍 —— 它若抢先把防重入
+  // 标志置位，本次真正成功的回调就会直接 return，await 永久挂起。
+  //
+  // fake server 已复刻该语义（失败时不清 listening 队列）。若防护被改坏，
+  // 这个用例会挂起，靠 timeout 判失败而不是默默卡死整个测试进程。
+  t.diagnostic('防护失效时此用例会挂起，timeout 会让它失败')
+  const { port } = await startOnce({ failPorts: [47000], errorCode: 'EACCES' })
+  assert.equal(port, 47001)
+}, { timeout: 5000 })
+
+// ---------------------------------------------------------------------------
+// 3. Windows 保留端口段解析
+// ---------------------------------------------------------------------------
+
+test('解析 netsh 排除端口输出：中英文表头都要认', () => {
+  const zh = [
+    '',
+    '协议 tcp 端口排除范围',
+    '',
+    '开始端口    结束端口      ',
+    '----------    --------      ',
+    '      2869        2869      ',
+    '      4311        4410      ',
+    '     5544        5545     *',
+    '',
+    '* - 管理的端口排除。',
+    ''
+  ].join('\n')
+
+  assert.deepEqual(parseExcludedPortRanges(zh), [
+    [2869, 2869],
+    [4311, 4410],
+    [5544, 5545]
+  ])
+
+  const en = [
+    'Protocol tcp Port Exclusion Ranges',
+    '',
+    'Start Port    End Port      ',
+    '----------    --------      ',
+    '      2869        2869      ',
+    '      4311        4410      ',
+    ''
+  ].join('\n')
+
+  assert.deepEqual(parseExcludedPortRanges(en), [
+    [2869, 2869],
+    [4311, 4410]
+  ])
+})
+
+test('解析 netsh 输出：异常输入返回空数组而不是抛错', () => {
+  // 表头、分隔线、说明文字都不含数字对，不该被误当成端口段
+  assert.deepEqual(parseExcludedPortRanges(''), [])
+  assert.deepEqual(parseExcludedPortRanges(null), [])
+  assert.deepEqual(parseExcludedPortRanges(undefined), [])
+  assert.deepEqual(parseExcludedPortRanges('garbage output\nno ranges here'), [])
+  assert.deepEqual(parseExcludedPortRanges('开始端口    结束端口'), [])
 })