@shgroup/dsh-serenity-hooks 1.49.0 → 1.50.1

package/lib/index.js

@@ -6,7 +6,7 @@ import { A as localIdStamp, C as setActiveSessionInfo, D as isoLocal, E as useSe
 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-CWMRa36W.js";
 import { a as unregisterSkiffSession$1, i as skiffSessionSnapshot$1, n as skiffRoleFor$1, o as ACC_VERSION, r as skiffSessionInfo$1, t as registerSkiffSession$1 } from "./skiff-registry-BjIX_KD1.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-KqQA6pkr.js";
-import { a as FACE_PORTS, c as MECHANISM_PORTS, i as ACP_HTTP_PORT, l as SKIFF_DEBUG_PORT, n as registerSettingsSection, o as GATEWAY_PORT, s as MAIN_WEB_PORT, t as readSimpleSettings, u as WEIXIN_SEND_PORT } from "./settings-section-B-KOyOYn.js";
+import { a as FACE_PORTS, c as MECHANISM_PORTS, i as ACP_HTTP_PORT, l as SKIFF_DEBUG_PORT, n as registerSettingsSection, o as GATEWAY_PORT, s as MAIN_WEB_PORT, t as readSimpleSettings, u as WEIXIN_SEND_PORT } from "./settings-section-EmaYsI-e.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-CtFYm53S.js";
 import z from "@deepseek-ai/schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";
@@ -18,7 +18,7 @@ import { promisify } from "node:util";
 import { platform as platform$1 } from "node:process";
 import { fileURLToPath } from "node:url";
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
-import { createHmac, randomBytes, randomUUID, scryptSync, timingSafeEqual } from "node:crypto";
+import { createHash, createHmac, randomBytes, randomUUID, scryptSync, timingSafeEqual } from "node:crypto";
 import { createServer, request } from "node:http";
 import * as zlib from "node:zlib";
 import { deriveEventMessage } from "@deepseek-ai/dsh-session";
@@ -1984,11 +1984,11 @@ const HANDYMAN_GUIDE = `# handyman — Scale-Up Usage Guide (guide)
 ## Two modes (v1.31.3; default = foreground)
 | | foreground (default) | background |
 |---|---|---|
-| What | one serial child agent runs the task ONCE and returns its final text | loop-validated worker: hard while-loop + random completion code |
-| Use when | you need exactly one result back now (per-case testers, single conversions) | long/unattended work needing anti-early-finish, resumability, or parallel jobs |
+| What | child agent(s) run the task ONCE and return their final text (jobs=[...] ⇒ parallel, cap 5) | loop-validated worker: hard while-loop + random completion code |
+| Use when | you need result(s) back now (per-case testers, single conversions, parallel fan-out) | long/unattended work needing anti-early-finish, resumability, or parallel jobs |
 | Loop / validation | none | stop-token is the ONLY completion condition; round cap (default 100); auto-restart (≤100) |
 | Progress file | none | AGENT_SESSIONS/handyman-<label>.md/.json (same label resumes) |
-| Parallel jobs | no (call once per task) | yes (jobs=[...], handyman.maxParallel default 10) |
+| Parallel jobs | **yes** — jobs=[{task,label?,model?},...], **cap 5 (fixed)** | yes (jobs=[...], handyman.maxParallel default 10) |
 | Mechanism | host delegation service ctx.subagents.start("spawn") + agentOptions | ctx.agents.create + internal while-loop |
 | Model source | CCC handyman.models whitelist (same for both) | same |
 
@@ -1997,7 +1997,7 @@ Before calling handyman, load eap (acc-eap skill) and design the "scale-up handy
 
 ### 1. Task decomposition (E↑ Explicit)
 - Split large tasks into explicit subtasks: each subtask defines goal / input / boundaries (what to do, what not to do) / acceptance criteria
-- Make dependencies explicit: dependent tasks run serially, independent ones can run in parallel (background mode)
+- Make dependencies explicit: dependent tasks run serially, independent ones can run in parallel (both modes)
 
 ### 2. Prompt design (handyman's task parameter)
 - task must be detailed, fixed, and EAP-compliant: clear goal, drawn boundaries, decidable acceptance criteria
@@ -2025,12 +2025,15 @@ Before calling handyman, load eap (acc-eap skill) and design the "scale-up handy
   (and "handyman.defaultModel") to a provider listed as available, or activate/register the provider on this
   machine. **Do not retry the same call unchanged** — it fails identically.
 
-### 4. Parallel strategy (background mode only)
-- Independent subtasks can run in parallel via handyman(mode="background", jobs=[...]): each job gets its own label + task + stop token + progress file
+### 4. Parallel strategy (both modes)
+- Independent subtasks can run in parallel:
+  · **foreground** — handyman(jobs=[{task,label?,model?},...]) ⇒ fan-out of custom-model subagents, **cap 5**,
+    results come back **in the order you passed them** (label is only a display name here; per-job "model" allowed)
+  · **background** — handyman(mode="background", jobs=[...]): each job gets its own label + task + stop token + progress file
 - Concurrency safety guaranteed: unique sessionId (handyman-<label>-<uuid>), progress files isolated per label
   (AGENT_SESSIONS/handyman-<label>.json) — same label resumes, different labels never interfere
-- Parallel cap: handyman.maxParallel (default 10 — cheap models are cheap)
-- Aggregation: after each parallel job produces progress, the main agent merges (or spawns one aggregation handyman)
+- Parallel cap: **foreground 5 (fixed)** / background handyman.maxParallel (default 10 — cheap models are cheap)
+- Aggregation: foreground returns all outputs in one result; background: after each parallel job produces progress, the main agent merges (or spawns one aggregation handyman)
 - For programmable pipeline/phase orchestration at scale, use the platform's workflow tool instead
 
 ## Completion criteria
@@ -3130,7 +3133,7 @@ function toolsBlock() {
 		"  container_git— git operations (status/commit/push/log)",
 		"  msm          — execute a registered CCC MSM: msm(name, args); partial name returns candidates; inspect=true shows usage",
 		"  praxis       — actionable theory injection: praxis (index) / praxis eap / praxis neat / praxis cce",
-		"  handyman     — delegate work to a worker agent on a CCC-whitelisted model; mode=\"foreground\" (default) = one serial child returns its final text; mode=\"background\" = loop-validated worker (completion code + round cap + restart + progress file), jobs=[] orchestrates parallel work",
+		"  handyman     — delegate work to a worker agent on a CCC-whitelisted model; mode=\"foreground\" (default) = child agent(s) run once and return their final text (jobs=[...] fans out in parallel, cap 5, per-job model); mode=\"background\" = loop-validated worker (completion code + round cap + restart + progress file), jobs=[] orchestrates parallel work",
 		"  localstore   — ACC local credential/config storage (CCC-root localstore.json; git policy localstore.gitTrack default deny)",
 		"  container_admin — container administration (the maintenance bay): role (Skiff roles: guide/validate/apply/list) / msm (register/deregister/check/guide/catalog/ccc-config) / config (view)",
 		"",
@@ -4455,6 +4458,33 @@ function parseJobs(raw) {
 	}
 	return jobs;
 }
+/**
+* 🔴 **foreground 并行上限 = 5**（owner 2026-09-27 具名令：「handyman foreground 能否允许并行，最大 5；
+* 就当是支持自定模型的 subagent 用了，急需」）。
+*
+* 为什么是**硬编码**而不是又一个配置键：owner 的原话就是"最大 5"（同 `REBUILD-TODO` 那次的裁决口径
+* —— 设定项能不加就不加，见 S142 的「可砍设定项」）。若将来真要调，再按具名令改成配置。
+*
+* 为什么 foreground 也要限流（而不是直接复用 `handyman.maxParallel` = 10）：**foreground 会占住主
+* agent 的这一轮**（调用方在等结果），并发越高越容易把宿主的并发面与用量推上去 ⇒ 前台给一个更紧的闸。
+*/
+const FOREGROUND_MAX_PARALLEL = 5;
+/** foreground 的 jobs 解析（与 background 的差别：**label 可选** —— 前台 label 只是显示名，不命名进度文件） */
+function parseForegroundJobs(raw) {
+	if (!Array.isArray(raw) || raw.length === 0) return null;
+	const jobs = [];
+	for (const item of raw) {
+		if (typeof item !== "object" || item === null) return null;
+		const rec = item;
+		if (typeof rec.task !== "string" || rec.task.trim() === "") return null;
+		jobs.push({
+			task: rec.task,
+			...typeof rec.label === "string" && rec.label !== "" ? { label: rec.label } : {},
+			...typeof rec.model === "string" && rec.model !== "" ? { model: rec.model } : {}
+		});
+	}
+	return jobs;
+}
 /** 拼接 SubagentResult.output（ContentBlock[]）中的文本块 */
 function subagentOutputText(output) {
 	if (!Array.isArray(output)) return "";
@@ -4678,11 +4708,11 @@ async function runHandymanJob(ctx, opts) {
 function createHandymanTool(ctx) {
 	return defineTool({
 		name: "handyman",
-		description: "The handyman (杂工): delegate work to a worker agent on a CCC-configured model. Two modes (v1.31.3).\nMode \"foreground\" (DEFAULT): one serial child agent runs the task once and returns its final text — no loop, no completion-code validation, no progress file; use it for one-shot serial delegation (e.g. per-case testers that just gather evidence). Usage: handyman(task, [label], [model]).\nMode \"background\": the loop-validated worker — internal hard while-loop whose ONLY completion condition is the worker echoing this round's random completion code (stop token, prevents low-intelligence models from finishing early), round cap (default 100, resumable), automatic restart on abnormal stop (≤100), progress file AGENT_SESSIONS/handyman-<label>.md/.json (same label resumes), and parallel jobs (handyman.maxParallel, default 10). Usage: handyman(mode=\"background\", task, label, [model]) or handyman(mode=\"background\", jobs=[{task,label,model?},...]).\nChoosing: need exactly one result back now → foreground; need anti-early-finish guarantees, resumability or parallel jobs → background.\nModel: only models whitelisted in .opencode/serenity.json \"handyman.models\" (missing config = error); default reads handyman.defaultModel. Both modes share the same whitelist and default.\nProvider check: the whitelist lives in the CCC (it travels with the repo) while provider adapters are registered per machine by the host — so before spawning, the provider of the resolved model is verified against the adapters present on THIS machine. If it is missing you get the available providers plus the exact fix (foreground: in `diagnostic`; background: thrown), never an opaque failure.\nRecursion: a worker's tool set excludes handyman itself (orchestration belongs to the main agent).\nGuide: handyman(guide=true) prints the scale-up usage guide.",
+		description: "The handyman (杂工): delegate work to a worker agent on a CCC-configured model. Two modes (v1.31.3).\nMode \"foreground\" (DEFAULT): one serial child agent runs the task once and returns its final text — no loop, no completion-code validation, no progress file; use it for one-shot serial delegation (e.g. per-case testers that just gather evidence). Usage: handyman(task, [label], [model]).\nMode \"background\": the loop-validated worker — internal hard while-loop whose ONLY completion condition is the worker echoing this round's random completion code (stop token, prevents low-intelligence models from finishing early), round cap (default 100, resumable), automatic restart on abnormal stop (≤100), progress file AGENT_SESSIONS/handyman-<label>.md/.json (same label resumes), and parallel jobs (handyman.maxParallel, default 10). Usage: handyman(mode=\"background\", task, label, [model]) or handyman(mode=\"background\", jobs=[{task,label,model?},...]).\nChoosing: need exactly one result back now → foreground; need anti-early-finish guarantees or resumability → background; need N results back now (parallel, per-job model) → foreground with jobs (cap 5).\nModel: only models whitelisted in .opencode/serenity.json \"handyman.models\" (missing config = error); default reads handyman.defaultModel. Both modes share the same whitelist and default.\nProvider check: the whitelist lives in the CCC (it travels with the repo) while provider adapters are registered per machine by the host — so before spawning, the provider of the resolved model is verified against the adapters present on THIS machine. If it is missing you get the available providers plus the exact fix (foreground: in `diagnostic`; background: thrown), never an opaque failure.\nRecursion: a worker's tool set excludes handyman itself (orchestration belongs to the main agent).\nGuide: handyman(guide=true) prints the scale-up usage guide.",
 		parameters: {
 			mode: {
 				type: "string",
-				description: "Delegation mode: \"foreground\" (default — one serial child, returns its final text) or \"background\" (loop-validated worker with completion-code check, round cap, auto-restart, progress file, parallel jobs)"
+				description: "Delegation mode: \"foreground\" (default — child agent(s) run once and return their final text; accepts `jobs` for parallel fan-out, cap 5) or \"background\" (loop-validated worker with completion-code check, round cap, auto-restart, progress file, parallel jobs)"
 			},
 			task: {
 				type: "string",
@@ -4702,7 +4732,7 @@ function createHandymanTool(ctx) {
 			},
 			jobs: {
 				type: "array",
-				description: "Multi-job orchestration (workflow capability): [{task, label, model?}, ...] — runs jobs in parallel (cap handyman.maxParallel, default 10)",
+				description: "Multi-job orchestration (workflow capability): [{task, label?, model?}, ...] — runs jobs in parallel. Cap: foreground 5 (fixed) / background handyman.maxParallel (default 10). Results keep the order you passed them in.",
 				items: {
 					type: "object",
 					properties: {
@@ -4732,8 +4762,31 @@ function createHandymanTool(ctx) {
 			const mode = args.mode === "background" ? "background" : "foreground";
 			if (args.mode !== void 0 && args.mode !== "background" && args.mode !== "foreground") throw new Error("handyman: mode must be \"foreground\" (default) or \"background\"");
 			if (mode === "foreground") {
+				if (args.jobs !== void 0) {
+					const jobs = parseForegroundJobs(args.jobs);
+					if (jobs === null) throw new Error("handyman foreground: jobs must be [{task, label?, model?}, ...] (every job requires a non-empty task)");
+					if (jobs.length > FOREGROUND_MAX_PARALLEL) throw new Error(`handyman foreground: ${jobs.length} jobs exceed the foreground parallel cap ${FOREGROUND_MAX_PARALLEL} (split into batches, or use mode="background" whose cap is handyman.maxParallel)`);
+					const results = await Promise.all(jobs.map((job) => runForegroundJob(ctx, {
+						task: job.task,
+						...job.label === void 0 ? {} : { label: job.label },
+						model: job.model ?? (typeof args.model === "string" && args.model !== "" ? args.model : hc.defaultModel),
+						models: hc.models,
+						parent: exec.agent,
+						signal: exec.signal
+					})));
+					const done = results.every((r) => r.done);
+					return {
+						mode: "foreground",
+						done,
+						jobs: results,
+						usage: {
+							how: `foreground parallel mode starts ${results.length} child agents at once through the host delegation service (ctx.subagents.start "spawn"), awaits all of them, and returns each child's final text. No loop, no completion-code validation, no progress file. Cap = ${FOREGROUND_MAX_PARALLEL}.`,
+							model: "restricted to the CCC whitelist handyman.models; per-job model overrides the call-level model; default reads handyman.defaultModel",
+							next: done ? "All children completed; use each job's output directly (results are in the same order as the jobs you passed)" : "Some children did not complete — inspect each job's diagnostic/output (results keep the order you passed); for anti-early-finish guarantees use mode=\"background\""
+						}
+					};
+				}
 				if (typeof args.task !== "string" || args.task.trim() === "") throw new Error("handyman foreground: task is required (and must be self-contained — the child does not share this conversation)");
