@shgroup/dsh-serenity-hooks 1.58.2 → 1.59.1

package/lib/index.js

@@ -2,10 +2,11 @@ import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.js";
 import { c as hostInjected, d as hostSessions, f as hostSettings, h as hostWebServer, i as cccRootForExec, l as hostLlm, m as hostWeb, n as agentCwdFor, o as listCccs, p as hostSubagents, r as cccRootForCwd, s as hostAgents, t as NO_CCC_FROM_AGENT_CWD, u as hostService } from "./ccc-roots-GIJ3A_tw.js";
 import { _ as resolveInside, a as findSerenityRoot$1, c as matchBlacklist, d as readCccName$1, f as readCheapWorkerConfig, h as readTrajectorySkills, i as findGitRoot, l as pathInside, m as readSafeModeHiddenTools, n as SAFE_MODE_MARKER, o as isSafeModeOn, p as readExclusiveTools, r as classifyPath, s as loadSerenityConfig, t as DEFAULT_SERENITY_CONFIG_PATHS, u as readBlacklist } from "./ccc-B0ZGL9lx.js";
 import { A as localIdStamp, C as setActiveSessionInfo, D as isoLocal, E as useSession, O as localFileStamp, S as sessionsRoot, T as summarize, _ as namingTitleFor, a as pruneMissingBindings, b as resolveSessionByTitle, c as setBindingStore, d as clearActiveSessionInfo, f as createSession, g as listSessions, h as getActiveSessionInfo, i as listBoundSessionIds, k as localHuman, l as DEFAULT_SESSION_SCOPE, m as findSession, n as PLUGIN_SOURCE, o as readLastBound, p as extractSessionMdPathFromText, r as appendBound, s as resolveSessionTrajectoryLabel, t as ACC_MESSAGE_KIND, u as TRAJECTORY_ACTIONS, v as parseSessionContextFromEvents, w as showSession, x as sessionEvents$1, y as readActiveSessionMd } from "./message-source-B4P3Uw6D.js";
-import { a as readWeixinCredential, c as weixinInboundDir, d as LOCALSTORE_SCOPES, f as checkLocalstoreGitCompliance, g as runLocalStore, h as readStore, i as matchWeixinRoute, l as weixinSessionIdFor, m as readGitTrack, n as extractWeixinText, o as readWeixinSettings, p as localstorePath, r as hasVoiceItem, s as sanitizeFileName$1, t as extractWeixinMedia } from "./weixin-route-B9gU1YXz.js";
+import { a as readGitTrack, c as unsetEntry, i as localstorePath, l as writeEntry, n as checkLocalstoreGitCompliance, o as readStore, r as getEntry, s as runLocalStore, t as LOCALSTORE_SCOPES } from "./localstore-ops-DMs_ovHo.js";
 import { a as FACE_PORTS, c as MECHANISM_PORTS, d as registerSkiffSession$1, f as skiffRoleFor$1, h as ACC_VERSION, i as ACP_PORT, l as SKIFF_DEBUG_PORT, m as unregisterSkiffSession$1, n as readSimpleSettings, o as GATEWAY_PORT, p as skiffSessionInfo$1, r as registerSettingsSection, s as MAIN_WEB_PORT, u as WEIXIN_SEND_PORT } from "./settings-section-DGUQZo5j.js";
 import { a as readSkiffRoles, c as roleMsmWhitelist, d as systemPromptSource, f as trajectorySubset, i as isSkiffSessionId, l as roleToolWhitelist, n as buildSkiffBasePrompt, o as resolveRoleSystemPrompt, r as createRolePromptReader, s as resolveSkiffKind } from "./skiff-role-B615L9MV.js";
 import { REGISTERED_TOOLS } from "./invariant.js";
+import { a as readWeixinCredential, c as weixinInboundDir, i as matchWeixinRoute, l as weixinSessionIdFor, n as extractWeixinText, o as readWeixinSettings, r as hasVoiceItem, s as sanitizeFileName$1, t as extractWeixinMedia } from "./weixin-route-Aheyq3fN.js";
 import { a as markdownToPlainText, c as sendTyping, i as getUpdates, l as sniffImageExt, n as downloadMedia, o as sendFileMessage, r as getConfig, s as sendTextMessage, t as TypingStatus } from "./weixin-api-BrRcPiQs.js";
 import { createRequire } from "node:module";
 import z from "@deepseek-ai/schemastery";
@@ -15004,6 +15005,8 @@ const FILE_UPLOAD_PATH = "/serenity/file-upload";
 const CONFIG_PATH = "/serenity/config";
 const CCCS_PATH = "/serenity/cccs";
 const WEIXIN_PATH = "/serenity/weixin";
