dsh-connect-workbuddy 4.6.0 → 4.6.2

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 4.6.2 (2026-10-16)
+
+> 版本号是 **patch**：修的是一个启动期缺陷，没有接口、配置或界面变更。
+
+### Fixes
+
+- **shim 启动时会避开「HTTP 客户端自己拒绝」的端口**
+  - **症状**：某个区域（`cn` 或 `global`）的模型请求**全部失败**，报错只有一句 `Connection error.`，而 shim 本身完全健康 —— `curl`、`node:http`、裸 TCP 连上去都是 200。重启后可能好、可能照样坏。
+  - **根因**：`server.listen(0)` 让内核挑端口，而 Fetch 规范定义了一张**必须拒绝**的端口清单（`fetch.spec.whatwg.org#block-bad-port`，undici 实现为 `badPorts`，当前最大到 `10080`）。`fetch` 在**开 socket 之前**就拒绝这些端口，所以请求根本没上过网线。pi-ai 驱动官方 `openai` SDK，而它的 `getDefaultFetch()` 返回 `globalThis.fetch` —— **生产路径走的就是这一层**，不是只有测试才会中招（已实测 `openai@6.40.0`：坏端口报 `Connection error. → fetch failed → bad port`，正常端口正常返回）。端口只在启动时 bind 一次，不会自己重掷，所以一旦抽中就是**该区域持续失败直到插件重新加载**。
+  - **只在特定机器上发生**：`listen(0)` 的抽取范围是系统的动态端口范围，三平台默认值（Windows/macOS `49152-65535`、Linux `32768-60999`）**整体高于**清单最大值 `10080`，交集为空 —— 默认机器**结构上不可能中招**。只有当范围被下调到触及 `10080` 以下才会发生，例如本机的遗留注册表值 `MaxUserPort = 15000`（实测 `netsh` 报 `1024-15000`，范围内有 **19 个**被禁端口，约 `0.136%`／次绑定；每次插件加载建 2 个 shim，约 `0.27%`／次加载）。这一条**已按三方独立实测核对**：`0.105%`（60000 次采样）、`0.115%`（20000 次采样）、理论值 `0.136%`。
+  - **为什么难自查**：错误链上真正的 `cause`（`bad port`）被 SDK 归一化时丢弃，界面和日志都只剩 `Connection error.`，读不出是端口问题；用户唯一能做的「换个账号」恰好**救不了**（与账号无关）。顺带确认：这个拒绝与代理无关（把 `HTTP_PROXY` 指向死端口、清空 `NO_PROXY`，回环好端口仍返回 200 —— 说明回环流量根本不经过代理），也不是 `ECONNREFUSED`（后者带 `code`，而它是 `cause.message === 'bad port'`、无 `code`）。
+  - **改了什么**：新增 `clientRefusesPort()`（绑定后用自己的 `fetch` 打 `/healthz` 探测：**返回任何 HTTP 码都算客户端接受**，含 401；只有抛异常才算被拒）与 `listenOnClientReachablePort()`（有界重掷，上限 `PORT_ROLL_LIMIT = 5`）。用客户端自身探测而**不是**比对一张抄来的端口表：清单是规范的一部分，抄本会随规范漂移，而这里要满足的规则**本身就是客户端的**。绑定方式仍是 `listen(0)` + 仅回环（随机性不变），端口在 `ready` 之前定格，因此 `baseUrl()` 的消费方一行未改。
+  - **顺带修掉一个自己引入的缺陷**：`close()` 落在 `listen()` 未完成期间时，Node **既不触发 `listening` 也不触发 `error`，只触发 `close`**（实测确认）——最初的 `listenOnce` 只监听前两者，会让 `ready` 永久 pending、卡住插件卸载。已补 `close` 监听。
+  - **守卫**：`tests/shim.spec.ts` 新增 6 例（真实客户端识别被禁端口、健康端口不误判、拒绝与真实传输错误可区分、重掷后确实服务、上界生效不空转、首抽即通过时不重掷），外加 2 例生命周期守卫（启动期被处置不得挂起、并发 `close()` 安全）。**变异验证（4 个变异全部转红，且各自只打中应打中的用例）**：① 探测恒真（永不重绑，等价修复前）→ 红 3 例；② 探测恒假 → 红 1 例；③ 移除 `close` 监听 → 红 1 例（30s 超时，正是挂起）；④ 上界失效 → 红 1 例。
+  - **端到端验证（跑在真实 `createWorkBuddyShim` 上，非 mock）**：启动 **500 个**真实 shim，落在被禁端口的 **0 个**、客户端不可达的 **0 个**（修复前期望约 0.68 个）；劫持 `fetch` 让首次探测抛出与真实 `bad port` **同形状**的错误后，真实对象从 `4512` 重掷到 `4513` 并在新端口正常服务。全量 `79` 文件／`1308` 用例通过，与改动前的 `1300` 相比净增 `8` 例。
+
+## 4.6.1 (2026-10-16)
+
+> 版本号是 **patch**：只加了一行提示文案，没有行为、接口或配置变更。
+
+### Fixes
+
+- **模型区补一句「免费模型有时间段内定额 Token 上限，并非无限制使用。」（加粗）**
+  - **为什么单独一句、而不是接在上面那句说明后面**：目录里有一批 `creditMultiplier: 0` 的模型，卡片把它们显示为免费；而上游仍会在**某一时段内的 token 定额**用完时用 `6004` / `14003` 拒掉 —— **那个定额不是账单余额，充钱也解决不了**。把「免费＝无限」当成事实的人，会把 `6004` 读成「插件坏了」进而去找一个没问题的账号（#56 的报告者就为这个误读花掉过时间），或者去充值（`#63` 报的正是这个读法）。上面那句是描述**事实**、灰度的说明文字，这一句纠正的是**预期**，所以它独立成行并加粗。
+  - **颜色刻意不变**：仍是三级灰，不换成主色也不换成错误色 —— 它陈述的是正常产品行为，不是故障；换成红色会读成报错横幅，而真正该被当成错误的信息在别处。
+  - **中英 1:1**：`row.tabFreeQuotaWarn`（`免费模型有时间段内定额 Token 上限，并非无限制使用。` / `Free models have a per-window token quota — they are not unlimited.`）。
+  - **守卫**：`tests/pool-card-render.spec.tsx` 新增 2 例 —— ① 提示会渲染、且带的是**加粗类**而不是又一条灰度提示；② 字重必须写在样式表里（断言 `.dsm-workbuddy-free-quota-warn{font-weight:600}`），防止有人改成内联 `style={{fontWeight:600}}` 之后这条规则在 CSS 里查不到。**变异验证**：① 删掉那段提示 → 红；② 从 CSS 删掉加粗规则 → 红。
+  - **顺带踩到并记录一个老坑**：这行的样式注释里写了反引号（引用 locale 键），而 `styles.ts` 是**模板字面量** —— 反引号会直接截断字符串，表现为 `tsc` 报 `',' expected`。同一个错在本次发布周期里犯了两次，已改为不带反引号的写法。
+
 ## 4.6.0 (2026-10-15)
 
 > 版本号是 **minor** 而不是 patch：这一版新增了**用户可见的界面结论与控件**（池级「模型整体繁忙」判断、积分弹窗的打开期自动刷新、额度提示的呈现位置调整），按语义化版本属于特性。主线是**三处「界面上说了错话」的修正** —— 窗口左上角那个本来没有的方框、池卡片把模型问题说成账号问题、以及同一个账号在两个界面上状态不一致。三处都不会让测试或 CI 变红，只有人看界面才会发现，这也是它们能一路发出去的原因。

