dsh-xdpool 2.4.2 → 2.4.3

package/CHANGELOG.md

@@ -1,6 +1,60 @@
 # Changelog
 本项目的所有重要变更都会记录在此文件。
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+## 2.4.3 — 渠道包补上 11128、粘性绑定跨重启、网关白名单、目录 TTL，外加 CodeArts 重签开关
+
+> 2.4.1 与 2.4.2 修的是**池车道**（`src/upstream.ts`）；这一版把同一套 11128 规则补进**渠道车道**自己那份 channel pack，并顺带解决三件独立的事：会话粘性绑定不该止于进程边界、网关页面的勾选该是真开关、远端模型目录该会过期。四个 PR 来自社区（[@GIGIGIGIbaby](https://github.com/GIGIGIGIbaby)），复核与发布由维护者完成。另附一个默认关闭的 CodeArts 重签开关（见末节）。
+
+### 渠道账号也吃 400 / 11128（PR [#63](https://github.com/XDTrees/dsh-xdpool/pull/63)）
+
+`workbuddy` 渠道在 `channels.ts` 的 `POOL_OWNED_CHANNELS` 列表里，但它**不走** `src/upstream.ts` —— 它由 channel pack 自己的 WorkBuddy 适配器应答。2.4.1 的两道内容指纹、2.4.2 的 role 转换与三个会话身份头都只加在了池车道，于是渠道账号继续吃到 2.4.2 已经替别人修好的那个 `400 / 11128`：
+
+| 项 | 渠道适配器改前 | 改后 |
+|---|---|---|
+| 首条消息 role | `developer` | `system`（就地转换） |
+| `powered by DeepSeek Harness` | 原样发出 | `running on DeepSeek Harness` |
+| `DeepSeek Harness Web GUI` | 原样发出 | `DeepSeek Harness web interface` |
+| `X-Conversation-ID` / `-Request-ID` / `-Message-ID` | 一个都不带 | 三个都带 |
+
+三处编辑各自标了 `[xdpool-local]`，配套的 `tests/chat-identity-headers.test.ts` 直接对**已发布的 bundle** 做源断言（pack.js 是外部构建产物、无法 `import`，所以只能在字节层 pin 住）—— 下次 pack 刷新若把这三处冲掉，测试会变红，而不是静默回退。
+
+### 会话粘性绑定跨过进程边界（PR [#64](https://github.com/XDTrees/dsh-xdpool/pull/64)）
+
+卡片承诺「一个会话一个账号」，但这个承诺原先止于进程边界：绑定存在一个 `Map` 里，每次重启都重新挑选，于是同一个会话一天里可能被三个账号各服务一遍，每次都按完整 prompt 计费。现在这张表写进插件状态目录（只存哈希到账号 id，不含任何消息内容），构造时加载，写入合并成一次原子 rename，并沿用与内存版相同的 LRU 上限。
+
+测试特意把会话绑到一个「默认挑选不会选中」的账号 —— 新建的空池本来就会同意未绑定会话的选择，所以「两个池答案一致」在禁用加载时也能通过；实测把加载去掉会让其中三个用例变红。
+
+### 网关页面的勾选不再是纯展示（PR [#65](https://github.com/XDTrees/dsh-xdpool/pull/65)）
+
+Gateway 页的模型勾选框与 LAN 共享列表此前只是**展示过滤器**：`/v1/models` 会隐藏没勾的模型，但请求路径照单全收。一台还留着旧模型 id 的手机、或照文档猜一个 id 的第二编辑器，就能继续拿卡片上写着「关」的模型花用户的钱。
+
+现在强制发生在**调用方实际发出的那个 id 上**，且在任何车道剥前缀或改写 body **之前**，覆盖每条车道：pool、aggregate、free、combo，以及登录渠道。列表与闸门读同一份集合——这正是让卡片上的勾选有意义的原因。
+
+### 远端模型目录会过期（PR [#66](https://github.com/XDTrees/dsh-xdpool/pull/66)）
+
+bundle 里每个适配器都把 `remoteModels` 缓存到进程结束，于是厂商改名或调整倍率要等重启才反映到卡片上——而**改名通常就是改价**，因为倍率是名字的一部分。现在由一道 TTL 闸门决定缓存能否应答，时长十分钟，可用 `DSH_XDPOOL_CATALOG_TTL_MS` 覆盖以便测试。
+
+闸门刻意**不清缓存**：加载器只在成功时覆盖，所以刷新失败会继续沿用最后一份已知良好的目录，而不是退化成一堆裸 id；网关侧 30s 的冷却又限住了重试速率。同样无需重建 lib —— `channels.ts` 在运行期按路径加载 `pack.js`。
+
+### 可选：CodeArts 请求带重签头（默认关闭，`[xdpool-local]`）
+
+在 CodeArts 的 chat 请求上追加两个头：
+
+```
+x-bili-resign: sdk-hmac-sha256
+x-bili-resign-credential: base64({"ak":"…","sk":"…","token":"…"})
+```
+
+用途是让 billion-context 用这对凭证**重签**一条它接管的 SDK-HMAC-SHA256 请求：该方案的签名覆盖请求体，压缩改写会让签名失效，而 bili 拿不到重签凭证时会按 compress-or-refuse 契约**本地拒发**（`bili_resign_unavailable`，表现为 403，再被误读成「密钥无效」）。带上这对头，bili 就能重算签名，压缩能力得以保留（billion-context 的 #1884 逃生口）。
+
+**为什么默认关闭**：`billion-context` 只在 `optionalDependencies` 里，未安装时这两个头会**直达上游**，而它们携带的是 AK/SK；另外 bili 的进程内 native client 自己会构造这两个头（`resignExtra`），xdpool 加不加都不影响它。开关留给「xdpool 直接对接 bili 代理路径」或将来需要显式携带凭证的场合 —— 启用方式是在 pool 构造时传 `codeartsResignHeaders: true`（当前没有对应的用户级配置项）。
+
+配套 `tests/codearts-resign-headers.test.ts` 用源断言 pin 住四件事：两个头名齐全、字段名与 bili `decodeApigCredential` 读取的 `ak`/`sk`/`token` 一致、插入位置在 `signRequestHuawei` 之后、以及默认关闭。
+
+### 其他
+
+- 新增测试：渠道包 11128 规则源断言、粘性绑定跨重启（含「去掉加载即变红」的对照）、网关白名单与列表一致性、目录 TTL。
+
 ## 2.4.2 — 第二道内容指纹：`Web GUI` 那句，以及 assistant 历史
 > 2.4.1 之后仍有 11128。这一版补上第二道内容指纹，并把改写范围扩到 assistant 历史。修复来自社区 PR [#62](https://github.com/XDTrees/dsh-xdpool/pull/62)（[@jmglsi](https://github.com/jmglsi)），实测复核与发布由维护者完成。
 ### 同一条提示词里还有第二道指纹

package/lib/bin.js

@@ -1,5 +1,5 @@
 import { createDecipheriv, createHash, randomUUID } from "node:crypto";
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
 import { copyFile, mkdir, readFile, readdir, rename, rm, writeFile, writeFile as writeFile$1 } from "node:fs/promises";
 import { homedir, platform } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
@@ -3363,6 +3363,9 @@ var WorkBuddyAccountPool = class {
 	* the LRU order: re-binding deletes then re-inserts.
 	*/
 	affinity = /* @__PURE__ */ new Map();
+	/** Where the bindings above are persisted; undefined keeps them in memory. */
+	affinityPath;
+	affinitySaveTimer;
 	lastScanAtMs = 0;
 	/**
 	* The account id the user pinned, or undefined for none.
@@ -3472,6 +3475,8 @@ var WorkBuddyAccountPool = class {
 		this.distribution = options.distribution ?? "priority";
 		this.persistent = options.persistent ?? false;
 		this.storePath = accountStorePath();
+		this.affinityPath = options.affinityPath;
+		if (this.affinityPath !== void 0) this.loadAffinity();
 	}
 	/**
 	* Re-apply configuration that only affects discovery and cooldown policy,
@@ -3747,6 +3752,49 @@ var WorkBuddyAccountPool = class {
 			if (oldest === void 0) break;
 			this.affinity.delete(oldest);
 		}
+		this.scheduleAffinitySave();
+	}
+	/**
+	* Restore bindings written by a previous process.
+	*
+	* Tolerant like the other state files: a malformed document or one bad entry
+	* must not take the pool down, and an account id that no longer exists is
+	* simply never matched (the next acquire re-picks and rebinds).
+	*/
+	loadAffinity() {
+		if (this.affinityPath === void 0) return;
+		try {
+			const bindings = JSON.parse(readFileSync(this.affinityPath, "utf8")).bindings;
+			if (typeof bindings !== "object" || bindings === null || Array.isArray(bindings)) return;
+			for (const [key, value] of Object.entries(bindings)) {
+				if (key === "" || typeof value !== "string" || value === "") continue;
+				this.affinity.set(key, value);
+			}
+			while (this.affinity.size > STICKY_AFFINITY_LIMIT) {
+				const oldest = this.affinity.keys().next().value;
+				if (oldest === void 0) break;
+				this.affinity.delete(oldest);
+			}
+		} catch {}
+	}
+	/** Write the bindings back, coalescing a burst into one atomic rename. */
+	scheduleAffinitySave() {
+		if (this.affinityPath === void 0 || this.affinitySaveTimer !== void 0) return;
+		this.affinitySaveTimer = setTimeout(() => {
+			this.affinitySaveTimer = void 0;
+			const path = this.affinityPath;
+			if (path === void 0) return;
+			try {
+				mkdirSync(dirname(path), { recursive: true });
+				writeFileSync(`${path}.tmp`, `${JSON.stringify({
+					version: 1,
+					bindings: Object.fromEntries(this.affinity)
+				}, null, 2)}
+`, "utf8");
+				renameSync(`${path}.tmp`, path);
+			} catch {}
+		}, 500);
+		this.affinitySaveTimer.unref?.();
 	}
 	/**
 	* `sticky`: the account this conversation already used, when it can still
@@ -11217,7 +11265,8 @@ function createCore(logger) {
 	const pool = new WorkBuddyAccountPool({
 		...logger === void 0 ? {} : { logger },
 		client,
-		persistent: true
+		persistent: true,
+		affinityPath: join(pluginDataDir(), "sticky-affinity.json")
 	});
 	return {
 		pool,

package/lib/client.js

@@ -1255,6 +1255,21 @@ window.__ModuleLoader__.load({
 .dsm-xdpool-gw-actions{display:flex;align-items:center;gap:6px;flex-wrap:wrap}
 .dsm-xdpool-gw-flash{margin:0;padding:6px 10px;border-radius:9px;border:1px solid color-mix(in srgb, var(--dsw-alias-border-l1,#ffffff14) 70%, transparent);background:color-mix(in srgb, var(--dsw-alias-bg-layer-1,#191a1e) 72%, transparent);color:var(--dsw-alias-label-secondary,#c6c9d0);font-size:11px;line-height:17px;word-break:break-word}
 .dsm-xdpool-gw-btn{appearance:none;display:inline-flex;align-items:center;gap:6px;font:inherit;font-size:11.5px;font-weight:560;line-height:17px;padding:4px 12px;border-radius:8px;border:1px solid color-mix(in srgb, var(--dsw-alias-border-l2,#36373b) 85%, transparent);background:color-mix(in srgb, var(--dsw-alias-bg-layer-3,#2a2c33) 70%, transparent);color:var(--dsw-alias-label-secondary,#c6c9d0);cursor:pointer;white-space:nowrap;transition:border-color .16s ease,color .16s ease,background .16s ease,transform .18s var(--ease-instrument,cubic-bezier(.16,1,.3,1))}
+/* The gateway's shared-model picker. Grouped by lane, and each row carries BOTH
+   the display name and the wire id, because for the login channels they are
+   different words: the user knows the model as "Qwen3.8-Flash · 免费" and has to
+   type "qfmodel" into the client. Showing only one of the two makes the list
+   either unreadable or unusable. */
+.dsm-xdpool-gw-group{margin-top:10px;display:flex;flex-direction:column;gap:2px;min-width:0}
+.dsm-xdpool-gw-group-title{margin:0 0 2px;color:var(--dsw-alias-label-tertiary,#8a90a0);font-size:11px;line-height:16px;font-weight:650;letter-spacing:.1px;text-transform:lowercase}
+.dsm-xdpool-gw-model{display:grid;grid-template-columns:16px minmax(0,1fr) auto;align-items:center;gap:8px;padding:3px 6px;border-radius:8px;cursor:pointer;min-width:0}
+.dsm-xdpool-gw-model:hover{background:color-mix(in srgb, var(--dsw-alias-bg-layer-1,#191a1e) 60%, transparent)}
+.dsm-xdpool-gw-model input{appearance:none;width:14px;height:14px;margin:0;border-radius:4px;border:1px solid var(--dsw-alias-border-l2,#36373b);background:color-mix(in srgb, var(--dsw-alias-bg-layer-1,#191a1e) 78%, transparent);cursor:pointer;display:grid;place-items:center}
+.dsm-xdpool-gw-model input:checked{background:var(--dsw-alias-brand-primary,#5686fe);border-color:var(--dsw-alias-brand-primary,#5686fe)}
+.dsm-xdpool-gw-model input:checked::after{content:"";width:6px;height:3px;border-left:1.5px solid #fff;border-bottom:1.5px solid #fff;transform:rotate(-45deg) translateY(-1px)}
+.dsm-xdpool-gw-model input:focus-visible{outline:2px solid var(--dsw-alias-brand-primary,#5686fe);outline-offset:1px}
+.dsm-xdpool-gw-model-name{color:var(--dsw-alias-label-primary,#e8e8ea);font-size:12px;line-height:17px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;min-width:0}
+.dsm-xdpool-gw-model-id{font-family:var(--dsw-alias-font-mono,ui-monospace,Menlo,Consolas,monospace);font-size:11px;line-height:16px;color:var(--dsw-alias-label-tertiary,#8a90a0);white-space:nowrap}
 .dsm-xdpool-gw-btn:hover:not(:disabled){transform:translateY(-1px);border-color:color-mix(in srgb, var(--dsw-alias-brand-primary,#5686fe) 55%, var(--dsw-alias-border-l2,#36373b));color:var(--dsw-alias-label-primary,#e8e8ea)}
 .dsm-xdpool-gw-btn:active:not(:disabled){transform:translateY(0);box-shadow:inset 0 2px 4px rgb(0 0 0 / 22%)}
 .dsm-xdpool-gw-btn:focus-visible{outline:2px solid var(--dsw-alias-brand-primary,#5686fe);outline-offset:2px}
@@ -10776,6 +10791,35 @@ window.__ModuleLoader__.load({
 			const [revealed, setRevealed] = (0, react.useState)(false);
 			const [host, setHost] = (0, react.useState)("127.0.0.1");
 			const [port, setPort] = (0, react.useState)("8326");
+			/**
+			* The in-progress share list, or undefined while it still mirrors the server.
+			*
+			* Held as a draft for the same reason the model card holds one: saving is a
+			* deliberate act here, because every unchecked row stops working on whatever
+			* device is already pointed at the gateway.
+			*/
+			const [draftShared, setDraftShared] = (0, react.useState)(void 0);
+			/**
+			* Which ids are shared right now.
+			*
+			* `status.shared === undefined` means the user has never chosen, and the
+			* gateway is serving everything — so the picker must show every row ticked
+			* rather than an empty list, which would read as "nothing is shared" and invite
+			* a save that closes a gateway that was open.
+			*/
+			const candidates = status?.candidates ?? [];
+			const serverShared = status?.shared ?? candidates.map((row) => row.id);
+			const shared = draftShared ?? new Set(serverShared);
+			const sharedDirty = draftShared !== void 0 && (draftShared.size !== serverShared.length || [...draftShared].some((id) => !serverShared.includes(id)));
+			const toggleShared = (id) => {
+				const next = new Set(shared);
+				if (next.has(id)) next.delete(id);
+				else next.add(id);
+				setDraftShared(next);
+			};
+			const setAllShared = (on) => {
+				setDraftShared(on ? new Set(candidates.map((row) => row.id)) : /* @__PURE__ */ new Set());
+			};
 			/** True once the server's values were adopted, so polls do not stomp edits. */
 			const seeded = (0, react.useRef)(false);
 			const mounted = (0, react.useRef)(true);
@@ -11015,6 +11059,92 @@ window.__ModuleLoader__.load({
 							})
 						]
 					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						className: "dsm-xdpool-sec",
+						children: [
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+								className: "dsm-xdpool-sectitle",
+								children: t?.("gw.share") ?? "Shared models"
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+								className: "dsm-xdpool-gw-note",
+								children: t?.("gw.shareHint") ?? ""
+							}),
+							candidates.length === 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+								className: "dsm-xdpool-gw-note",
+								children: t?.("gw.shareNone") ?? ""
+							}) : /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
+								/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+									className: "dsm-xdpool-gw-actions",
+									children: [
+										/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+											type: "button",
+											className: "dsm-xdpool-gw-btn",
+											"data-on": "false",
+											disabled: busy,
+											onClick: () => {
+												setAllShared(true);
+											},
+											children: t?.("gw.shareAll") ?? "Select all"
+										}),
+										/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+											type: "button",
+											className: "dsm-xdpool-gw-btn",
+											"data-on": "false",
+											disabled: busy,
+											onClick: () => {
+												setAllShared(false);
+											},
+											children: t?.("gw.shareNoneBtn") ?? "Select none"
+										}),
+										/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+											type: "button",
+											className: "dsm-xdpool-gw-btn",
+											"data-on": "true",
+											disabled: busy || !sharedDirty,
+											onClick: () => {
+												write({ models: [...shared] }).then(() => {
+													setDraftShared(void 0);
+												});
+											},
+											children: t?.("gw.shareSave") ?? "Save"
+										})
+									]
+								}),
+								sharedDirty ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+									className: "dsm-xdpool-gw-warn",
+									children: t?.("gw.shareDirty") ?? ""
+								}) : null,
+								[...new Set(candidates.map((row) => row.source))].map((source) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+									className: "dsm-xdpool-gw-group",
+									children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+										className: "dsm-xdpool-gw-group-title",
+										children: source
+									}), candidates.filter((row) => row.source === source).map((row) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", {
+										className: "dsm-xdpool-gw-model",
+										children: [
+											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+												type: "checkbox",
+												checked: shared.has(row.id),
+												disabled: busy,
+												onChange: () => {
+													toggleShared(row.id);
+												}
+											}),
+											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+												className: "dsm-xdpool-gw-model-name",
+												children: row.name
+											}),
+											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+												className: "dsm-xdpool-gw-model-id",
+												children: row.id
+											})
+										]
+									}, row.id))]
+								}, source))
+							] })
+						]
+					}),
 					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 						className: "dsm-xdpool-sec",
 						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