+/** 🔴 v1.59.2：ACP 账户台账（面板数据面；形状照 `/serenity/weixin`） */
+const ACP_PATH = "/serenity/acp";
 /** 图片落盘目录（CCC 根相对；S142 图片自动识别基础设施——粘贴图片落盘供 agent 经 CCC vlm MSM 自主处理） */
 const IMAGE_UPLOAD_DIR = "_tmp/images_from_user";
 const IMAGE_MEDIA_TYPES = /* @__PURE__ */ new Set([
@@ -15323,11 +15326,11 @@ function registerStatusApi(ctx, opts = {}) {
 						sendJson$3(res, 400, { error: chk.error });
 						return;
 					}
-					const { readWeixinSettings } = await import("./weixin-route-B9gU1YXz.js").then((n) => n.u);
+					const { readWeixinSettings } = await import("./weixin-route-Aheyq3fN.js").then((n) => n.u);
 					const { weixinBridgeStatus } = await Promise.resolve().then(() => weixin_bridge_exports);
 					const settings = readWeixinSettings(chk.root);
 					const bridge = weixinBridgeStatus().find((b) => b.ccc === chk.root);
-					const { readWeixinCredential } = await import("./weixin-route-B9gU1YXz.js").then((n) => n.u);
+					const { readWeixinCredential } = await import("./weixin-route-Aheyq3fN.js").then((n) => n.u);
 					const accounts = (settings.accounts ?? []).map((a) => ({
 						accountId: a.accountId,
 						name: a.name ?? void 0,
@@ -15359,7 +15362,7 @@ function registerStatusApi(ctx, opts = {}) {
 					const { fetchQRCode } = await import("./weixin-api-BrRcPiQs.js").then((n) => n.u);
 					const { randomUUID } = await import("node:crypto");
 					for (const [key, v] of weixinLogins) if (Date.now() - v.startedAt > WEIXIN_LOGIN_TTL_MS) weixinLogins.delete(key);
-					const { readWeixinSettings } = await import("./weixin-route-B9gU1YXz.js").then((n) => n.u);
+					const { readWeixinSettings } = await import("./weixin-route-Aheyq3fN.js").then((n) => n.u);
 					const qr = await fetchQRCode({ botType: readWeixinSettings(root).botType ?? void 0 });
 					const loginKey = randomUUID();
 					weixinLogins.set(loginKey, {
@@ -15380,7 +15383,7 @@ function registerStatusApi(ctx, opts = {}) {
 						sendJson$3(res, 400, { error: "missing accountId" });
 						return;
 					}
-					const { removeWeixinAccount } = await import("./weixin-route-B9gU1YXz.js").then((n) => n.u);
+					const { removeWeixinAccount } = await import("./weixin-route-Aheyq3fN.js").then((n) => n.u);
 					const { syncCccBridge } = await Promise.resolve().then(() => weixin_bridge_exports);
 					removeWeixinAccount(root, body.accountId);
 					syncCccBridge(ctx, root);
@@ -15393,7 +15396,7 @@ function registerStatusApi(ctx, opts = {}) {
 						sendJson$3(res, 400, { error: "invalid routes (expected [{user, role}, ...])" });
 						return;
 					}
-					const { saveWeixinRoutes } = await import("./weixin-route-B9gU1YXz.js").then((n) => n.u);
+					const { saveWeixinRoutes } = await import("./weixin-route-Aheyq3fN.js").then((n) => n.u);
 					const { readSkiffRoles } = await import("./skiff-role-B615L9MV.js").then((n) => n.u);
 					const roles = readSkiffRoles(root);
 					for (const r of routes) if (!roles.has(r.role)) {
@@ -15406,7 +15409,7 @@ function registerStatusApi(ctx, opts = {}) {
 				}
 				if (body.action === "set-enabled") {
 					const enabled = body.enabled === true;
-					const { readWeixinSettings, setWeixinEnabled } = await import("./weixin-route-B9gU1YXz.js").then((n) => n.u);
+					const { readWeixinSettings, setWeixinEnabled } = await import("./weixin-route-Aheyq3fN.js").then((n) => n.u);
 					const { syncCccBridge } = await Promise.resolve().then(() => weixin_bridge_exports);
 					const settings = readWeixinSettings(root);
 					if (enabled && (settings.accounts ?? []).length === 0) {
@@ -15450,7 +15453,7 @@ function registerStatusApi(ctx, opts = {}) {
 					return;
 				}
 				const { pollQRStatus } = await import("./weixin-api-BrRcPiQs.js").then((n) => n.u);
-				const { readWeixinSettings } = await import("./weixin-route-B9gU1YXz.js").then((n) => n.u);
+				const { readWeixinSettings } = await import("./weixin-route-Aheyq3fN.js").then((n) => n.u);
 				const settings = readWeixinSettings(login.root);
 				const status = await pollQRStatus({
 					baseUrl: void 0,
@@ -15465,7 +15468,7 @@ function registerStatusApi(ctx, opts = {}) {
 							});
 							return;
 						}
-						const { upsertWeixinAccount, writeWeixinCredential, nextWeixinAccountId } = await import("./weixin-route-B9gU1YXz.js").then((n) => n.u);
+						const { upsertWeixinAccount, writeWeixinCredential, nextWeixinAccountId } = await import("./weixin-route-Aheyq3fN.js").then((n) => n.u);
 						const { syncCccBridge } = await Promise.resolve().then(() => weixin_bridge_exports);
 						const accountId = nextWeixinAccountId(settings);
 						upsertWeixinAccount(login.root, {
@@ -15549,6 +15552,7 @@ function registerStatusApi(ctx, opts = {}) {
 			}
 		}
 	});
+	registerAcpAccountsApi(ctx);
 }
 /** 进行中的扫码登录（loginKey → 状态；进程内，5min 有效） */
 const weixinLogins = /* @__PURE__ */ new Map();
@@ -15569,6 +15573,99 @@ function requireCcc(root) {
 		root: serenityRoot
 	};
 }
+/** ACP 账户台账端点（面板专用；形状照 `/serenity/weixin`） */
+function registerAcpAccountsApi(ctx) {
+	ctx.webServer.register({
+		kind: "exact",
+		path: ACP_PATH,
+		handler: async (req, res) => {
+			try {
+				if (!requireWebUi(req, res, "ACP 账户配置仅限 WebUI（client 专用）")) return;
+				const url = new URL(req.url ?? "/", "http://127.0.0.1");
+				if (req.method === "GET") {
+					const chk = requireCcc(url.searchParams.get("ccc") ?? void 0);
+					if (!chk.ok) {
+						sendJson$3(res, 400, { error: chk.error });
+						return;
+					}
+					const { acpChannelStatus, listAcpRoots } = await Promise.resolve().then(() => acp_auth_exports);
+					const { listCccs } = await import("./ccc-roots-GIJ3A_tw.js").then((n) => n.a);
+					const st = acpChannelStatus(chk.root);
+					const all = (await listCccs(ctx)).map((e) => e.root);
+					sendJson$3(res, 200, {
+						channel: st.channel,
+						enabled: st.enabled,
+						accounts: st.accounts,
+						roots: listAcpRoots(all)
+					});
+					return;
+				}
+				if (req.method !== "POST") {
+					sendJson$3(res, 405, { error: "method not allowed" });
+					return;
+				}
+				const raw = await readBody$3(req, 65536);
+				const body = JSON.parse(raw);
+				const chk = requireCcc(body.ccc);
+				if (!chk.ok) {
+					sendJson$3(res, 400, { error: chk.error });
+					return;
+				}
+				const root = chk.root;
+				const acp = await Promise.resolve().then(() => acp_auth_exports);
+				if (body.action === "upsert") {
+					const account = acp.normalizeAcpAccount(body.account);
+					if (!account) {
+						sendJson$3(res, 400, { error: "invalid account (accountId 与 role 均必填)" });
+						return;
+					}
+					const { readSkiffRoles } = await import("./skiff-role-B615L9MV.js").then((n) => n.u);
+					const roles = readSkiffRoles(root);
+					if (!roles.has(account.role)) {
+						sendJson$3(res, 400, { error: `role "${account.role}" 不在该 CCC 的 skiff.roles 里（现有：${[...roles.keys()].join(", ") || "无"}）` });
+						return;
+					}
+					acp.upsertAcpAccount(root, account);
+					const created = acp.ensureAcpChannelTokens(root).includes(account.accountId);
+					sendJson$3(res, 200, {
+						saved: true,
+						accounts: acp.acpChannelStatus(root).accounts,
+						token: created ? acp.readAcpToken(root, account.accountId) : void 0
+					});
+					return;
+				}
+				if (body.action === "remove") {
+					const accountId = typeof body.accountId === "string" ? body.accountId.trim() : "";
+					if (accountId === "") {
+						sendJson$3(res, 400, { error: "missing accountId" });
+						return;
+					}
+					acp.removeAcpAccount(root, accountId);
+					sendJson$3(res, 200, {
+						removed: accountId,
+						accounts: acp.acpChannelStatus(root).accounts
+					});
+					return;
+				}
+				if (body.action === "rotate") {
+					const accountId = typeof body.accountId === "string" ? body.accountId.trim() : "";
+					if (accountId === "") {
+						sendJson$3(res, 400, { error: "missing accountId" });
+						return;
+					}
+					sendJson$3(res, 200, {
+						rotated: accountId,
+						token: acp.resetAcpToken(root, accountId)
+					});
+					return;
+				}
+				sendJson$3(res, 400, { error: `unknown action: ${String(body.action)}` });
+			} catch (err) {
+				sendJson$3(res, 400, { error: err?.message ?? String(err) });
+			}
+		}
+	});
+}
 //#endregion
 //#region src/voyage-page.ts
 const VOYAGE_PATH = "/serenity/voyage";
@@ -21816,9 +21913,566 @@ function registerWeixinSendApi(ctx) {
 	sync();
 }
 //#endregion
+//#region src/acp-auth.ts
+/**
+* acp-auth.ts — ACP 面的**认证 ＋ 身份**层（v1.59.0，owner 2026-10-17 令）
+*
+* ## 它解决什么
+*
+* owner 令（逐字）：「将微信桥升级为 IM 桥，每个 CCC 可以选择微信实现或 ACP 实现，
+* 微信实现保留不变向前兼容，**ACP 实现就可以暴露端口并绑定 skiff，并且要随即生成认证用的 token**」。
+*
+* 面 E（`acp-face.ts`）原本**无认证、无 CCC 归属、无角色** —— 本模块补上这三件：
+*   ① **token**：每 CCC 一枚，落**该 CCC 的 localstore**（credential scope）。
+*   ② **CCC 归属**：连接建立时由 token 反查 ⇒ **服务端权威**（不拿客户端自述的 `cwd` 当身份）。
+*   ③ **角色**：该 CCC 的 `im.acp.role` ⇒ 供装配层把 ACP 会话套上 skiff 角色。
+*
+* ## 🔴 架构决策：一面多 token，不是每 CCC 一个端口
+*
+* | | 甲：每 CCC 一个端口 | **乙：一面多 token** ← 选它 |
+* |---|---|---|
+* | 端口 | 随 CCC 数增长 | **固定 3200** |
+* | 身份来源 | 端口号 | **token（一一对应 CCC）** |
+*
+* **判据**：`token → CCC` 是一一对应，而 `cwd` 是**客户端可填的**。
+* ⇒ 用 token 定 CCC 比用 cwd 定 CCC 强：前者**服务端权威**，后者**客户端自述**。
+* ⇒ 连接一建立就知道"这是哪个 CCC"，**该连接的所有会话都归它**，角色绑定无需猜。
+* ⚠️ `cwd` 仍要校验（见 `cwdInsideRoot`）：防一枚 token 越权到别的 CCC。
+*
+* ## 🔴 为什么认证放在 WS upgrade 层，而不在 ACP 协议里
+*
+* `dsh-acp` 的 `authenticate()` **恒成功**且 `authMethods: []`（读其 `lib/index.js` 逐字），
+* 且它**不导出**可替换的认证缝 ⇒ 改协议层要重写它的接线（P0′ 已实测此路不通）。
+* 而**我们自己持有 HTTP server**（自持面）⇒ 在 `upgrade` **升级之前**校验，
+* 失败即 `401 ＋ destroy` ⇒ **连接根本进不来**。
+*
+* ## 边界
+*
+* 本模块**零 DSH 依赖**（只 `node:crypto` ／ `node:fs` ／ `node:path` 与本仓纯逻辑）⇒ 可独立单测。
+*/
+var acp_auth_exports = /* @__PURE__ */ __exportAll({
+	acpChannelEnabled: () => acpChannelEnabled,
+	acpChannelStatus: () => acpChannelStatus,
+	acpTokenKeyFor: () => acpTokenKeyFor,
+	cwdInsideRoot: () => cwdInsideRoot,
+	ensureAcpChannelTokens: () => ensureAcpChannelTokens,
+	ensureAcpToken: () => ensureAcpToken,
+	expandAcpAccounts: () => expandAcpAccounts,
+	extractToken: () => extractToken,
+	listAcpRoots: () => listAcpRoots,
+	normalizeAcpAccount: () => normalizeAcpAccount,
+	readAcpToken: () => readAcpToken,
+	readImSettings: () => readImSettings,
+	removeAcpAccount: () => removeAcpAccount,
+	resetAcpToken: () => resetAcpToken,
+	resolveTokenAccount: () => resolveTokenAccount,
+	safeEqual: () => safeEqual,
+	saveAcpAccounts: () => saveAcpAccounts,
+	tokenFingerprint: () => tokenFingerprint,
+	upsertAcpAccount: () => upsertAcpAccount
+});
+/** 多账户凭据键前缀（`IM_ACP_TOKEN_<ACCOUNT_ID>`；与微信桥 `WEIXIN_<ID>_<FIELD>` 同构） */
+const ACP_TOKEN_PREFIX = "IM_ACP_TOKEN_";
+/**
+* `accountId` → UPPER_SNAKE 片段（`agmente-phone` → `AGMENTE_PHONE`）。
+*
+* 🔴 **与 `weixin-route.ts` 的 `accountKeyPart` 逐字同规则** —— 刻意复制而非共享：
+*    两者属不同子域（微信 vs ACP），共享会让"改微信键规则"意外改掉 ACP 的既有凭据键，
+*    而凭据键**改一次就等于全体客户端掉线**。⇒ 用"同规则的两份"换"互不牵连"。
+*/
+function accountKeyPart(accountId) {
+	return accountId.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+}
+/** 该账户的凭据键（`IM_ACP_TOKEN_<ACCOUNT_ID>`）；`accountId` 必填 */
+function acpTokenKeyFor(accountId) {
+	return `${ACP_TOKEN_PREFIX}${accountKeyPart(accountId)}`;
+}
+/** token 字节数（32 B = 256 bit；hex 后 64 字符） */
+const TOKEN_BYTES = 32;
+/**
+* 该**账户**的 ACP token（**读**；不存在返回 null）。
+*
+* 🔴 **不自动生成** —— 生成是**写操作**，只在显式要求时做（`ensureAcpToken`）。
+*    读路径永远无副作用：否则每次判定都会改 localstore。
+*
+* @param accountId 账户键（必填 —— 凭据按账户分离，没有"CCC 默认 token"这回事）
+*/
+function readAcpToken(root, accountId) {
+	try {
+		const value = getEntry(root, "credential", acpTokenKeyFor(accountId));
+		return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* 生成（或返回既有）ACP token 并落该 CCC 的 localstore。
+*
+* ⚠️ **幂等**：已有 token 时**原样返回**（不轮换）—— 轮换会让在用的客户端立刻断线，
+*    必须是一次显式动作（`resetAcpToken`）。
+*
+* @param accountId 多账户时指明哪个账户；省略 ＝ 单账户简写键
+*/
+function ensureAcpToken(root, accountId) {
+	const existing = readAcpToken(root, accountId);
+	if (existing) return existing;
+	const token = randomBytes(TOKEN_BYTES).toString("hex");
+	writeEntry(root, "credential", acpTokenKeyFor(accountId), token);
+	return token;
+}
+/**
+* 轮换 token（显式动作；返回新值）。旧 token 立即失效。
+* @param accountId 账户键
+*/
+function resetAcpToken(root, accountId) {
+	const token = randomBytes(TOKEN_BYTES).toString("hex");
+	writeEntry(root, "credential", acpTokenKeyFor(accountId), token);
+	return token;
+}
+/**
+* 常时比较（防时序侧信道）。
+*
+* 🔴 两个长度不等时 `timingSafeEqual` **会抛** ⇒ 先比长度并立刻返回 false。
+*    ⚠️ 那一步本身**泄漏长度**（可接受：token 长度固定且公开）。
+*/
+function safeEqual(a, b) {
+	const bufA = Buffer.from(a, "utf8");
+	const bufB = Buffer.from(b, "utf8");
+	if (bufA.length !== bufB.length) return false;
+	return timingSafeEqual(bufA, bufB);
+}
+/** token 指纹（诊断面用；不可逆） */
+function tokenFingerprint(token) {
+	return createHash("sha256").update(token).digest("hex").slice(0, 12);
+}
+/**
+* 从一次 HTTP upgrade 请求里取出候选 token。
+*
+* 两种携带方式都认（客户端差异；Agmente 等用具名头，脚本常用查询串）：
+*   ① `Authorization: Bearer <t>`
+*   ② `?token=<t>`（查询串）
+*
+* @returns 取到的 token；两者都无 → null
+*/
+function extractToken(headers, url) {
+	const auth = headers["authorization"];
+	if (typeof auth === "string") {
+		const m = /^Bearer\s+(.+)$/i.exec(auth.trim());
+		if (m?.[1]) return m[1].trim();
+	}
+	if (typeof url === "string" && url !== "") try {
+		const q = new URL(url, "http://placeholder.invalid").searchParams.get("token");
+		if (q && q.trim() !== "") return q.trim();
+	} catch {}
+	return null;
+}
+/**
+* 把该 CCC 的配置**展开成账户列表**（读时现算，**无快照**）。
+*
+* 🔴 **`im.acp.accounts` 是必填项** —— 没有它就没有账户，**一个都认证不了**。
+*    刻意**不提供**"单账户简写"退回路径（v1.59.1）：那会多出一条永不生效的分支，
+*    而它的唯一作用是把"配置写错了"伪装成"用了简写"。
+*
+* 判据（三条都由调用方以 fail-closed 消费）：
+*  - `enabled !== false`（缺省 true）
+*  - `role` 非空（空 ⇒ 该账户**不出现**在列表里 ⇒ 必然登录失败）
+*  - token 存在（不存在 ⇒ 同样不出现）
+*
+* ⚠️ 本函数**纯读，绝不生成 token** —— 生成是写操作，归 `ensureAcpChannelTokens`。
+*    这样 upgrade 路径可以随时现算而不冒"每次连接都写 localstore"的风险。
+*/
+function expandAcpAccounts(root, paths = DEFAULT_SERENITY_CONFIG_PATHS) {
+	const im = readImSettings(root, paths);
+	if (im.channel !== "acp" || im.acp.enabled !== true) return [];
+	const declared = Array.isArray(im.acp.accounts) ? im.acp.accounts : [];
+	const out = [];
+	for (const a of declared) {
+		if (typeof a !== "object" || a === null) continue;
+		if (a.enabled === false) continue;
+		const accountId = typeof a.accountId === "string" ? a.accountId.trim() : "";
+		if (accountId === "") continue;
+		const role = typeof a.role === "string" ? a.role.trim() : "";
+		if (role === "") continue;
+		const token = readAcpToken(root, accountId);
+		if (!token) continue;
+		out.push({
+			root,
+			accountId,
+			tokenKey: acpTokenKeyFor(accountId),
+			token,
+			role
+		});
+	}
+	return out;
+}
+/**
+* **让配置里声明的账户都拥有 token**（写操作；幂等；由装配层与配置变更时调用）。
+*
+* 🔴 owner 令「**随即生成**认证用的 token」的落地点。与 v1.59.0 的差别：
+*    那时只在**启动**时跑一次 ⇒ 加一台设备要重启；现在**任何一次判定前都可以跑**，
+*    且撤账户后不会被"复活"（只对**当前声明里**的账户生成）。
+*
+* @returns 本次**新生成**的账户键列表（已存在的原样返回，不轮换）
+*/
+function ensureAcpChannelTokens(root, paths = DEFAULT_SERENITY_CONFIG_PATHS) {
+	const im = readImSettings(root, paths);
+	if (im.channel !== "acp" || im.acp.enabled !== true) return [];
+	const declared = Array.isArray(im.acp.accounts) ? im.acp.accounts : [];
+	const created = [];
+	for (const a of declared) {
+		if (typeof a !== "object" || a === null) continue;
+		if (a.enabled === false) continue;
+		const accountId = typeof a.accountId === "string" ? a.accountId.trim() : "";
+		if (accountId === "") continue;
+		try {
+			if (!readAcpToken(root, accountId)) {
+				ensureAcpToken(root, accountId);
+				created.push(accountId);
+			}
+		} catch {}
+	}
+	return created;
+}
+/**
+* 校验一枚候选 token，返回它归属的**账户**（未命中返回 null）。
+*
+* @param candidate 客户端出示的 token
+* @param roots 候选 CCC 根集合（由调用方枚举——本模块不认识"CCC 在哪"）
+*/
+function resolveTokenAccount(candidate, roots, paths = DEFAULT_SERENITY_CONFIG_PATHS) {
+	if (!candidate) return null;
+	for (const root of roots) for (const acct of expandAcpAccounts(root, paths)) if (safeEqual(candidate, acct.token)) return acct;
+	return null;
+}
+/**
+* 枚举**有可用 ACP 账户**的 CCC（供准入名单用）。
+*
+* 判据：`im.channel === 'acp'` ∧ `im.acp.enabled === true` ∧ **至少一个账户有 token 且配了角色**。
+* ⚠️ 缺一即不算（fail-closed：宁可连不上，不可放行一个半配置的通道）。
+*/
+function listAcpRoots(roots, paths = DEFAULT_SERENITY_CONFIG_PATHS) {
+	const out = [];
+	for (const root of roots) if (expandAcpAccounts(root, paths).length > 0) out.push(root);
+	return out;
+}
+/** 读该 CCC 的 `im` 段（未配置 ⇒ 归一缺省；永不 undefined） */
+function readImSettings(root, paths = DEFAULT_SERENITY_CONFIG_PATHS) {
+	try {
+		const im = loadSerenityConfig(root, paths).im;
+		if (!im || typeof im !== "object") return {
+			channel: "weixin",
+			acp: {}
+		};
+		return {
+			channel: im.channel === "acp" ? "acp" : "weixin",
+			acp: im.acp && typeof im.acp === "object" ? im.acp : {}
+		};
+	} catch {
+		return {
+			channel: "weixin",
+			acp: {}
+		};
+	}
+}
+/**
+* 该 CCC 是否启用 ACP 入站通道。
+*
+* 🔴 **两个条件都真才算**：`im.channel === 'acp'` **且** `im.acp.enabled === true`。
+*    为什么双键：`channel` 表达"选了哪条路"，`enabled` 表达"现在开不开" ⇒
+*    让 owner 能**选好 ACP 但暂时关着**（不用删配置），与既有各面的 `enabled` 范式一致。
+*/
+function acpChannelEnabled(root, paths = DEFAULT_SERENITY_CONFIG_PATHS) {
+	const im = readImSettings(root, paths);
+	return im.channel === "acp" && im.acp.enabled === true;
+}
+/**
+* 客户端 `session/new` 传来的 `cwd` 是否落在该 token 归属的 CCC 内。
+*
+* 🔴 **为什么必须校验**：token 定的是"哪个 CCC"，而 `cwd` 由**客户端**指定。
+*    不校验 ⇒ 一枚 CCC A 的 token 可以把会话开到 CCC B（越权读到另一个 CCC 的上下文）。
+*    这与 CCC 自身的路径围墙（P3）是同一条纪律，只是发生在**接入**这一层。
+*
+* 判据用 `relative()` 而非 `startsWith`（后者会把 `/a/bc` 误判为在 `/a/b` 内）。
+*/
+function cwdInsideRoot(cwd, root) {
+	if (!isAbsolute(cwd)) return false;
+	const rel = relative(resolve(root), resolve(cwd));
+	return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+}
+/** 该 CCC 的 ACP 通道对外**可见形态**（诊断面用；**绝不含 token 明文**） */
+function acpChannelStatus(root, paths = DEFAULT_SERENITY_CONFIG_PATHS) {
+	const im = readImSettings(root, paths);
+	const declared = Array.isArray(im.acp.accounts) ? im.acp.accounts : [];
+	const usable = new Set(expandAcpAccounts(root, paths).map((a) => a.accountId));
+	const accounts = [];
+	for (const a of declared) {
+		if (typeof a !== "object" || a === null) continue;
+		const accountId = typeof a.accountId === "string" ? a.accountId.trim() : "";
+		if (accountId === "") continue;
+		const role = typeof a.role === "string" && a.role.trim() !== "" ? a.role.trim() : null;
+		const token = readAcpToken(root, accountId);
+		const enabled = a.enabled !== false;
+		let blockedBy = null;
+		if (!enabled) blockedBy = "该账户 enabled=false";
+		else if (!role) blockedBy = "未配 role";
+		else if (!token) blockedBy = "尚无 token（保存配置后自动生成）";
+		accounts.push({
+			accountId,
+			name: typeof a.name === "string" && a.name.trim() !== "" ? a.name.trim() : null,
+			role,
+			enabled,
+			hasToken: token !== null,
+			tokenFingerprint: token ? tokenFingerprint(token) : null,
+			usable: usable.has(accountId),
+			blockedBy
+		});
+	}
+	return {
+		channel: im.channel,
+		enabled: acpChannelEnabled(root, paths),
+		accounts
+	};
+}
+/**
+* 读取 serenity.json 原文（不存在 → 空对象）。
+*
+* ⚠️ 与 `weixin-route.ts` 的同名函数**刻意各写一份**：两者写的是**不同段**
+* （`weixin` vs `im.acp.accounts`），共用一个会在"某天只想改其中一段"时
+* 意外把另一段也重写一遍。同规则两份 > 一个会互相牵连的共用件。
+*/
+function readRawConfig(root, paths = DEFAULT_SERENITY_CONFIG_PATHS) {
+	for (const candidate of paths) {
+		const p = resolve(root, candidate);
+		if (existsSync(p)) try {
+			const v = JSON.parse(readFileSync(p, "utf-8").replace(/^\uFEFF/, ""));
+			if (v && typeof v === "object" && !Array.isArray(v)) return v;
+		} catch {
+			return {};
+		}
+	}
+	return {};
+}
+/**
+* 写回 `im.acp.accounts`（保留文件里其余所有字段）。
+*
+* 🔴 **只碰这一个键**：`im.channel` / `im.acp.enabled` 归面板总开关与人工配置，
+*    本函数不越权改它们（否则"加一台设备"会顺手把通道开关也改了）。
+*/
+function saveAcpAccounts(root, accounts, paths = DEFAULT_SERENITY_CONFIG_PATHS) {
+	const target = resolve(root, paths[0] ?? ".opencode/serenity.json");
+	const raw = readRawConfig(root, paths);
+	const im = raw.im && typeof raw.im === "object" ? raw.im : {};
+	const acp = im.acp && typeof im.acp === "object" ? im.acp : {};
+	acp.accounts = accounts;
+	im.acp = acp;
+	raw.im = im;
+	const dir = resolve(target, "..");
+	if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+	writeFileSync(target, JSON.stringify(raw, null, 2) + "\n", "utf-8");
+	return accounts;
+}
+/**
+* 规范化一条账户声明（面板传入的任意形状 → 合法声明；非法 ⇒ null）。
+*
+* 🔴 返回类型里 `role` 是**必填**（不是 `ImAcpAccount` 的可选形态）——
+*    本函数的契约就是"要么给一个角色齐备的账户，要么给 null"。
+*    这样调用方**不必再判一次** `role` 有没有（那正是会漂的第二处判据）。
+*/
+function normalizeAcpAccount(input) {
+	if (typeof input !== "object" || input === null) return null;
+	const a = input;
+	const accountId = typeof a.accountId === "string" ? a.accountId.trim() : "";
+	if (accountId === "") return null;
+	const role = typeof a.role === "string" ? a.role.trim() : "";
+	if (role === "") return null;
+	const out = {
+		accountId,
+		role
+	};
+	if (typeof a.name === "string" && a.name.trim() !== "") out.name = a.name.trim();
+	if (a.enabled === false) out.enabled = false;
+	return out;
+}
+/** 增／改一条账户（按 accountId 定位；写入后返回全表） */
+function upsertAcpAccount(root, account, paths = DEFAULT_SERENITY_CONFIG_PATHS) {
+	const list = [...readImSettings(root, paths).acp.accounts ?? []];
+	const idx = list.findIndex((a) => a.accountId === account.accountId);
+	if (idx >= 0) list[idx] = {
+		...list[idx],
+		...account
+	};
+	else list.push(account);
+	return saveAcpAccounts(root, list, paths);
+}
+/** 删一条账户（**同时清掉它的 token**，避免留死键） */
+function removeAcpAccount(root, accountId, paths = DEFAULT_SERENITY_CONFIG_PATHS) {
+	const next = saveAcpAccounts(root, (readImSettings(root, paths).acp.accounts ?? []).filter((a) => a.accountId !== accountId), paths);
+	try {
+		unsetEntry(root, "credential", acpTokenKeyFor(accountId));
+	} catch {}
+	return next;
+}
+//#endregion
 //#region src/acp-face.ts
 /** 面名（面宿主幂等键；与 FACE_PORTS 的 id 同名，便于对账） */
 const FACE_ACP = "acp";
+/**
+* 校验一次 upgrade 请求（**只读**：不改任何状态）。
+*
+* 判据链（任一环失败即拒，fail-closed）：候选 token 缺失 ⇒ 不匹配任何 CCC ⇒
+* 该 CCC 未启用 ACP 通道 ⇒ 该 CCC 未配角色。最后一环尤其重要：**没有角色的 ACP 会话
+* 等于一个无身份、无约束的裸 agent** ⇒ 宁可连不上。
+*/
+function authorizeUpgrade(req) {
+	const candidate = extractToken(req.headers, req.url);
+	if (!candidate) return {
+		ok: false,
+		reason: "未携带 token（用 Authorization: Bearer <t> 或 ?token=<t>）"
+	};
+	const roots = knownAcpRoots();
+	if (roots.length === 0) return {
+		ok: false,
+		reason: "本机没有任何启用了 ACP 通道的 CCC"
+	};
+	const acct = resolveTokenAccount(candidate, roots);
+	if (!acct) return {
+		ok: false,
+		reason: "token 不匹配任何已声明账户的 ACP 通道"
+	};
+	const role = acct.role;
+	if (!role) return {
+		ok: false,
+		reason: `CCC（${acct.root}）账户 ${acct.accountId} 未配 im.acp.accounts[].role`
+	};
+	return {
+		ok: true,
+		root: acct.root,
+		role,
+		accountId: acct.accountId
+	};
+}
+/**
+* CCC 根候选的来源（**只要根，不判配置**）。
+*
+* 🔴 v1.59.1 分层变更：**这份名单是"本机有哪些 CCC"，不是"谁能连 ACP"**。
+*    "谁能连"由 `expandAcpAccounts` 现算（读各 CCC 的 serenity.json ＋ localstore）。
+*    ⇒ 缓存失效的代价从"配错权限"降为"多看/少看一个候选根"，**不再是安全问题**。
+*/
+let knownRoots = [];
+/**
+* 准入名单的现算入口（v1.59.1）。
+*
+* 顺序：**先用已知根**（免 async）→ 逐个 `expandAcpAccounts` 现读配置。
+* 未知根时退回上次枚举的结果（可能稍旧，但只影响"会不会去问它"，不影响是否放行）。
+*
+* ⚠️ 这里是**同步**的（upgrade 回调用）⇒ 不 await、不扫盘。
+*/
+function knownAcpRoots() {
+	return listAcpRoots(knownRoots);
+}
+/**
+* 刷新"本机有哪些 CCC"（async，枚举宿主三来源）。
+*
+* 🔴 **失败必须响亮**：v1.59.0 这里是 `void refresh(...)` 且没有 catch ——
+*    枚举失败会让名单清空 ⇒ **所有连接一律 401**，而现场只有一行 stdout 看不到的日志。
+*    这正是本轨记过的「调用没报错 ≠ 已验证」。
+*
+* @returns 本次枚举到的根数（0 ＝ 一个都没发现，日志会说为什么）
+*/
+async function refreshAcpRoots(ctx) {
+	try {
+		knownRoots = (await listCccs(ctx)).map((e) => e.root);
+		let created = 0;
+		for (const root of knownRoots) try {
+			created += ensureAcpChannelTokens(root).length;
+		} catch (err) {
+			console.warn(`[serenity-hooks] 面 E：为 CCC（${root}）生成 token 失败: ${String(err?.message ?? err)}`);
+		}
+		if (created > 0) console.log(`[serenity-hooks] ✓ 面 E：已为 ${created} 个 ACP 账户生成 token`);
+		return knownRoots.length;
+	} catch (err) {
+		knownRoots = [];
+		const msg = `面 E：CCC 枚举失败（准入名单将为空，所有连接会被拒）: ${String(err?.message ?? err)}`;
+		console.warn(`[serenity-hooks] ${msg}`);
+		state.lastErrors.push({
+			at: Date.now(),
+			applied: false,
+			error: msg
+		});
+		if (state.lastErrors.length > MAX_ERR_KEEP) state.lastErrors.shift();
+		return 0;
+	}
+}
+/**
+* 把**本连接归属的 CCC 角色**套到该连接创建的 agent 上（v1.59.0）。
+*
+* ## 🔴 为什么是"认领"而不是"直接挂"
+*
+* 理想形态是：在本连接的 scoped fiber 里监听 `session/created`，**只**收到本连接建的会话。
+* 但那条路依赖一个**我没有实测过的**引擎行为 —— cordis 的 `EventsService.dispatch()` 只在
+* **派发方设了 `Context.filter`** 时才按 ctx 过滤（读 `@deepseek-ai/cordis/src/events.ts`
+* 的 `.filter(hook => hook.global || !filter || filter.call(thisArg, hook.ctx))`）。
+* ⇒ 若宿主派发 `session/created` 时**没设**过滤器，本监听器会**收到全进程**的会话
+* （网页端、别的轨迹、别的连接），**套错角色**。
+*
+* 🔴 **D119 纪律**：不许照源码的"意图"断言引擎行为 ⇒ 本实现**不赌**那条语义，
+* 改用**认领制**（两条过滤都可以自证，不依赖 filter）：
+*   ① **cwd 必须落在本连接归属的 CCC 内**（token 已定 CCC ⇒ 越界会话直接跳过）；
+*   ② **同一会话只被认领一次**（`claimed` 集合；先到先得 ⇒ 不会被另一条连接的监听器抢走）。
+*
+* ⚠️ **残余风险（如实标注）**：若**同一 CCC** 同时有网页端会话与 ACP 会话在创建，
+*   本函数可能把网页端那个会话也认领了（两者 cwd 都在该 CCC 内）。⇒ 判据是"cwd ＋ 先到先得"，
+*   **不是"确属本连接"**。⚠️ **这一格必须由探针实测**（见 REBUILD-TODO 的待办）；
+*   未实测前**不得**声称"只套本连接的会话"。
+*
+* 失败语义：全程不抛（本面是可选面）——角色挂不上只记日志，不阻断 ACP 接线。
+*/
+function bindRoleToConnScopedAgent(scoped, root, roleName) {
+	try {
+		const role = readSkiffRoles(root).get(roleName);
+		if (!role) {
+			console.warn(`[serenity-hooks] 面 E：CCC（${root}）未定义 skiff 角色 "${roleName}" ⇒ 本连接不注入角色`);
+			return;
+		}
+		const rolePrompt = createRolePromptReader(root, role);
+		const claimed = /* @__PURE__ */ new Set();
+		const onCreated = (session) => {
+			try {
+				const id = session?.header?.id;
+				const cwd = session?.header?.cwd;
+				if (!id || !cwd) return;
+				if (claimed.has(id)) return;
+				if (!cwdInsideRoot(cwd, root)) return;
+				const target = resolveAgentById(scoped, id);
+				if (!target) return;
+				target.ctx.systemPrompt.section({
+					name: "serenity-skiff",
+					order: -60,
+					text: () => [buildSkiffBasePrompt(roleName, role), rolePrompt()].filter(Boolean).join("\n")
+				});
+				claimed.add(id);
+				console.log(`[serenity-hooks] ✓ 面 E：会话 ${id} 已绑定角色 "${roleName}"（CCC=${root}）`);
+			} catch (err) {
+				console.warn(`[serenity-hooks] 面 E：角色注入失败（不影响会话）: ${String(err?.message ?? err)}`);
+			}
+		};
+		for (const eventName of ["session/created", "agent/created"]) try {
+			scoped.on(eventName, onCreated);
+		} catch {}
+	} catch (err) {
+		console.warn(`[serenity-hooks] 面 E：角色绑定装配失败: ${String(err?.message ?? err)}`);
+	}
+}
+/** 按会话 id 取 live agent（只读；取不到返回 undefined） */
+function resolveAgentById(scoped, sessionId) {
+	try {
+		const agent = hostInjected(scoped, "agents")?.get?.(sessionId);
+		if (!agent?.ctx?.systemPrompt || typeof agent.ctx.systemPrompt.section !== "function") return void 0;
+		return agent;
+	} catch {
+		return;
+	}
+}
 /** 本面绑定的地址（取自集中端口表 —— **单一真相源**，不在本文件硬写） */
 const ACP_HOST = FACE_PORTS.acp.host ?? "127.0.0.1";
 /**
@@ -21846,13 +22500,51 @@ function acpFaceEnabled() {
 	return readSimpleSettings().acpFaceEnabled;
 }
 /**
+* 把客户端给的 `cwd` 归一化成宿主要求的**绝对路径**（v1.59.2）。
+*
+* ## 为什么需要
+* 宿主 `dsh-acp` 在每次 `session/new` 都有这一行（`lib/index.js` 逐字）：
+* ```js
+* if (!isAbsolute(params.cwd)) throw invalidParams(`cwd must be an absolute path: ${params.cwd}`)
+* ```
+* 而**连接归属哪个 CCC 已由 token 决定**（服务端权威）⇒ 让用户再手打一遍绝对路径
+* 是**同一个信息说两遍**，且那第二遍正是最容易打错的一遍。
+*
+* ## 规则（唯一一条）
+* **非绝对路径 ⇒ 一律解释为「本连接归属 CCC 的根」**。
+*
+* | 客户端填 | 送宿主 |
+* |---|---|
+* | `serenity` / `a` / `.` / 空 | `/…/home-serenity`（该 token 的 CCC 根） |
+* | `/…/home-serenity`（已绝对且在根内） | 原样 |
+* | `/…/home-serenity/sub` | 原样（仍在根内） |
+* | `/etc`（绝对但在根外） | **原样透传，交给 `cwdInsideRoot` 拒** |
+*
+* 🔴 **最后一行为什么不在这里直接拒**：越权判据必须**只有一处**（`cwdInsideRoot`，
+* 它也管着角色认领），在这里再判一次就是**两份会漂的实现**。归一化只负责"把非绝对变成绝对"。
+*
+* @param raw 客户端原样给的 `cwd`（可能是 `undefined`）
+* @param cccRoot 本连接归属的 CCC 根
+*/
+function normalizeClientCwd(raw, cccRoot) {
+	const value = typeof raw === "string" ? raw.trim() : "";
+	if (value === "" || !isAbsolute(value)) return cccRoot;
+	return value;
+}
+/**
 * 把一条裸 WS socket 适配成 ACP `Stream`。
 *
 * 🔴 与官方 `ndJsonStream` **同语义**：我们自己做「消息 ↔ 文本帧」的分帧（按行）。
 *    实测注意（P0′）：`dsh-acp` 写出的每条消息**自带换行**，客户端同样 ⇒ 按行切分即正确。
 *    ⚠️ **空行要丢**；**非 JSON 帧要容忍**（桥/客户端可能插入控制帧）。
+*
+* 🔴 v1.59.2：**入站消息在这里做一次 `cwd` 归一化**（见 {@link normalizeClientCwd}）。
+*    为什么是这里：`session/new` 与 `session/resume` 都带 `cwd`，而这是**唯一**能同时
+*    拦到两者、且属于我们自己的缝（再往下就进 `dsh-acp` 了，那里改了就是改宿主）。
+*
+* @param cccRoot 本连接归属的 CCC 根（token 反查所得）
 */
-function wsToAcpStream(ws, onWarn) {
+function wsToAcpStream(ws, onWarn, cccRoot) {
 	return {
 		readable: new ReadableStream({ start(controller) {
 			let buf = "";
@@ -21863,11 +22555,14 @@ function wsToAcpStream(ws, onWarn) {
 					const line = buf.slice(0, i);
 					buf = buf.slice(i + 1);
 					if (!line.trim()) continue;
+					let msg;
 					try {
-						controller.enqueue(JSON.parse(line));
+						msg = JSON.parse(line);
 					} catch {
 						onWarn(line.slice(0, 120));
+						continue;
 					}
+					controller.enqueue(normalizeInboundCwd(msg, cccRoot));
 				}
 			});
 			ws.on("close", () => {
@@ -21886,12 +22581,33 @@ function wsToAcpStream(ws, onWarn) {
 		} })
 	};
 }
+/**
+* 若这条消息带 `params.cwd`，就地归一化（**只动 `session/new` / `session/resume`**）。
+*
+* 🔴 判据 = **有 `params.cwd` 就归一化**，不按 method 白名单挑：
+*    带 `cwd` 的方法只有那两个，而白名单一旦漏项就会**静默退回旧行为**（最难查的一类）。
+*/
+function normalizeInboundCwd(msg, cccRoot) {
+	if (typeof msg !== "object" || msg === null) return msg;
+	const m = msg;
+	if (typeof m.params !== "object" || m.params === null) return msg;
+	if (!("cwd" in m.params)) return msg;
+	const normalized = normalizeClientCwd(m.params.cwd, cccRoot);
+	return {
+		...msg,
+		params: {
+			...m.params,
+			cwd: normalized
+		}
+	};
+}
 function newState() {
 	return {
 		handle: null,
 		wss: null,
 		connections: 0,
 		applied: 0,
+		rejected: 0,
 		lastErrors: [],
 		disposers: []
 	};
@@ -21938,16 +22654,41 @@ async function startAcpFace(ctx) {
 	local.handle = handle;
 	handle.server.on("upgrade", (req, socket, head) => {
 		local.connections += 1;
+		const verdict = authorizeUpgrade(req);
+		if (!verdict.ok) {
+			local.rejected += 1;
+			local.lastErrors.push({
+				at: Date.now(),
+				applied: false,
+				error: `auth: ${verdict.reason}`
+			});
+			if (local.lastErrors.length > MAX_ERR_KEEP) local.lastErrors.shift();
+			try {
+				socket.write(`HTTP/1.1 401 Unauthorized\r
+content-type: text/plain; charset=utf-8\r
+connection: close\r
+\r
+ACP 面：认证失败（${verdict.reason}）。请在该 CCC 的 localstore 生成并使用 IM_ACP_TOKEN。\n`);
+			} catch {}
+			try {
+				socket.destroy();
+			} catch {}
+			console.warn(`[serenity-hooks] ✗ 面 E：拒绝一条连接（${verdict.reason}）`);
+			return;
+		}
 		try {
 			wss.handleUpgrade(req, socket, head, (ws) => {
 				try {
+					const connRoot = verdict.root;
+					const connRole = verdict.role;
 					const stream = wsToAcpStream(ws, (line) => {
 						console.log(`[serenity-hooks] 面 E：丢弃一条非 JSON 帧（前 120 字）: ${line}`);
-					});
+					}, connRoot);
 					const fiber = ctx.plugin({
 						inject: ACP_REQUIRED_SERVICES,
 						apply: (scoped) => {
 							const sel = resolveAcpSelection(scoped);
+							bindRoleToConnScopedAgent(scoped, connRoot, connRole);
 							dshAcp.apply(scoped, {
 								stream,
 								provider: sel.provider,
@@ -22107,6 +22848,17 @@ function registerAcpFace(ctx) {
 			sync();
 		});
 	} catch {}
+	const refresh = () => {
+		refreshAcpRoots(ctx).then((n) => {
+			console.log(`[serenity-hooks] 面 E：CCC 候选根已枚举（${n} 个）`);
+		});
+	};
+	try {
+		ctx.on("settings/document-updated", (ns) => {
+			if (String(ns) === "serenity-hooks") refresh();
+		});
+	} catch {}
+	refresh();
 	sync();
 }
 //#endregion