-				if (args.jobs !== void 0) throw new Error("handyman foreground: jobs is background-only — call foreground once per task, or use mode=\"background\" for parallel jobs");
 				const model = typeof args.model === "string" && args.model !== "" ? args.model : hc.defaultModel;
 				const res = await runForegroundJob(ctx, {
 					task: args.task,
@@ -9836,12 +9889,64 @@ function registerCompactRetention(ctx, opts = {}) {
 * WebUI 停靠栏的数据源：ACC 版本 / CCC 根 / safe-mode 状态 / 黑名单 / keeper 阈值 / handyman 模型。
 * setSafeMode 直接读写 .serenity-safe-on 标记（守卫实时读取，写即生效）。
 */
+/** 宿主包名 —— 从运行入口反推包根时的**身份核对**用（见 {@link dshVersionFromEntry}） */
+const HOST_PACKAGE_NAME = "@deepseek-ai/dsh";
+/** 上溯层数上限：入口脚本在包内的深度是 `lib/`（1 层）或 `lib/x/y/`（≤3 层）⇒ 6 层足够，且**保证有界** */
+const MAX_ENTRY_ASCENT = 6;
+/**
+* 🔴 **布局无关档**：从**正在跑的那个入口脚本**反推宿主包根，读它的 `version`。
+*
+* 为什么必须补这一档（R↓：一处**静默失效**的实际缺陷；2026-09-28 docker bench 实测）：
+* 下面那条静态候选链（{@link readDshVersion} 的 ②）是**猜安装位置**——`npm_config_prefix` /
+* `APPDATA\npm` / `~/.npm-global`。一旦宿主装在**别处**（典型 = 容器镜像里的
+* `/usr/local/lib/node_modules/@deepseek-ai/dsh`），**三个候选全不中** ⇒ 返回 `null`
+* ⇒ `checkHostVersion(null)` 只给一条 **`required: false`** 的 issue ⇒ 报告 `ok` 仍为 `true`
+* ⇒ **版本门完全静默**（bench 逐字：`host contract degraded (1 optional): host version unknown`）。
+* ⚠️ 这类坏法**比"偶尔报警"更危险**：一条**永远为假**的判据看起来像"没报警 = 没问题"。
+*
+* 而"我们正跑在哪个宿主里"**本来就有直接证据**：`process.argv[1]`（= 启动本进程的那个脚本）。
+* 三条判据要点（每条都对应一个实测过的坑）：
+*  ① **先 `realpath`** —— 全局安装的 `dsh` 是**符号链接**（`/usr/local/bin/dsh` → `…/@deepseek-ai/dsh/lib/bin.js`），
+*     而 Node 的 `argv[1]` **保留调用路径、不解析符号链接** ⇒ 不 realpath 就永远上溯不到包根。
+*  ② **核对包名**（`name === '@deepseek-ai/dsh'`）—— 否则在 vitest / npx 等入口下会误取**别人的**
+*     `package.json`（这是本档**唯一**的假阳性来源）。
+*  ③ **上溯有界**（{@link MAX_ENTRY_ASCENT}）—— 不设界的话，一个不在任何 dsh 包内的入口会一路爬到文件系统根。
+*
+* @param entry `process.argv[1]`（单测直接注入，无需替身）
+*/
+function dshVersionFromEntry(entry) {
+	if (typeof entry !== "string" || entry === "") return null;
+	let dir;
+	try {
+		const real = realpathSync(entry);
+		dir = statSync(real).isDirectory() ? real : dirname(real);
+	} catch {
+		return null;
+	}
+	for (let i = 0; i < MAX_ENTRY_ASCENT; i++) {
+		try {
+			const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8"));
+			if (pkg.name === HOST_PACKAGE_NAME && typeof pkg.version === "string") return pkg.version;
+		} catch {}
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return null;
+}
 /**
 * 读取已安装 DSH CLI 版本；读不到返回 null。
-* 跨平台（Windows 审计问题 13）：Windows npm 全局装在 %APPDATA%\npm（非 ~/.npm-global）——
-* 依次尝试 npm_config_prefix / APPDATA\npm / ~/.npm-global。
+*
+* **两档，顺序有理由**：
+*  ① 🔴 **布局无关档**（{@link dshVersionFromEntry}）= **正在跑的就是它** —— 直接证据优先于"猜安装位置"。
+*  ② **静态候选链**（跨平台历史档，保留）：`npm_config_prefix` ／ `APPDATA\npm` ／ `~/.npm-global`
+*     （Windows npm 全局装在 `%APPDATA%\npm`，见审计问题 13）。
+*     ⚠️ 保留它是因为**本进程不一定是 dsh CLI**（单测、嵌入式、将来别的宿主进程）——
+*     那时"本机装了哪个版本"仍需一个答案，只是证据等级更低。
 */
 function readDshVersion() {
+	const fromEntry = dshVersionFromEntry(process.argv[1]);
+	if (fromEntry !== null) return fromEntry;
 	const candidates = [];
 	if (process.env.npm_config_prefix) candidates.push(join(process.env.npm_config_prefix, "lib", "node_modules", "@deepseek-ai", "dsh"));
 	if (process.env.APPDATA) candidates.push(join(process.env.APPDATA, "npm", "node_modules", "@deepseek-ai", "dsh"));
@@ -10249,7 +10354,7 @@ function registerStatusApi(ctx, opts = {}) {
 					return;
 				}
 				const settings = readAdvancedSettings();
-				const { readSimpleSettings } = await import("./settings-section-B-KOyOYn.js").then((n) => n.r);
+				const { readSimpleSettings } = await import("./settings-section-EmaYsI-e.js").then((n) => n.r);
 				const simple = readSimpleSettings();
 				const allowed = settings.publicAsk.allowed;
 				const port = simple.acpHttpPort ?? ACP_HTTP_PORT;
@@ -10964,12 +11069,43 @@ const HOST_SERVICES = [
 		required: false
 	}
 ];
-/** dsp 被验证过的宿主版本范围（与 package.json peerDependencies 同源，单一真相源） */
-const REQUIRED_HOST_RANGE = "^0.1.7-rc.1";
-/** 范围 floor：剥掉 caret/比较前缀（`^0.1.7-rc.1` → `0.1.7-rc.1`），供 {@link checkHostVersion} 使用 */
-const REQUIRED_HOST_FLOOR = REQUIRED_HOST_RANGE.replace(/^[\^~>=<\s]+/, "");
-/** 范围 ceiling：`^0.1.x` 的上界 = `<0.2.0`（显式常量，见 {@link checkHostVersion} 注释） */
-const REQUIRED_HOST_CEILING = "0.2.0";
+/**
+* dsp **被验证过的宿主版本档**（单一真相源）—— 每档 = 一个半开区间 `[floor, ceiling)`。
+*
+* 🔴 为什么是"档"而不是一条 caret 范围（R↓：2026-09-28 0.2.0-rc.1 适配轮实测得出）：
+*  - **宿主门的判据是真 semver**（`@deepseek-ai/dsh-app-boot:evaluatePluginCompatibility`
+*    = `semver.satisfies(runtime, range, { includePrerelease: true })`）⇒ **它支持 `||` 联合范围**；
+*  - 而 **dsp 这边是手写比较器**（{@link compareSemver}），**不实现 semver 的 range 语义**：
+*    旧写法"用正则从 `REQUIRED_HOST_RANGE` 剥前缀取 floor"在**联合范围上会取到垃圾**
+*    （`^0.1.7-rc.1 || ^0.2.0-rc.1` 的预发布捕获组 `(.*)` 会**吞掉 `||` 之后整段**）
+*    ⇒ 判定**变瞎**（既非"通过"也非"低于下限"，而是不可解释的值）。
+*  ⇒ 故**档表是唯一被验证的真相**：`REQUIRED_HOST_RANGE`（给宿主门看的串）与
+*    `checkHostVersion`（给自己的手写比较器）**都从它派生**，两者不可能互相漂移。
+*
+* 🔴 两档的由来（**实测，非推断**；判据表见插件仓 `docs/dsh-0.2.0-rc.1-adaptation-plan.md` §7.4）：
+*  - `^0.1.7-rc.1` 在 `0.2.0-rc.1` 上被宿主**整包拒绝 ＋ 回滚**
+*    （逐字 `installation rejected: … incompatible with dsh 0.2.0-rc.1` ＋ `restored package.json, …`）；
+*  - 单档 `^0.2.0-rc.1` 会**同样硬拒本机正在跑的 `0.1.7-rc.2`**
+*    ⇒ 发布后 deploy 必须先升宿主，**而升级会打断本容器**；
+*  - ⇒ 双档是**唯一不把本机宿主堵死的写法**（两档在真 semver 下均 PASS）。
+* 档上界取 `<0.2.0` / `<0.3.0`（即 `^0.2.0-rc.1` 的 caret 上界）：第二档同时覆盖
+* `0.2.0` 正式版与后续 `0.2.0-rc.N`。
+*/
+const VERIFIED_HOST_BANDS = [{
+	floor: "0.1.7-rc.1",
+	ceiling: "0.2.0"
+}, {
+	floor: "0.2.0-rc.1",
+	ceiling: "0.3.0"
+}];
+/**
+* 与 `package.json` 的 `peerDependencies` **逐字同串**的宿主版本范围（由 {@link VERIFIED_HOST_BANDS} 派生）。
+*
+* 🔴 这个字符串**就是**宿主门（`evaluatePluginCompatibility`）拿去跑 `semver.satisfies` 的那个串
+* ⇒ 它与档表**必须一致**（"声明 union、判定单档"是一种自相矛盾）。
+* 一致性由 `tests/host-contract.test.ts` 的**跨文件对账用例**钉住（读 package.json 逐字比对）。
+*/
+const REQUIRED_HOST_RANGE = VERIFIED_HOST_BANDS.map((b) => `^${b.floor}`).join(" || ");
 /** 最小 semver 比较（无依赖）：返回 -1 / 0 / 1；解析失败返回 null */
 function compareSemver(a, b) {
 	const parse = (v) => {
@@ -10994,37 +11130,54 @@ function compareSemver(a, b) {
 	return ra < rb ? -1 : 1;
 }
 /**
-* 宿主版本是否落在 dsp 被验证的范围（`REQUIRED_HOST_RANGE`）。
+* 宿主版本是否落在 dsp **被验证过的档**（{@link VERIFIED_HOST_BANDS}）之内。
 * 无版本信息 → 视为未知（ok=false，detail 说明），不猜测。
 *
-* floor/ceiling **从 `REQUIRED_HOST_RANGE` 派生**（v1.31.6，0.1.5-rc.1 适配轮）：
-* 此前 floor 是独立硬编码字面量——改 `REQUIRED_HOST_RANGE` 而忘改 floor 会造出
-* "常量说 0.1.5、判定用 0.1.2" 的双真相源。ceiling 无法从 caret 语义机械派生（手写比较器
-* 不实现 semver 的 caret 规则），故保留显式常量并在此声明其含义。
+* 🔴 **逐档判**（v1.50.x，0.2.0-rc.1 适配轮）：判据 = "∃ 档：`version >= floor ∧ version < ceiling`"。
+* 曾经的做法是"从 `REQUIRED_HOST_RANGE` 剥前缀取一个 floor ＋ 一个显式 ceiling"——
+* **单档假设一旦不成立（改联合范围），那个正则就会取到垃圾**（详见 {@link VERIFIED_HOST_BANDS}
+* 的注释）⇒ 故本函数**只读档表**，不再从范围串反推。
+* ⚠️ 手写比较器**不实现 semver 的 range 语义**（本条只做"区间内/外"），这也是必须逐档判的原因。
 */
 function checkHostVersion(version) {
 	if (version === null) return {
 		ok: false,
 		detail: `host version unknown (required ${REQUIRED_HOST_RANGE})`
 	};
-	const floor = compareSemver(version, REQUIRED_HOST_FLOOR);
-	const ceiling = compareSemver(version, REQUIRED_HOST_CEILING);
-	if (floor === null || ceiling === null) return {
+	let matched = false;
+	let belowEveryFloor = true;
+	let unparseable = false;
+	for (const band of VERIFIED_HOST_BANDS) {
+		const floor = compareSemver(version, band.floor);
+		const ceiling = compareSemver(version, band.ceiling);
+		if (floor === null || ceiling === null) {
+			unparseable = true;
+			break;
+		}
+		if (floor >= 0) {
+			belowEveryFloor = false;
+			if (ceiling < 0) {
+				matched = true;
+				break;
+			}
+		}
+	}
+	if (unparseable) return {
 		ok: false,
 		detail: `host version "${version}" not parseable (required ${REQUIRED_HOST_RANGE})`
 	};
-	if (floor < 0) return {
+	if (matched) return {
+		ok: true,
+		detail: `host ${version} within ${REQUIRED_HOST_RANGE}`
+	};
+	if (belowEveryFloor) return {
 		ok: false,
 		detail: `host ${version} is below the verified floor (required ${REQUIRED_HOST_RANGE})`
 	};
-	if (ceiling >= 0) return {
+	return {
 		ok: false,
 		detail: `host ${version} is outside the verified range (required ${REQUIRED_HOST_RANGE})`
 	};
-	return {
-		ok: true,
-		detail: `host ${version} within ${REQUIRED_HOST_RANGE}`
-	};
 }
 /** 结构化读取宿主服务（lazy → ctx.get；injected → 直接属性，属性缺失再试 ctx.get） */
 function readService(ctx, name, access) {
@@ -15848,6 +16001,257 @@ qInput.focus()
 </body>
 </html>`;
 }
+//#endregion
+//#region src/human-channel.ts
+/**
+* human-channel.ts — 人机信道的**机制层**（机器级；2026-09-26 owner 定案 ⇒ 方案 §2.6）
+*
+* ## 为什么单独一个模块（方案 §5-12）
+* 今天"机制"与"渠道实现"混在 `weixin-bridge.ts` 里。P0-2 要立的这条不变量是**机器级**的 ——
+* 它**跨 CCC**、且与"微信"无关（飞书桥／邮件桥同样要守）⇒ 抽到这里；`weixin-bridge` 只做接线。
+*
+* ## 本模块唯一的不变量
+* 🔴 **一账号一 poller**：同一个**账号**（= 同一个 bot 身份）在**同一时刻只有一个轮询者**。
+* 今天的形态是"**按 CCC 起桥**"（`for entry of listCccs ⇒ syncCccBridge`）⇒ 若两个 CCC 各自
+* 配了**同一个**微信账号（同一份凭据），就会**两处轮询同一条消息** ⇒ 重复投递 ＋ 重复落盘
+* （方案 §3.6 的"顺带解决"就是这一条）。
+*
+* ## 🔴 账号的"身份"是什么（本模块最容易写错的一处）
+* **不是 `accountId`** —— 它是**每 CCC 的本地标签**（今天两处都叫 `wechat-1` 完全可能是两个
+* 不同的微信号）。跨 CCC 能辨认同一个 bot 的**唯一**依据是**凭据内容**（token）。
+* ⇒ `accountIdentity()` 以 **token 的哈希**为身份；**没有 token** 时才退回
+* `ccc:<root>|<accountId>`（那时身份里带了 root ⇒ 跨 CCC 不可能撞车，也就不会误判成"同一账号"）。
+*
+* ## 边界
+* 本模块做三件事（**都属机制**，与"哪个渠道"无关）：
+*  ① **归属判定**（P0-2：谁能起 poller、谁被谁占着）—— 见下 §归属判定
+*  ② **订阅表查询 ＋ 入站路由决策**（P0-3：`(账号, 用户) → (CCC, 角色)`）—— 见 §订阅表
+*  ③ **机器级留痕**（P0-3：未投递 ／ 目标不存在 ／ 表残缺）—— 见 §留痕。
+*     🔴 为什么这些必须机器级：它们**没有目标 CCC** ⇒ 落进任何 CCC 都是"编一个"目标。
+* **不碰**：轮询循环、凭据解析、会话投递 —— 那些是**渠道实现**，留在 `weixin-bridge.ts`。
+* ⇒ 本模块**零 DSH 依赖**（只有 `node:crypto` ／ `node:fs`），可独立单测。
+*/
+/**
+* 算账号的**机器级身份**。
+*
+* - 有 token ⇒ `token:<sha256 前 16 位>`（**跨 CCC 可辨同一 bot**；不落原文，日志/状态面可安全展示）
+* - 无 token（未扫码绑定等）⇒ `ccc:<root>|<accountId>`（**退化为每 CCC 唯一** ⇒ 不会误判撞车）
+* @param root CCC 根
+* @param accountId 该 CCC 本地账号键
+* @param token 凭据 token（可缺省）
+*/
+function accountIdentity(root, accountId, token) {
+	const t = (token ?? "").trim();
+	if (t !== "") return `token:${createHash("sha256").update(t).digest("hex").slice(0, 16)}`;
+	return `ccc:${root}|${accountId}`;
+}
+/**
+* 归属判定（**纯函数**：不改任何状态）。
+*
+* 规则三条（**同批**与**跨批**刻意用不同判据，别合并——合并会放过"同一 CCC 里两个本地键绑同一个 bot"）：
+*  ① **同批**内同身份重复 ⇒ **一律跳过**（后者）—— 与是哪个 CCC 无关。实例：某 CCC 的账号表里
+*     `wechat-1` 与 `wechat-2` 绑的是同一个 bot ⇒ 若豁免"自己"，它就会为同一个 bot 起**两个**循环。
+*  ② 身份已被**别的** CCC 占着 ⇒ 跳过（记 `ownedBy`）—— 这就是"一账号一 poller"的主判据。
+*  ③ 身份被**自己**占着 ⇒ **照常 claim**（热重建语义：`syncCccBridge` 会先释放自己的旧归属再重新
+*     claim；把"自己占着"也判成冲突会让**配置一变就再也起不来**）。
+* @param requests 本批请求（顺序即优先级：先到先得）
+* @param owners 当前归属表（`pollerOwners()`）
+*/
+function planPollerClaims(requests, owners) {
+	const claims = [];
+	const skipped = [];
+	/** 本批占位（判据 ①：不带"自己"豁免） */
+	const batch = /* @__PURE__ */ new Map();
+	for (const request of requests) {
+		const inBatch = batch.get(request.identity);
+		if (inBatch) {
+			skipped.push({
+				request,
+				ownedBy: inBatch
+			});
+			continue;
+		}
+		const existing = owners.get(request.identity);
+		if (existing && existing.root !== request.root) {
+			skipped.push({
+				request,
+				ownedBy: existing
+			});
+			continue;
+		}
+		batch.set(request.identity, {
+			root: request.root,
+			accountId: request.accountId
+		});
+		claims.push(request);
+	}
+	return {
+		claims,
+		skipped
+	};
+}
+const owners = /* @__PURE__ */ new Map();
+/** 当前归属表（只读视图；供判定与状态面用） */
+function pollerOwners() {
+	return owners;
+}
+/** 落实一批 claim（调用方在**真正起了 poller 之后**调它） */
+function commitPollerClaims(plan) {
+	for (const claim of plan.claims) owners.set(claim.identity, {
+		root: claim.root,
+		accountId: claim.accountId
+	});
+}
+/**
+* 释放某 CCC 的**全部**归属（热重建/停止时先调它，再重新 claim）。
+*
+* 🔴 为什么"先全放再 claim"是安全的：`syncCccBridge` 内这一段是**同步**的（中间没有 await）
+* ⇒ 不存在"刚放开就被别人抢走"的窗口；且**别人**在这次调用里本来就抢不到（它的请求会被
+* 判成"被 <本 CCC> 占着"而跳过）⇒ 归属**粘在本 CCC**，不会在两个 CCC 之间来回漂。
+* @param root 要释放的 CCC 根
+* @returns 被释放的身份数（日志/判据用）
+*/
+function releasePollersOf(root) {
+	let released = 0;
+	for (const [identity, owner] of [...owners]) if (owner.root === root) {
+		owners.delete(identity);
+		released++;
+	}
+	return released;
+}
+/** 清空归属表（插件 dispose） */
+function releaseAllPollers() {
+	owners.clear();
+}
+/** 订阅行的四个字段（顺序即报错里的字段顺序） */
+const SUBSCRIPTION_FIELDS = [
+	"account",
+	"user",
+	"ccc",
+	"role"
+];
+/**
+* 订阅表查询（**纯函数**）。
+*
+* 匹配两段式（**刻意对齐**旧 `matchWeixinRoute` 的 exact → `*` 兜底）：
+*  ① `account` **精确** ∧ `user` **精确**
+*  ② `account` **精确** ∧ `user === '*'`（通配兜底）
+* 🔴 `account` **不设通配**：它是机器级账号的**显式身份**（表里写的就是账号 id）；
+*   给账号也开 `*` 会让"这条订阅到底覆盖哪个 bot"变得不可读。
+* 🔴 `user` 保留 `*`：这是**有意的**——存量 CCC 级 `routes` 用的就是 `{user:'*'}`，
+*   迁移（P0-4）要能**逐字平移**它，否则"迁移"会悄悄改变行为。
+*
+* @param subscriptions 机器级订阅表（`readSimpleSettings().humanChannel.subscriptions`）
+* @param account 收到的**账号 id**（poller 身份；不是 token）
+* @param user 发信人 id
+*/
+function lookupSubscription(subscriptions, account, user) {
+	const defects = [];
+	const usable = [];
+	subscriptions.forEach((row, index) => {
+		const raw = {
+			account: row?.account,
+			user: row?.user,
+			ccc: row?.ccc,
+			role: row?.role
+		};
+		const present = {};
+		const missing = [];
+		for (const field of SUBSCRIPTION_FIELDS) {
+			const v = raw[field];
+			if (typeof v === "string" && v.trim() !== "") present[field] = v.trim();
+			else missing.push(field);
+		}
+		if (missing.length > 0) {
+			defects.push({
+				index,
+				missing,
+				present
+			});
+			return;
+		}
+		usable.push({
+			account: present.account,
+			user: present.user,
+			ccc: present.ccc,
+			role: present.role
+		});
+	});
+	return {
+		hit: usable.find((r) => r.account === account && r.user === user) ?? usable.find((r) => r.account === account && r.user === "*") ?? null,
+		defects,
+		usable: usable.length
+	};
+}
+/**
+* 入站路由决策（**纯函数**）。
+*
+* 顺序：**机器级订阅表优先** → 未命中时用 CCC 级回退。
+*
+* 🔴 **回退是过渡期的"不打断在用的微信"**（方案 §11.3 **Q5**）：机器级账号表为空时，
+* 桥仍按 CCC 起、路由也仍认 CCC 级 `routes`。机器级一旦配起来，回退传 `null`
+* ⇒ **未命中 = 不投递**（不是"投给默认角色"——那正是方案 §3.1 明令禁止的）。
+* @param input.subscriptions 机器级订阅表
+* @param input.account 收到的账号 id
+* @param input.user 发信人 id
+* @param input.fallback CCC 级回退目标（`{ccc, role}`）；无 ⇒ `null` ／ 省略
+*/
+function planInboundRoute(input) {
+	const { hit, defects } = lookupSubscription(input.subscriptions, input.account, input.user);
+	if (hit) return {
+		target: {
+			ccc: hit.ccc,
+			role: hit.role
+		},
+		source: "machine",
+		skipReason: null,
+		defects
+	};
+	if (input.fallback) return {
+		target: {
+			ccc: input.fallback.ccc,
+			role: input.fallback.role
+		},
+		source: "ccc-fallback",
+		skipReason: null,
+		defects
+	};
+	return {
+		target: null,
+		source: null,
+		skipReason: input.subscriptions.length === 0 ? "no-subscription" : "no-match",
+		defects
+	};
+}
+/**
+* 留痕落点：`$DSH_HOME/human-channel-audit.jsonl`（缺省 `~/.dsh/human-channel-audit.jsonl`）。
+*
+* 🔴 **为什么是机器级而不是某个 CCC 的 `_weixin-logs/`**：本文件记的事件（未投递 ／
+* 目标不存在 ／ 表残缺）**恰恰是"没有目标 CCC"的那些** —— 落进任何一个 CCC 都是**编一个**目标。
+* （投递成功的入站事件仍落**被路由到的那个 CCC** 的 `_weixin-logs/`，方案 §3.6 不变。）
+* env `SERENITY_HUMAN_CHANNEL_AUDIT` 覆盖（测试注入；与 `SERENITY_HOOKS_CONFIG` 同款推导）。
+*/
+function humanChannelAuditPath() {
+	const override = process.env.SERENITY_HUMAN_CHANNEL_AUDIT;
+	if (override && override !== "") return override;
+	const dshHome = process.env.DSH_HOME ?? join(process.env.HOME ?? "", ".dsh");
+	return join(dshHome, "human-channel-audit.jsonl");
+}
+/**
+* 追加一条留痕。**永不抛** ——
+* 留痕失败绝不能反过来打断投递（它是**旁路**，与 `invokeWeixinHook` 的"旁路容忍"同款）。
+* 🔴 **不静默的是它记的那件事**，不是它自己：所以调用方仍要**另行 `console` 出声**。
+*/
+function appendHumanChannelAudit(event) {
+	try {
+		const path = humanChannelAuditPath();
+		mkdirSync(dirname(path), { recursive: true });
+		appendFileSync(path, `${JSON.stringify({
+			ts: (/* @__PURE__ */ new Date()).toISOString(),
+			...event
+		})}\n`, "utf-8");
+	} catch {}
+}
 const manualSessions = /* @__PURE__ */ new Map();
 /**
 * 本轮是否已成功发送（**由桥在每轮开始时清空** `clearSentThisTurn`；闸门只置位不清空——
@@ -16136,6 +16540,7 @@ function invokeWeixinHook(root, hookRel, event) {
 //#region src/weixin-bridge.ts
 var weixin_bridge_exports = /* @__PURE__ */ __exportAll({
 	handleIncoming: () => handleIncoming,
+	handleMachineIncoming: () => handleMachineIncoming,
 	manualOutputFallbackNeeded: () => manualOutputFallbackNeeded,
 	registerWeixinBridge: () => registerWeixinBridge,
 	resolveWeixinAccount: () => resolveWeixinAccount,
@@ -16143,9 +16548,21 @@ var weixin_bridge_exports = /* @__PURE__ */ __exportAll({
 	stopAllBridges: () => stopAllBridges,
 	stopCccBridge: () => stopCccBridge,
 	syncCccBridge: () => syncCccBridge,
+	syncHumanChannel: () => syncHumanChannel,
 	weixinBridgeStatus: () => weixinBridgeStatus
 });
 const bridges = /* @__PURE__ */ new Map();
+/**
+* 🔴 **机器级 poller 的"根"哨兵**（P0-3 A）—— 它**不是一个目录**。
+*
+* 机器级 poller **不属于任何 CCC**（这正是"上移 ACC 层"的含义：谁轮询不再由 CCC 数量决定）。
+* 用途有二：① `runAccountLoop` 的 `root` 形参在机器级模式下不被使用，传它以示"无根"；
+* ② 归属表（`human-channel.ts`）按 root 区分拥有者 ⇒ 机器级用这个哨兵值，
+*    与任何**真实** CCC 根都不会撞（真根一律是绝对路径）。
+*/
+const MACHINE_SCOPE = "<machine>";
+/** 机器级 poller（账号 id → 循环）。与 `bridges` **互斥**：同一时刻只有一种模式在跑。 */
+const machineLoops = /* @__PURE__ */ new Map();
 /** 轮询间隔（getupdates 失败后重试延迟；成功 = 立即续轮询） */
 const POLL_RETRY_MS = 3e3;
 /** 媒体大小上限（M6：20MB，对齐 vlm-describe；超限降级告知不落盘） */
@@ -16199,7 +16616,7 @@ async function sendTypingStop(cred, accountId, fromUserId) {
 	}
 }
 /** 单账号轮询循环：getupdates 长轮询 → 逐消息分发 → 回复回写 */
-async function runAccountLoop(ctx, root, accountId, cred, loop) {
+async function runAccountLoop(ctx, root, accountId, cred, loop, machine = false) {
 	let buf = "";
 	while (!loop.stopped) {
 		loop.lastPollAt = Date.now();
@@ -16214,7 +16631,8 @@ async function runAccountLoop(ctx, root, accountId, cred, loop) {
 			for (const msg of resp.msgs ?? []) {
 				if (loop.stopped) break;
 				if (msg.message_type !== 1) continue;
-				await handleIncoming(ctx, root, accountId, cred, msg);
+				if (machine) await handleMachineIncoming(ctx, accountId, cred, msg);
+				else await handleIncoming(ctx, root, accountId, cred, msg);
 			}
 		} catch (err) {
 			loop.lastError = err instanceof Error ? err.message : String(err);
@@ -16257,6 +16675,106 @@ function manualOutputFallbackNeeded(input) {
 	return input.fallbackOnNoSend === true && input.guardActive && !input.sentThisTurn && input.answer !== "";
 }
 /**
+* 订阅表里的 `ccc` **别名 → CCC 根**（P0-3）。
+*
+* 别名取值与面板下拉**同源**（方案 §2.3：`listCccs({withRoles:true})` 的下拉）⇒
+* 先按 **`CccEntry.name`**（= CCC 根目录名，`basename(root)`）匹配；再退一步接受**绝对路径**
+* （手写配置时人会直接粘路径）。两条都试 ⇒ 两种写法都可用，且**不引入第二张名字表**。
+* @returns 命中的 CCC 根；枚举里没有 ⇒ `null`（调用方**响亮报错**，不静默丢弃）
+*/
+async function resolveCccRootByAlias(ctx, alias) {
+	try {
+		const { listCccs } = await import("./ccc-roots-Duk89a-h.js").then((n) => n.a);
+		const entries = await listCccs(ctx);
+		const byName = entries.find((e) => e.name === alias);
+		if (byName) return byName.root;
+		const byRoot = entries.find((e) => e.root === alias);
+		return byRoot ? byRoot.root : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* **入站路由的单一解析处**（P0-3）：机器级订阅表优先 → CCC 级回退；三档语义都在这里落地。
+*
+* 🔴 为什么抽成一个函数而不是写两遍：**两种模式（CCC 起桥 ／ 机器级起 poller）走的是同一套
+* 判据**，差别只有一格 —— **有没有 CCC 级回退**（`cccFallback`）。写两遍必然分叉。
+*
+* 三档（方案 §3.1，**刻意分档**）：
+*  - **未命中** ⇒ 不投递 ＋ **留痕**（`console.warn`，静默档：这是"表里没有你"，不是错误）
+*  - **表残缺** ⇒ **响亮出声**（`console.error`；且**独立于是否命中**）
+*  - **目标不存在**（CCC ／ 角色）⇒ **响亮报错**（`console.error`；不静默丢弃）
+*
+* @param input.cccFallback 过渡期回退（方案 Q5）；**机器级模式传 `null`** ⇒ 未命中即不投递
+*/
+async function resolveInboundTarget(ctx, input) {
+	const route = planInboundRoute({
+		subscriptions: readSimpleSettings().humanChannel.subscriptions,
+		account: input.account,
+		user: input.user,
+		fallback: input.cccFallback ? {
+			ccc: input.cccFallback.root,
+			role: input.cccFallback.role
+		} : null
+	});
+	for (const defect of route.defects) {
+		console.error(`[serenity-hooks] ✗ human-channel: 订阅表第 ${defect.index + 1} 行**残缺**（缺 ${defect.missing.join(" / ")}）｜已有字段 ${JSON.stringify(defect.present)}｜该行**不生效** —— 请补全或删掉（机器级 humanChannel.subscriptions）`);
+		appendHumanChannelAudit({
+			kind: "subscription-defect",
+			account: input.account,
+			index: defect.index,
+			missing: defect.missing,
+			present: defect.present
+		});
+	}
+	const target = route.target;
+	if (!target) {
+		const detail = route.skipReason === "no-subscription" ? "机器级订阅表为空（且无 CCC 级回退）" : "订阅表里没有匹配 (账号, 用户) 的行";
+		console.warn(`[serenity-hooks] ⚠ human-channel: 入站未命中订阅 ⇒ **不投递**（account=${input.account} user=${input.user}）：${detail}`);
+		appendHumanChannelAudit({
+			kind: "inbound-unrouted",
+			account: input.account,
+			user: input.user,
+			reason: route.skipReason ?? "no-match",
+			detail
+		});
+		return null;
+	}
+	const root = route.source === "ccc-fallback" ? target.ccc : await resolveCccRootByAlias(ctx, target.ccc);
+	if (root === null) {
+		const detail = `订阅表指向的 CCC "${target.ccc}" 在本机 CCC 枚举里不存在`;
+		console.error(`[serenity-hooks] ✗ human-channel: ${detail}（account=${input.account} user=${input.user}）—— 该消息**未投递**，请改订阅表`);
+		appendHumanChannelAudit({
+			kind: "inbound-target-missing",
+			account: input.account,
+			user: input.user,
+			ccc: target.ccc,
+			role: target.role,
+			detail
+		});
+		return null;
+	}
+	const role = readSkiffRoles(root).get(target.role);
+	if (!role) {
+		const detail = `目标 CCC "${target.ccc}" 未定义 skiff 角色 "${target.role}"`;
+		console.error(`[serenity-hooks] ✗ human-channel: ${detail}（account=${input.account} user=${input.user}）—— 该消息**未投递**，请改订阅表或该 CCC 的 skiff.roles`);
+		appendHumanChannelAudit({
+			kind: "inbound-target-missing",
+			account: input.account,
+			user: input.user,
+			ccc: target.ccc,
+			role: target.role,
+			detail
+		});
+		return null;
+	}
+	return {
+		root,
+		roleName: target.role,
+		role
+	};
+}
+/**
 * 处理单条微信消息：路由 → skiff 会话（固定 id 创建/延续）→ 提问 → 回复回写。
 *
 * 会话语义：`weixinSessionIdFor(fromUserId)` 固定可重建——同用户长期同一会话；
@@ -16273,16 +16791,35 @@ function manualOutputFallbackNeeded(input) {
 *   `_tmp/weixin-inbound/<userhash>/` → question 注入「存在性 + 路径」（ACC 层只保证
 *   可达性——"让会话知道文件的存在并可以拿到"；识别/解析归角色 LLM 决策，不编排）。
 *   降级不静默：下载失败 / 超 20MB → 注入说明进对话；typing 窗口覆盖下载（M7）。
+*
+* 🔴 **P0-3（2026-09-27）：路由改由机器级订阅表决定**（本函数的 `root` 入参退为
+* **回退目标**）。两档语义刻意分开（方案 §3.1）：**未命中 ⇒ 不投递 ＋ 留痕**（静默档）；
+* **目标不存在（CCC ／ 角色）⇒ 响亮报错**（`console.error` ＋ 机器级留痕）。两者都
+* **不是**"投给默认角色"。
 */
-async function handleIncoming(ctx, root, accountId, cred, msg) {
+async function handleIncoming(ctx, root, accountId, cred, msg, preset) {
 	const fromUserId = msg.from_user_id;
 	if (!fromUserId) return;
 	const text = extractWeixinText(msg);
 	const mediaRefs = extractWeixinMedia(msg);
 	const settings = readWeixinSettings(root);
-	if (!settings.enabled) return;
-	const roleName = matchWeixinRoute(settings.routes ?? [], fromUserId);
-	if (!roleName) return;
+	let resolved;
+	if (preset) resolved = preset.target;
+	else {
+		if (!settings.enabled) return;
+		const cccRole = matchWeixinRoute(settings.routes ?? [], fromUserId);
+		resolved = await resolveInboundTarget(ctx, {
+			account: accountId,
+			user: fromUserId,
+			cccFallback: cccRole ? {
+				root,
+				role: cccRole
+			} : null
+		});
+	}
+	if (!resolved) return;
+	const { roleName, role } = resolved;
+	root = resolved.root;
 	if (!text && mediaRefs.length === 0) {
 		if (hasVoiceItem(msg)) await sendTextMessage({
 			baseUrl: cred.baseUrl,
@@ -16294,11 +16831,6 @@ async function handleIncoming(ctx, root, accountId, cred, msg) {
 		return;
 	}
 	try {
-		const role = readSkiffRoles(root).get(roleName);
-		if (!role) {
-			console.log(`[serenity-hooks] weixin-bridge: 路由命中角色 "${roleName}" 但该 CCC 未定义（检查 skiff.roles）`);
-			return;
-		}
 		const sessionId = weixinSessionIdFor(fromUserId);
 		const existing = getSkiffAgent(sessionId);
 		const hc = readHandymanConfig(root);
@@ -16458,8 +16990,38 @@ async function handleIncoming(ctx, root, accountId, cred, msg) {
 	}
 }
 /**
+* **机器级 poller 的单条消息入口**（P0-3 A）。
+*
+* 与 `handleIncoming` 的唯一差别：**目标由机器级订阅表逐条解析，且没有 CCC 级回退**
+* （方案 §3.1：机器级模式下**未命中 = 不投递**，不是"投给默认角色"）。
+* 解析出来后把**目标根**当 `root` 交给 `handleIncoming`（并带上 `preset` ⇒ 它不再自行路由、
+* 也不看目标 CCC 的 `weixin.enabled`）。
+*
+* 🔴 为什么"起 poller"与"路由"必须同批（本件即 P0-2 的后半）：机器级 poller 收到消息时
+* **不知道它属于哪个 CCC** —— 那个答案是订阅表给的。没有订阅表 ⇒ **能收不能投**。
+*
+* 🔵 **导出供测试直接驱动**（与 `handleIncoming` 同款：它俩都是"单条消息的入口"，
+* 生产路径 `runAccountLoop` 只是循环壳）。
+*/
+async function handleMachineIncoming(ctx, accountId, cred, msg) {
+	const fromUserId = msg.from_user_id;
+	if (!fromUserId) return;
+	const target = await resolveInboundTarget(ctx, {
+		account: accountId,
+		user: fromUserId,
+		cccFallback: null
+	});
+	if (!target) return;
+	await handleIncoming(ctx, target.root, accountId, cred, msg, { target });
+}
+/**
 * 启动/重建某 CCC 的桥：读配置 → 对每个 enabled + 有凭据的账号启动轮询循环。
 * 已存在（配置变化热重建）→ 先停旧循环再启动新的。
+*
+* 🔴 **P0-2（2026-09-27，方案 §2.6）：一账号一 poller** —— 起循环**之前**先过机器级归属判定
+* （`human-channel.ts`）：身份被**别的** CCC 占着的账号**不起循环**，只留一条响亮日志。
+* 身份 = **凭据 token 的哈希**（不是 `accountId`：那是每 CCC 的本地标签，跨 CCC 无意义）。
+* 先 `releasePollersOf(root)` 再重新 claim —— 热重建语义与"归属粘住不漂"的论证见该函数注释。
 */
 function syncCccBridge(ctx, root) {
 	const existing = bridges.get(root);
@@ -16467,41 +17029,164 @@ function syncCccBridge(ctx, root) {
 		for (const loop of existing.loops.values()) loop.stopped = true;
 		bridges.delete(root);
 	}
+	releasePollersOf(root);
 	const settings = readWeixinSettings(root);
 	if (!settings.enabled) return;
+	const requests = [];
+	const creds = /* @__PURE__ */ new Map();
+	for (const account of settings.accounts ?? []) {
+		if (account.enabled === false) continue;
+		const cred = readWeixinCredential(root, account.accountId);
+		if (!cred) continue;
+		creds.set(account.accountId, cred);
+		requests.push({
+			root,
+			accountId: account.accountId,
+			identity: accountIdentity(root, account.accountId, cred.token)
+		});
+	}
+	const plan = planPollerClaims(requests, pollerOwners());
+	for (const { request, ownedBy } of plan.skipped) console.warn(`[serenity-hooks] ⚠ weixin-bridge: 账号 ${request.accountId}（ccc=${root}）已被 ccc=${ownedBy.root} 的账号 ${ownedBy.accountId} 轮询 ⇒ 本处不重复起循环（一账号一 poller；方案 §2.6）`);
 	const bridge = {
 		root,
 		loops: /* @__PURE__ */ new Map()
 	};
-	for (const account of settings.accounts ?? []) {
-		if (account.enabled === false) continue;
-		const cred = readWeixinCredential(root, account.accountId);
+	for (const claim of plan.claims) {
+		const cred = creds.get(claim.accountId);
 		if (!cred) continue;
 		const loop = {
 			stopped: false,
 			lastPollAt: 0
 		};
-		bridge.loops.set(account.accountId, loop);
-		runAccountLoop(ctx, root, account.accountId, cred, loop);
+		bridge.loops.set(claim.accountId, loop);
+		runAccountLoop(ctx, root, claim.accountId, cred, loop);
 	}
+	commitPollerClaims(plan);
 	if (bridge.loops.size > 0) {
 		bridges.set(root, bridge);
 		console.log(`[serenity-hooks] ✓ weixin-bridge: ccc=${root} accounts=${[...bridge.loops.keys()].join(",")}`);
 	}
 }
-/** 停止某 CCC 的桥（移除账号/禁用时） */
+/** 停止某 CCC 的桥（移除账号/禁用时）；同时释放它的账号归属 */
 function stopCccBridge(root) {
 	const bridge = bridges.get(root);
+	releasePollersOf(root);
 	if (!bridge) return;
 	for (const loop of bridge.loops.values()) loop.stopped = true;
 	bridges.delete(root);
 }
 /**
-* 停止全部桥（插件 dispose）
+* 停掉**全部 CCC 级桥**（不碰机器级 poller）＋ 释放它们各自的账号归属。
+* 🔴 模式切换时必须先调它：否则同一个 bot 会被**两处**轮询（方案 §2.6 要消灭的正是这个）。
+*/
+function stopCccBridges() {
+	for (const root of [...bridges.keys()]) stopCccBridge(root);
+}
+/** 停掉**机器级 poller**（不碰 CCC 级桥）＋ 释放机器级归属 */
+function stopMachineLoops() {
+	for (const loop of machineLoops.values()) loop.stopped = true;
+	machineLoops.clear();
+	releasePollersOf(MACHINE_SCOPE);
+}
+/**
+* 停止全部桥（插件 dispose）：CCC 级 ＋ 机器级
 */
 function stopAllBridges() {
-	for (const bridge of bridges.values()) for (const loop of bridge.loops.values()) loop.stopped = true;
-	bridges.clear();
+	stopCccBridges();
+	stopMachineLoops();
+	releaseAllPollers();
+}
+/** 已告警过的"未实现渠道"（避免每次 session/created 都刷一行） */
+const warnedChannels = /* @__PURE__ */ new Set();
+/**
+* **机器级模式**：按**账号**起 poller（方案 §2.6「一账号一 poller」的正面形态）。
+*
+* 与 CCC 模式的差别：poller **不属于任何 CCC** —— 消息投到哪由**订阅表逐条决定**
+* （见 `handleMachineIncoming`）。凭据来自机器级配置本身（方案 Q3：凭据落插件 Config）。
+*
+* 🔴 进入本函数即**先停掉全部 CCC 级桥**：两种模式**互斥**（同时跑 = 同一 bot 两处轮询）。
+*/
+function syncMachinePollers(ctx, hc) {
+	stopCccBridges();
+	const requests = [];
+	const creds = /* @__PURE__ */ new Map();
+	for (const account of hc.accounts) {
+		const id = account.id;
+		if (account.enabled === false) continue;
+		if (!id) {
+			console.warn("[serenity-hooks] ⚠ human-channel: 机器级账号表有一行**缺 `id`** ⇒ 跳过（该行无法被订阅表引用）");
+			continue;
+		}
+		if (account.channel !== "weixin") {
+			if (!warnedChannels.has(`${id}:${account.channel ?? ""}`)) {
+				warnedChannels.add(`${id}:${account.channel ?? ""}`);
+				console.warn(`[serenity-hooks] ⚠ human-channel: 账号 ${id} 的渠道 "${account.channel ?? "(未填)"}" **本机未实现** ⇒ 不起 poller（当前只有 weixin）`);
+			}
+			continue;
+		}
+		const token = (account.token ?? "").trim();
+		if (token === "") {
+			console.warn(`[serenity-hooks] ⚠ human-channel: 账号 ${id} **无 token**（未绑定）⇒ 不起 poller`);
+			continue;
+		}
+		creds.set(id, {
+			token,
+			baseUrl: "",
+			userId: account.userId
+		});
+		requests.push({
+			root: MACHINE_SCOPE,
+			accountId: id,
+			identity: accountIdentity(MACHINE_SCOPE, id, token)
+		});
+	}
+	const plan = planPollerClaims(requests, pollerOwners());
+	for (const { request, ownedBy } of plan.skipped) console.warn(`[serenity-hooks] ⚠ human-channel: 机器级账号 ${request.accountId} 与 ${ownedBy.accountId} **绑的是同一个 bot** ⇒ 本处不重复起循环（一账号一 poller；方案 §2.6）`);
+	stopMachineLoops();
+	for (const claim of plan.claims) {
+		const cred = creds.get(claim.accountId);
+		if (!cred) continue;
+		const loop = {
+			stopped: false,
+			lastPollAt: 0
+		};
+		machineLoops.set(claim.accountId, loop);
+		runAccountLoop(ctx, MACHINE_SCOPE, claim.accountId, cred, loop, true);
+	}
+	commitPollerClaims(plan);
+	if (machineLoops.size > 0) console.log(`[serenity-hooks] ✓ human-channel: 机器级 poller accounts=${[...machineLoops.keys()].join(",")}（与 CCC 无关）`);
+}
+/**
+* 人机信道的**装配入口**（P0-3 A）—— 决定用哪种模式起 poller。
+*
+* 🔴 **模式由机器级账号表决定**（方案 §11.3 **Q5** 的过渡期语义）：
+*  - 账号表**非空** ⇒ **机器级模式**：按账号起 poller；路由**只认订阅表**
+*  - 账号表**为空** ⇒ **回退模式**（今天的形态）：按 CCC 起桥；路由**先查订阅表，未命中回退
+*    到 CCC 级 routes** ⇒ **不打断在用的微信**
+* ⚠️ 两种模式**互斥**（各自进入时先停掉另一种），否则同一个 bot 会被两处轮询。
+*/
+function syncHumanChannel(ctx) {
+	let hc;
+	try {
+		hc = readSimpleSettings().humanChannel;
+	} catch (err) {
+		console.warn(`[serenity-hooks] ✗ human-channel: 机器级配置读取失败 ⇒ 按"未配置"处理（回退按 CCC 起桥）: ${String(err?.message ?? err)}`);
+	}
+	if (hc && hc.accounts.length > 0) {
+		try {
+			syncMachinePollers(ctx, hc);
+		} catch (err) {
+			console.warn(`[serenity-hooks] ✗ human-channel: 机器级 poller 装配失败: ${String(err?.message ?? err)}`);
+		}
+		return;
+	}
+	(async () => {
+		try {
+			stopMachineLoops();
+			const { listCccs } = await import("./ccc-roots-Duk89a-h.js").then((n) => n.a);
+			for (const entry of await listCccs(ctx)) syncCccBridge(ctx, entry.root);
+		} catch {}
+	})();
 }
 /**
 * 解析该 CCC 的发送账号 + 凭据（v1.31.0：文本与文件发送的**单一账号选择真相源**）。
@@ -16585,35 +17270,37 @@ async function sendProactiveText(input) {
 		role
 	};
 }
-/** 桥状态快照（面板数据源）：每 CCC → 每账号 → 轮询健康 */
+/**
+* 桥状态快照（面板数据源）：每 CCC → 每账号 → 轮询健康。
+* 🔴 **P0-3 A 起多一行**：机器级 poller 以 `ccc: '<machine>'`（`MACHINE_SCOPE`）出现 ——
+* 它**不属于任何 CCC**，故**不伪装成某个 CCC 的行**（面板按原样显示这个哨兵值即可）。
+*/
 function weixinBridgeStatus() {
 	const out = [];
+	const toAccounts = (loops) => [...loops.entries()].map(([accountId, loop]) => ({
+		accountId,
+		lastPollAt: loop.lastPollAt,
+		...loop.lastError ? { lastError: loop.lastError } : {}
+	}));
 	for (const [root, bridge] of bridges) out.push({
 		ccc: root,
-		accounts: [...bridge.loops.entries()].map(([accountId, loop]) => ({
-			accountId,
-			lastPollAt: loop.lastPollAt,
-			...loop.lastError ? { lastError: loop.lastError } : {}
-		}))
+		accounts: toAccounts(bridge.loops)
+	});
+	if (machineLoops.size > 0) out.push({
+		ccc: MACHINE_SCOPE,
+		accounts: toAccounts(machineLoops)
 	});
 	return out;
 }
 /**
-* 装配（index.ts 调用）：扫描 live CCC 启动桥 + 监听会话变化。
-* 事件驱动（对齐 autotrajectory v1.26.15）：live 会话出现 → 同步该 CCC 桥。
+* 装配（index.ts 调用）：**按机器级配置决定模式**（P0-3 A：`syncHumanChannel`），
+* 并监听会话变化以重扫（新 CCC 出现即启动其桥；配置变化也可经此路径热重建）。
+* 事件驱动（对齐 autotrajectory v1.26.15）。
 */
 function registerWeixinBridge(ctx) {
-	const syncFromLive = () => {
-		(async () => {
-			try {
-				const { listCccs } = await import("./ccc-roots-Duk89a-h.js").then((n) => n.a);
-				for (const entry of await listCccs(ctx)) syncCccBridge(ctx, entry.root);
-			} catch {}
-		})();
-	};
-	syncFromLive();
+	syncHumanChannel(ctx);
 	try {
-		ctx.on("session/created", () => syncFromLive());
+		ctx.on("session/created", () => syncHumanChannel(ctx));
 	} catch {}
 }
 //#endregion
@@ -18755,6 +19442,21 @@ const inject = [
 	"settings",
 	"web"
 ];
+/** human-channel 账号行 schema（行形状 = `HumanChannelAccountConfig`） */
+const humanChannelAccountSchema = z.object({
+	id: z.string(),
+	channel: z.string(),
+	enabled: z.boolean().default(true),
+	token: z.string(),
+	userId: z.string()
+});
+/** human-channel 订阅行 schema：`(账号, 用户) → (CCC, 角色)` */
+const humanChannelSubscriptionSchema = z.object({
+	account: z.string(),
+	user: z.string(),
+	ccc: z.string(),
+	role: z.string()
+});
 const Config = z.object({
 	serenityConfigPaths: z.array(z.string()).default([...DEFAULT_SERENITY_CONFIG_PATHS]),
 	tools: z.boolean().default(true),
@@ -18780,6 +19482,12 @@ const Config = z.object({
 	webFetch: z.object({ enabled: z.boolean().default(true) }),
 	opencodeProvider: z.object({ autoConfigure: z.boolean().default(true) }),
 	visionPatch: z.object({ enabled: z.boolean().default(true) }),
+	humanChannel: z.object({
+		accounts: z.array(humanChannelAccountSchema).default([]),
+		subscriptions: z.array(humanChannelSubscriptionSchema).default([]),
+		relay: z.object({ ccc: z.string() }),
+		sending: z.object({ allow: z.array(z.string()).default(["*"]) })
+	}),
 	gatewayEnabled: z.boolean().volatile(),
 	rebuildThresholdK: z.number().min(50).max(4e3).volatile(),
 	skiffEnabled: z.boolean().volatile(),
@@ -19014,4 +19722,4 @@ function registerAcp(ctx) {
 	sync();
 }
 //#endregion
-export { Config, apply, inject, name };
+export { Config, apply, humanChannelAccountSchema, humanChannelSubscriptionSchema, inject, name };