package/lib/bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { C as defaultDesktopAuthDirs, F as WorkBuddyUpstreamClient, K as WORKBUDDY_APP_EXECUTABLE_ENV, O as legacyWorkbuddyOwnAuthPath, Q as findWorkbuddyAppExecutableWithSource, S as defaultDesktopAuthCandidates, a as readHostHeartbeat, c as WORKBUDDY_CONNECT_VERSION, d as FALLBACK_WORKBUDDY_MODELS_GLOBAL, j as workbuddyOwnAuthPath, l as piAiRuntimeInfo, o as workbuddyHostHeartbeatPath, ot as hostPeersInfo, r as isHeartbeatProcessAlive, u as FALLBACK_WORKBUDDY_MODELS, v as WORKBUDDY_AUTH_FILE_ENV, y as WorkBuddyCredentialStore } from "./host-heartbeat-BxBvvAZq.js";
+import { C as defaultDesktopAuthDirs, F as WorkBuddyUpstreamClient, K as WORKBUDDY_APP_EXECUTABLE_ENV, O as legacyWorkbuddyOwnAuthPath, Q as findWorkbuddyAppExecutableWithSource, S as defaultDesktopAuthCandidates, a as readHostHeartbeat, c as WORKBUDDY_CONNECT_VERSION, d as FALLBACK_WORKBUDDY_MODELS_GLOBAL, j as workbuddyOwnAuthPath, l as piAiRuntimeInfo, o as workbuddyHostHeartbeatPath, ot as hostPeersInfo, r as isHeartbeatProcessAlive, u as FALLBACK_WORKBUDDY_MODELS, v as WORKBUDDY_AUTH_FILE_ENV, y as WorkBuddyCredentialStore } from "./host-heartbeat-De95rlXS.js";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 //#region src/bin.ts