@@ -12195,7 +12325,7 @@ window.__ModuleLoader__.load({
 		*
 		* @module dsh-xdpool/version
 		*/
-		const POOL_VERSION = "2.4.2";
+		const POOL_VERSION = "2.4.3";
 		//#endregion
 		//#region src/client/PoolCard.tsx
 		/**
@@ -14961,6 +15091,15 @@ window.__ModuleLoader__.load({
 			"gw.usageHint": "Any OpenAI-compatible app works. Set its base URL to the endpoint above, pick a model out of /v1/models, and send this key as the API key. The relay passes /v1/models and /v1/chat/completions only; everything else is refused before a byte is forwarded.",
 			"gw.loading": "Reading the relay status…",
 			"gw.saveFailed": "Could not save",
+			"gw.share": "Shared models",
+			"gw.shareHint": "Only the ticked models are reachable over the gateway. Unticking one does not just hide it from /v1/models — the gateway refuses it, because the relay key is a single secret shared by every device on the network, and a listing a client can ignore is not a restriction.",
+			"gw.shareNone": "Nothing to offer yet: no model is reachable until an account pool, an aggregate key or a signed-in channel provides one.",
+			"gw.shareAll": "Select all",
+			"gw.shareNoneBtn": "Select none",
+			"gw.shareSave": "Save sharing",
+			"gw.shareSaved": "Gateway sharing updated",
+			"gw.shareDirty": "Not saved yet. A device already using an unticked model will start getting 403.",
+			"gw.shareCount": "{shared} of {total} shared",
 			"ledger.title": "Data dashboard",
 			"ledger.sub": "Every number here is counted from calls this pool actually made.",
 			"ledger.window": "last {count} call(s)",
@@ -15463,6 +15602,15 @@ window.__ModuleLoader__.load({
 			"gw.usageHint": "任何 OpenAI 兼容的客户端都行：接口地址填上面那个入口，模型从 /v1/models 里挑，密钥填到这个 API 密钥的位置。中继只放行 /v1/models 和 /v1/chat/completions，其余路径在转发任何字节之前就拒掉。",
 			"gw.loading": "正在读取中继状态……",
 			"gw.saveFailed": "没能保存",
+			"gw.share": "共享哪些模型",
+			"gw.shareHint": "只有勾选的模型能通过网关访问。取消勾选不只是把它从 /v1/models 里藏起来——网关会直接拒绝它。因为中继密钥是整台网络上所有设备共用的同一把，而一份客户端可以无视的列表算不上限制。",
+			"gw.shareNone": "暂时无可提供：在账号池、聚合渠道密钥或已登录的渠道给出模型之前，这里不会有任何条目。",
+			"gw.shareAll": "全选",
+			"gw.shareNoneBtn": "全不选",
+			"gw.shareSave": "保存共享设置",
+			"gw.shareSaved": "网关共享设置已更新",
+			"gw.shareDirty": "尚未保存。已在使用某个被取消勾选模型的设备，会开始收到 403。",
+			"gw.shareCount": "已共享 {shared} / {total}",
 			"ledger.title": "数据看板",
 			"ledger.sub": "这里每个数字，都是这个池子真实发出去的调用数出来的。",
 			"ledger.window": "最近 {count} 次调用",

package/lib/index.d.ts

@@ -934,6 +934,15 @@ export declare function candidateAuthDirs(env?: NodeJS.ProcessEnv): string[];
 /** How the pool chooses which account serves the next request. */
 type AccountDistribution = 'priority' | 'round-robin' | 'balanced' | 'sticky' | 'expiry';
 interface AccountPoolOptions {
+  /**
+   * File the `sticky` bindings are remembered in, or undefined for memory only.
+   *
+   * The card promises one account per conversation, and that promise used to end
+   * at the process boundary: every restart re-picked, so one session could be
+   * served by three different accounts in a day and pay full prompt cost each
+   * time. The caller passes the plugin's own state path; tests pass a temp file.
+   */
+  affinityPath?: string;
   /** Logger for discovery and rotation events. */
   logger?: {
     info?(...args: unknown[]): void;
@@ -1026,6 +1035,9 @@ export declare class WorkBuddyAccountPool {
    * the LRU order: re-binding deletes then re-inserts.
    */
   private readonly affinity;
+  /** Where the bindings above are persisted; undefined keeps them in memory. */
+  private readonly affinityPath;
+  private affinitySaveTimer;
   private lastScanAtMs;
   /**
    * The account id the user pinned, or undefined for none.
@@ -1205,6 +1217,16 @@ export declare class WorkBuddyAccountPool {
   private pickRoundRobin;
   /** Remember which account a conversation is bound to, keeping LRU order. */
   private bindAffinity;
+  /**
+   * Restore bindings written by a previous process.
+   *
+   * Tolerant like the other state files: a malformed document or one bad entry
+   * must not take the pool down, and an account id that no longer exists is
+   * simply never matched (the next acquire re-picks and rebinds).
+   */
+  private loadAffinity;
+  /** Write the bindings back, coalescing a burst into one atomic rename. */
+  private scheduleAffinitySave;
   /**
    * `sticky`: the account this conversation already used, when it can still
    * serve the model being asked for.
@@ -1763,6 +1785,69 @@ interface PoolWebRelayPatch {
   host?: string;
   port?: number;
   key?: string;
+  /**
+   * The models to share with LAN clients, by gateway id.
+   *
+   * An empty array is an answer, not an absence: it means the user unticked
+   * everything, and the gateway then refuses every model. Only "never set"
+   * leaves the gateway open.
+   */
+  models?: string[];
+}
+/**
+ * What {@link POOL_RELAY_PATH} answers with.
+ *
+ * `listening` is separate from `enabled` because "you turned it on and it could
+ * not bind" is a state the user has to be able to see. Collapsing the two would
+ * tell them to switch on something that is already on.
+ *
+ * `key` is the RELAY key, in full, on purpose: the card has to show it so it can
+ * be pasted into another device. It is the key the plugin minted for LAN
+ * clients — the shim's own per-process secret is never returned by any route.
+ *
+ * The type lives here rather than beside the listener because the client card
+ * renders it, and importing the listener's module would drag `node:http` into a
+ * browser bundle.
+ */
+interface PoolWebRelayStatus {
+  enabled: boolean;
+  listening: boolean;
+  host: string;
+  port: number;
+  /** Where a client should point; '' until something is listening. */
+  endpoint: string;
+  key: string;
+  /** Why nothing is bound; '' when there is nothing to explain. */
+  error: string;
+  /**
+   * Every model the gateway could serve, with the name a human reads.
+   *
+   * Built from the shim's own roster, so the picker cannot offer a model the
+   * gateway would then refuse. The name is here because the OpenAI `/v1/models`
+   * schema has no such field: `qfmodel` is what a client sends, and
+   * `Qwen3.8-Flash · 免费` is what the user knows it as, and only this card can
+   * show both together.
+   *
+   * REQUIRED, and required on the POST answer too: the card treats a write
+   * response as the new state, so a save that answered without the roster emptied
+   * the picker until the next poll. Declaring it optional let the write path
+   * return the bare listener status and typecheck clean.
+   */
+  candidates: readonly PoolWebGatewayModel[];
+  /**
+   * The shared list in force. `undefined` means the user has never chosen, which
+   * the card must render as "everything is shared" rather than an empty picker.
+   */
+  shared?: readonly string[];
+}
+/** One row of the gateway's model picker. */
+interface PoolWebGatewayModel {
+  /** What a client sends, and what the allowlist stores. */
+  id: string;
+  /** The display name from the lane that serves it. */
+  name: string;
+  /** The lane or channel it belongs to; what the picker groups under. */
+  source: string;
 }
 /**
  * What a key probe answered.
@@ -2451,6 +2536,21 @@ interface RelaySetting {
   port?: number;
   /** URL-safe shared secret LAN clients authenticate with. */
   key?: string;
+  /**
+   * Which models the gateway may serve, by gateway id (`buddy:hy3`,
+   * `qoder:qfmodel`, `free:…`, `provider/model`).
+   *
+   * Absent and empty are DIFFERENT answers and the distinction is load-bearing:
+   * absent means "no selection has ever been made, serve everything", so
+   * upgrading does not silently break a gateway a device is already pointed at;
+   * empty means "the user unticked everything", and is honoured as such.
+   *
+   * This is an allowlist enforced on the request, not just on the listing. A
+   * relay key is one value shared by every device on the LAN, so "hidden from
+   * /v1/models" would leave every other lane reachable to anything that guessed
+   * an id — including the login channels, whose quota is this account's.
+   */
+  models?: string[];
 }
 //#endregion
 //#region src/aggregate.d.ts
@@ -2717,6 +2817,40 @@ declare class UsageRecorder {
   private days;
 }
 //#endregion
+//#region src/channel-lane.d.ts
+/** One model as the gateway lists and routes it. */
+interface ChannelLaneRow {
+  /** The composite id a client sends: `<channel>:<model>`. */
+  id: string;
+  channel: string;
+  modelId: string;
+  name: string;
+}
+/** One translated event, so the caller decides how to frame it as SSE. */
+type ChannelLaneEvent = {
+  kind: 'delta';
+  delta: Record<string, unknown>;
+} | {
+  kind: 'usage';
+  usage: Record<string, number>;
+} | {
+  kind: 'done';
+  finishReason: string;
+};
+interface ChannelLane {
+  rows: () => Promise<readonly ChannelLaneRow[]>;
+  resolve: (id: string) => {
+    channel: string;
+    modelId: string;
+  } | undefined;
+  turn: (input: {
+    channel: string;
+    modelId: string;
+    body: Record<string, unknown>;
+    signal: AbortSignal;
+  }) => AsyncGenerator<ChannelLaneEvent>;
+}
+//#endregion
 //#region src/shim.d.ts
 interface ShimLogger {
   info?(...args: unknown[]): void;
@@ -2727,8 +2861,29 @@ interface WorkBuddyShim {
   ready: Promise<void>;
   baseUrl(): string;
   token(): string;
+  /**
+   * Everything the gateway could serve, with display names.
+   *
+   * The card's model picker reads this; `/v1/models` maps the same entries down
+   * to ids. One source so the card cannot offer a model the gateway then refuses.
+   */
+  roster(): Promise<readonly GatewayModelEntry[]>;
   close(): Promise<void>;
 }
+/**
+ * One gateway-visible model: the id a client sends, the name a human reads, and
+ * the lane it belongs to.
+ *
+ * Both are needed because they disagree in exactly the places that matter. A
+ * qoder model is `qfmodel` on the wire and `Qwen3.8-Flash · 免费` in every
+ * interface the user has met it in, and the OpenAI `/v1/models` schema has no
+ * field for the second — so the name can only ever be shown here, on the card.
+ */
+interface GatewayModelEntry {
+  id: string;
+  name: string;
+  source: string;
+}
 /**
  * Everything the aggregate lane needs to answer one request.
  *
@@ -2752,9 +2907,18 @@ interface ExtraLaneOptions {
   free: ExtraLaneSource;
 }
 interface ExtraLaneSource {
+  /**
+   * The rows this lane offers.
+   *
+   * `name` is the human-facing display name the free catalog already keeps (a
+   * raw upstream id is deliberately never shown to a picker); it is optional
+   * here because the lane's own contract only ever needed the ids, and the
+   * gateway's model picker is the first consumer that wants the label too.
+   */
   current: () => readonly {
     modelId: string;
     id: string;
+    name?: string;
   }[];
   /**
    * Run one turn, handing back the frames to write.
@@ -2809,6 +2973,29 @@ interface WorkBuddyShimOptions {
    * give the user two names for one lane.
    */
   extra?: ExtraLaneOptions;
+  /**
+   * The fifth lane: the 扫码登录 channels, reached through the host's own LLM
+   * seam rather than a socket this plugin owns.
+   *
+   * CN-shim-only for the aggregate lane's reason — a second copy under the
+   * global provider id would list every channel twice — and the relay is wired to
+   * this shim, so this is also the only shim the LAN gateway can see.
+   */
+  channels?: ChannelLane;
+  /**
+   * The gateway allowlist, re-read per request.
+   *
+   * `undefined` means "no selection has been made: serve everything to LAN
+   * clients too", so upgrading cannot silently break a device already pointed at
+   * the relay. An empty array is the opposite answer — the user unticked
+   * everything — and is enforced as such.
+   *
+   * Only consulted for requests carrying {@link RELAY_HOP_HEADER}, which is the
+   * relay's own marker. The host's adapter reaches this same process without it,
+   * so the models DSH offers in its picker are never narrowed by a list meant
+   * for other machines.
+   */
+  lanModels?: () => readonly string[] | undefined;
 }
 export declare function createWorkBuddyShim(options: WorkBuddyShimOptions): WorkBuddyShim;
 //#endregion
@@ -3618,27 +3805,6 @@ export declare function readPreferredIdSync(path?: string): string | undefined;
  */
 export declare function writePreferredId(accountId: string | undefined, path?: string): Promise<void>;
 //#endregion
-//#region src/relay.d.ts
-interface PoolRelayStatus {
-  enabled: boolean;
-  /** Whether a listener is actually bound right now. */
-  listening: boolean;
-  host: string;
-  port: number;
-  /** Where a client should point; '' until something is listening. */
-  endpoint: string;
-  /**
-   * The relay key in full.
-   *
-   * Returned on purpose: the card has to show it once so the user can copy it
-   * into the other device. This is the key WE minted for LAN clients, not the
-   * shim secret, and it grants nothing beyond reaching the pool.
-   */
-  key: string;
-  /** Why nothing is bound; '' when there is nothing to explain. */
-  error: string;
-}
-//#endregion
 //#region src/web-status.d.ts
 /** Constructor dependencies — a narrow slice of the pool runtime. */
 interface PoolStatusRouteOptions {
@@ -3836,9 +4002,9 @@ interface PoolStatusRouteOptions {
    * the plugin minted for LAN clients. The shim's own per-process secret is never
    * exposed by any route.
    */
-  relayDocument?: () => Promise<PoolRelayStatus>;
+  relayDocument?: () => Promise<PoolWebRelayStatus>;
   /** Apply a relay patch, re-evaluate the listener, and answer with the new state. */
-  saveRelay?: (patch: PoolWebRelayPatch) => Promise<PoolRelayStatus>;
+  saveRelay?: (patch: PoolWebRelayPatch) => Promise<PoolWebRelayStatus>;
 }
 /**
  * Assemble the card's status document. Per-account credits and check-in state