package/lib/client.js

@@ -3129,6 +3129,12 @@ window.__ModuleLoader__.load({
    scrolling to the end of a long model list. */
 .dsm-workbuddy-models-dirty{margin-left:8px;padding:1px 6px;border-radius:6px;background:var(--dsw-alias-state-warn-primary,#f59e0b);color:#1b1d22;font-size:11px;font-weight:600;line-height:16px;vertical-align:1px;white-space:nowrap}
 .dsm-workbuddy-models-summary{margin:2px 0 0;color:var(--dsw-alias-label-tertiary,#999);font-size:12px;line-height:18px}
+/* The free-model quota warning (see the tabFreeQuotaWarn locale key). Bold on
+   purpose, and it keeps the summary's own grey rather than the primary label
+   colour: it has to stand out from the three lines around it WITHOUT reading as
+   an error banner, because the fact it states is normal product behaviour
+   rather than a failure. Weight is the only signal it needs. */
+.dsm-workbuddy-free-quota-warn{font-weight:600}
 .dsm-workbuddy-model-list{display:flex;flex-direction:column;border:1px solid var(--dsw-alias-border-l2,#36373b);border-radius:10px;overflow:hidden}
 .dsm-workbuddy-model{display:grid;grid-template-columns:minmax(0,1fr);gap:7px;padding:10px 12px;background:var(--dsw-alias-bg-layer-2,#232529);transition:opacity .16s}
 .dsm-workbuddy-model-disabled{opacity:.55}
@@ -4750,6 +4756,10 @@ window.__ModuleLoader__.load({
 								className: "dsm-workbuddy-models-summary",
 								children: t("row.tabHint")
 							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+								className: "dsm-workbuddy-models-summary dsm-workbuddy-free-quota-warn",
+								children: t("row.tabFreeQuotaWarn")
+							}),
 							!activeRegionOn ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
 								className: "dsm-workbuddy-tab-off-notice",
 								children: t("row.tabOffNotice")
@@ -5930,6 +5940,7 @@ window.__ModuleLoader__.load({
 			"row.tabCn": "Domestic",
 			"row.tabGlobal": "Global",
 			"row.tabHint": "Each tab is a separate provider (workbuddy / workbuddy-global) with its own account, credits, and models. Both sides are live at once: different sessions can pick from either side, and changes on one tab never touch the other.",
+			"row.tabFreeQuotaWarn": "Free models have a per-window token quota — they are not unlimited.",
 			"row.tabSwitchHint": "Uncheck to switch this provider off. Its models disappear from the DSH model picker; your account, credits, and model settings are kept and return when you check it again.",
 			"row.tabSwitchAria": "Offer the {region} provider to DSH",
 			"row.tabOffNotice": "This provider is switched off: none of its models are offered to DSH. Your account, credits, and model settings are kept — check the box above the tab to bring it back.",
@@ -6214,6 +6225,7 @@ window.__ModuleLoader__.load({
 			"row.tabCn": "国内版",
 			"row.tabGlobal": "国际版",
 			"row.tabHint": "每个 tab 是一个独立供应商（workbuddy / workbuddy-global），各有自己的账号、积分与模型。两边同时生效：不同会话可各选一边，一侧的改动不影响另一侧。",
+			"row.tabFreeQuotaWarn": "免费模型有时间段内定额 Token 上限，并非无限制使用。",
 			"row.tabSwitchHint": "取消勾选即关闭该供应商：它的模型不再出现在 DSH 模型选择器里；账号、积分与模型设置都会保留，重新勾选即恢复。",
 			"row.tabSwitchAria": "是否向 DSH 提供{region}供应商",
 			"row.tabOffNotice": "该供应商已关闭：它的模型不会提供给 DSH。账号、积分与模型设置均已保留——勾选上方复选框即可恢复。",

package/lib/{host-heartbeat-BxBvvAZq.js → host-heartbeat-De95rlXS.js}

@@ -3825,7 +3825,7 @@ function generationOf(version) {
 //#endregion
 //#region src/version.ts
 /** The npm package version this build was produced from. */
-const WORKBUDDY_CONNECT_VERSION = "4.6.0";
+const WORKBUDDY_CONNECT_VERSION = "4.6.2";
 //#endregion
 //#region src/host-heartbeat.ts
 /**

package/lib/index.js

@@ -1,4 +1,4 @@
-import { $ as isEncryptedFieldWrapper, A as workbuddyAccountId, B as modelIdOfBody, C as defaultDesktopAuthDirs, D as isVaultAccountId, E as isEncryptedCredentialError, F as WorkBuddyUpstreamClient, G as regionOf, H as parseReasoning, I as classifyUpstreamError, J as deriveAtRestKey, K as WORKBUDDY_APP_EXECUTABLE_ENV, L as declaredTools, M as CREDENTIAL_REJECTED_CODE, N as WORKBUDDY_FALLBACK_SYSTEM_PROMPT, O as legacyWorkbuddyOwnAuthPath, P as WorkBuddyCredentialRejectedError, R as isCredentialRejectedError, S as defaultDesktopAuthCandidates, T as hasEncryptedCredentialFields, U as parseUpstreamModel, V as parseCreditMultiplier, W as prepareChatBody, X as fetchAtRestKeyPayload, Y as deriveAtRestKeyId, Z as findWorkbuddyAppExecutable, _ as WORKBUDDY_AUTH_FILENAME, a as readHostHeartbeat, at as workbuddyAppExecutableCandidates, b as WorkBuddyEncryptedCredentialError, c as WORKBUDDY_CONNECT_VERSION, ct as withFileLock, d as FALLBACK_WORKBUDDY_MODELS_GLOBAL, et as isWorkbuddyBundle, f as WorkBuddyCatalog, g as ENCRYPTED_CREDENTIAL_CODE, h as fallbackModelsFor, i as processStartTimeMs, it as readAtRestKey, j as workbuddyOwnAuthPath, k as parseWorkBuddyAuth, l as piAiRuntimeInfo, lt as writeFileAtomic, m as deriveCatalog, n as clearHostHeartbeat, nt as macosNestedAppBundles, o as workbuddyHostHeartbeatPath, p as applyContextBudgets, q as clearAtRestKeyCache, r as isHeartbeatProcessAlive, rt as openEncryptedField, s as writeHostHeartbeat, st as resolveDshHome, t as WORKBUDDY_HOST_HEARTBEAT_FILENAME, tt as macosBundleExecutable, u as FALLBACK_WORKBUDDY_MODELS, v as WORKBUDDY_AUTH_FILE_ENV, w as defaultDesktopAuthPath, x as authFileName, y as WorkBuddyCredentialStore, z as knownRegionOf } from "./host-heartbeat-BxBvvAZq.js";
+import { $ as isEncryptedFieldWrapper, A as workbuddyAccountId, B as modelIdOfBody, C as defaultDesktopAuthDirs, D as isVaultAccountId, E as isEncryptedCredentialError, F as WorkBuddyUpstreamClient, G as regionOf, H as parseReasoning, I as classifyUpstreamError, J as deriveAtRestKey, K as WORKBUDDY_APP_EXECUTABLE_ENV, L as declaredTools, M as CREDENTIAL_REJECTED_CODE, N as WORKBUDDY_FALLBACK_SYSTEM_PROMPT, O as legacyWorkbuddyOwnAuthPath, P as WorkBuddyCredentialRejectedError, R as isCredentialRejectedError, S as defaultDesktopAuthCandidates, T as hasEncryptedCredentialFields, U as parseUpstreamModel, V as parseCreditMultiplier, W as prepareChatBody, X as fetchAtRestKeyPayload, Y as deriveAtRestKeyId, Z as findWorkbuddyAppExecutable, _ as WORKBUDDY_AUTH_FILENAME, a as readHostHeartbeat, at as workbuddyAppExecutableCandidates, b as WorkBuddyEncryptedCredentialError, c as WORKBUDDY_CONNECT_VERSION, ct as withFileLock, d as FALLBACK_WORKBUDDY_MODELS_GLOBAL, et as isWorkbuddyBundle, f as WorkBuddyCatalog, g as ENCRYPTED_CREDENTIAL_CODE, h as fallbackModelsFor, i as processStartTimeMs, it as readAtRestKey, j as workbuddyOwnAuthPath, k as parseWorkBuddyAuth, l as piAiRuntimeInfo, lt as writeFileAtomic, m as deriveCatalog, n as clearHostHeartbeat, nt as macosNestedAppBundles, o as workbuddyHostHeartbeatPath, p as applyContextBudgets, q as clearAtRestKeyCache, r as isHeartbeatProcessAlive, rt as openEncryptedField, s as writeHostHeartbeat, st as resolveDshHome, t as WORKBUDDY_HOST_HEARTBEAT_FILENAME, tt as macosBundleExecutable, u as FALLBACK_WORKBUDDY_MODELS, v as WORKBUDDY_AUTH_FILE_ENV, w as defaultDesktopAuthPath, x as authFileName, y as WorkBuddyCredentialStore, z as knownRegionOf } from "./host-heartbeat-De95rlXS.js";
 import z from "@deepseek-ai/schemastery";
 import { appendFile, mkdir, readFile } from "node:fs/promises";
 import { randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
@@ -1111,8 +1111,12 @@ function finish(parts, calls) {
 *     JSON、bearer 必须匹配进程内随机 secret）、常量时间比对、
 *     随机端口绑定、body 上限、上游错误分类到 HTTP 状态码的映射，
 *     均由该项目设计并验证。
-* 改动：无。安全相关代码不做「改善」，原样沿用。
-
+* 改动：随机端口绑定加了「先确认客户端能用」一步（`listenOnClientReachablePort`）。
+*   绑定方式仍是 `listen(0)` + 仅回环，随机性不变；改的只是抽到 HTTP 客户端
+*   禁用端口（fetch 规范的 block-bad-port 清单）时重抽，而不是带着一个自己
+*   客户端连不上的端口启动。四重校验、常量时间比对、body 上限、
+*   错误分类均未改动。
+*
 * @module dsh-connect-workbuddy/shim
 */
 const REQUEST_BODY_LIMIT = 67108864;
@@ -1776,6 +1780,147 @@ function contentFrame(chunk, choice, content) {
 	return `data: ${JSON.stringify(next)}\n\n`;
 }
 /**
+* Whether this runtime's `fetch` refuses `port` WITHOUT ever connecting.
+*
+* `server.listen(0)` lets the kernel pick the port, and the Fetch standard bans
+* a list of ports that `fetch` must reject before opening a socket
+* (`fetch.spec.whatwg.org#block-bad-port`, implemented as undici's `badPorts`).
+* Every client of this shim goes through that same `fetch`: pi-ai drives the
+* OpenAI SDK, whose `getDefaultFetch()` returns `globalThis.fetch`. So a shim
+* that lands on a banned port is unreachable to its own client while being
+* perfectly healthy on the wire — measured on port 6000: `fetch` refuses,
+* while `node:http`, a raw TCP socket and `curl` all connect and get 200.
+*
+* That combination is what makes it worth preventing rather than diagnosing: it
+* is silent (the SDK surfaces only `Connection error.`, with the `bad port`
+* cause dropped), total (every request in the region fails), and it does not
+* re-roll on its own.
+*
+* Whether it can happen at all depends on the machine's dynamic port range,
+* because that is the set `listen(0)` draws from:
+*
+*   Windows default 49152-65535, Linux default 32768-60999, macOS 49152-65535
+*     — every banned port is <= 10080 (the current list ends there), so the
+*       intersection is EMPTY and these machines cannot be affected.
+*   A range lowered to reach below 10080 — e.g. the legacy `MaxUserPort`
+*     registry value pinned to 15000, which yields 1024-15000 — draws from a
+*     set that CONTAINS banned ports. Measured there: 19 of 13977 ports are
+*     banned, i.e. ~0.14% per bind and ~0.27% per plugin load (two regions,
+*     one bind each).
+*
+* Probing with the client itself, rather than comparing against a copy of the
+* banned list, is deliberate: a hard-coded list drifts the moment the standard
+* gains a port, whereas the rule being satisfied here IS the client's own, so
+* asking the client cannot disagree with it. `tests/shim.spec.ts` pins the
+* error shape this relies on, so a Node change that renames it fails loudly
+* instead of silently disabling the guard.
+*/
+async function clientRefusesPort(port) {
+	try {
+		await fetch(`http://127.0.0.1:${port}/healthz`);
+		return false;
+	} catch (error) {
+		return isBadPortRefusal(error);
+	}
+}
+/**
+* Whether `error` is the client's PORT REFUSAL rather than a real transport
+* failure.
+*
+* The two must never be conflated: a refused port is worth re-rolling, while
+* `ECONNREFUSED`/`ECONNRESET` are ordinary transport errors that re-rolling
+* would only paper over. Measured shapes on Node 24:
+*
+*   refused port : TypeError('fetch failed') -> cause Error('bad port')        (no `code`)
+*   closed  port : TypeError('fetch failed') -> cause Error('connect ECONNREFUSED …') (code `ECONNREFUSED`)
+*
+* The cause chain is walked, with a bound, rather than read one level deep:
+* the OpenAI SDK wraps this same refusal in its own `APIConnectionError`, and a
+* caller should not have to know how deep the active client happens to nest it.
+*/
+function isBadPortRefusal(error) {
+	let current = error;
+	for (let depth = 0; depth < 4; depth++) {
+		if (!(current instanceof Error)) return false;
+		if (current.message === "bad port") return true;
+		current = current.cause;
+	}
+	return false;
+}
+/**
+* Listen on an ephemeral loopback port, rejecting on failure.
+*
+* Also settles on `close`, which is NOT redundant: measured on Node 24, a
+* `close()` that lands while `listen()` is still pending fires neither
+* `listening` nor `error` — only `close`. Without that third listener a dispose
+* during startup would leave this promise (and therefore the shim's `ready`)
+* pending forever, wedging plugin unload. Resolving there is deliberate:
+* disposal is a satisfied end state, not a startup failure.
+*/
+function listenOnce(server) {
+	return new Promise((resolve, reject) => {
+		const settle = () => {
+			server.off("listening", onListening);
+			server.off("error", onError);
+			server.off("close", onClose);
+		};
+		const onListening = () => {
+			settle();
+			resolve();
+		};
+		const onError = (error) => {
+			settle();
+			reject(error);
+		};
+		const onClose = () => {
+			settle();
+			resolve();
+		};
+		server.once("listening", onListening);
+		server.once("error", onError);
+		server.once("close", onClose);
+		server.listen(0, "127.0.0.1");
+	});
+}
+/** Stop listening, resolving once the listener is down. */
+function closeOnce(server) {
+	return new Promise((resolve) => server.close(() => resolve()));
+}
+/**
+* Bind an ephemeral loopback port that the CLIENT can actually reach.
+*
+* `listen(0)` stays the right way to get a port — the kernel picks a free one
+* instead of this plugin guessing a number — but the first pick is not always
+* usable, so the roll repeats while the client refuses it. See
+* {@link clientRefusesPort} for why the client's own answer is the criterion,
+* and {@link PORT_ROLL_LIMIT} for why the loop is bounded.
+*
+* The probe is injected rather than imported so the re-roll path can be driven
+* deterministically: no test can make `listen(0)` return a banned port on
+* demand, so this seam is the only way to pin the behaviour that actually
+* matters.
+*
+* `ready` (the returned promise) therefore resolves only once a port is
+* settled, which is what lets every consumer keep reading `baseUrl()` as it
+* always has.
+*/
+async function listenOnClientReachablePort(options) {
+	const { server, clientRefuses, logger, cancelled } = options;
+	for (let attempt = 1;; attempt++) {
+		if (cancelled?.() === true) return;
+		await listenOnce(server);
+		const address = server.address();
+		const port = address === null || typeof address === "string" ? void 0 : address.port;
+		if (port === void 0 || !await clientRefuses(port)) return;
+		if (attempt >= 5) {
+			logger?.warn(`dsh-connect-workbuddy: port ${port} is on the HTTP client's refused list and 5 rolls did not avoid one; serving on it anyway`);
+			return;
+		}
+		logger?.warn(`dsh-connect-workbuddy: port ${port} is refused by the HTTP client; re-rolling (attempt ${attempt})`);
+		await closeOnce(server);
+	}
+}
+/**
 * Start the loopback endpoint. Requests must carry the shim's shared secret;
 * the loopback bind alone is not a trust boundary.
 */
@@ -1804,11 +1949,27 @@ function createWorkBuddyShim(options) {
 	const server = createServer((req, res) => {
 		handle(req, res);
 	});
-	const ready = new Promise((resolve, reject) => {
-		server.once("listening", () => resolve());
-		server.once("error", reject);
+	let disposed = false;
+	server.on("error", (error) => {
+		if (server.listening) logger?.error("dsh-connect-workbuddy: loopback listener error", error);
+	});
+	/**
+	* Resolves once the listener is up on a port the client can actually reach.
+	*
+	* The port is settled HERE — `listenOnClientReachablePort` re-rolls while the
+	* client refuses the assigned one — so every consumer can keep resolving
+	* `baseUrl()` exactly as before, with no invalidation or rebuild step. A
+	* genuine bind failure still rejects, the one behaviour the caller relies on.
+	*/
+	const ready = listenOnClientReachablePort({
+		server,
+		clientRefuses: clientRefusesPort,
+		logger,
+		cancelled: () => disposed
+	}).catch((error) => {
+		logger?.error("dsh-connect-workbuddy: loopback listener failed to start", error);
+		throw error;
 	});
-	server.listen(0, "127.0.0.1");
 	const baseUrl = () => {
 		const address = server.address();
 		if (address === null || typeof address === "string") throw new Error("workbuddy shim has no listening address");
@@ -2054,10 +2215,10 @@ function createWorkBuddyShim(options) {
 		ready,
 		baseUrl,
 		token: () => SHARED_SECRET,
-		close: () => new Promise((resolve, reject) => {
+		close: () => new Promise((resolve) => {
+			disposed = true;
 			server.close(() => resolve());
 			server.closeAllConnections();
-			server.once("error", reject);
 		})
 	};
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "dsh-connect-workbuddy",
   "displayName": "DSH Connect WorkBuddy",
   "description": "把本机登录的 WorkBuddy 模型接入 DeepSeek Harness，并提供只读的积分概览与模型管理。",
-  "version": "4.6.0",
+  "version": "4.6.2",
   "author": "dingminhua",
   "copyright": "Copyright (c) 2026 LaoDing",
   "license": "MIT",