@feng0531/dsh-execution-bus 0.11.3 → 0.12.1

package/README.md

@@ -4,7 +4,7 @@
 
 “萧何”是产品与模式显示名，执行总线是其技术功能；不新增人物 Agent，不进行角色扮演。仓库 dsh-execution-bus、npm 包名、execution_bus 工具名及 execution-bus-test 预设 ID 保持不变。历史版本发布说明保留当时名称。
 
-DSH 独立插件：`@feng0531/dsh-execution-bus` · 当前版本 **0.11.3**
+DSH 独立插件：`@feng0531/dsh-execution-bus` · 当前版本 **0.12.1**
 
 > 萧何模式从宿主已声明的 PTC 组合派生，保留日常工具，再叠加可选执行总线。已验证隔离的真实 Node PTC → 原 read + 总线调用，以及脚本模型内存会话；真实模型、桌面界面与实际沙箱仍未验收。**不支持重启后恢复任务。**
 
@@ -130,7 +130,7 @@ flowchart TD
 2. 在你选定的隔离 DSH 配置依赖目录安装固定版本，不要在 DSH 程序安装目录执行：
 
    ```powershell
-   npm install --ignore-scripts @feng0531/dsh-execution-bus@0.11.3
+   npm install --ignore-scripts @feng0531/dsh-execution-bus@0.12.1
    ```
 
    这是 npm 目录示例。若目标配置使用 pnpm，应沿用其包管理器，不混用锁文件。遇到宿主 peer 版本冲突就停止，不用强制安装绕过。
@@ -205,7 +205,14 @@ PTC 是 DSH 的程序化工具调用入口。在 `run_code` 内使用 `await too
 
 **跨步骤取回的正确姿势（0.11.1 补充）：** 同一 `run_code` 程序内，未完成的 request 会阻塞后发工具调用的结果提交（宿主按提交顺序结算）；不要在同一个程序里“启动后立刻 status 轮询”。启动步骤只发请求并尽早结束程序，下一步再用同一 `requestId` 的 `status`/`result`（或重发同一 request）附着取回——pilot 实测单次执行、返回 `reused:true`。
 
-**0.9.0 起，预算到期不再连带取消已受理执行。** `run_code` 因时间预算到期或程序结束时，宿主会中断其中的工具子调用；总线把这种中断视为**只停止等待**：已受理执行与宿主 Job 继续，程序返回预算错误后，可在后续 `run_code` 中用同一 `requestId` 的 `status`/`result` 取回结果，或用 `cancel` 取消。用户主动中断、会话取消、沙箱模式变化等其他原因仍会请求取消整个执行。该识别依赖 DSH 0.2.1-rc.2 的中断原因字符串（见[宿主兼容性](<docs/host-compatibility.md>)），不是宿主公开稳定契约；进程退出仍会丢失全部内存状态，保留期一小时。
+### 调度与互斥（0.12.0 起，0.12.1 修正）
+
+- **队列类别**：内置 Handler 分为 `fs`（read/glob/grep/edit/write）、`command`（pwsh）、`diagnostic`（test）。同会话内按类别优先级 + 等待老化选择：等待越久提升越多、不封顶（最低到 0 后按 FIFO），避免低优先类别饥饿。
+- **舱壁**：Handler 可声明 `maxConcurrency`，同一 Handler 运行数受限；`execution_bus_state` 的 `waitReason` 会显示 `concurrency`/`bulkhead`/`resource`/`dispatch`，运行超过 30 秒的任务标记 `longRunning`。
+- **资源互斥**：`host.edit`/`host.write` 按 `file_path` 资源键在同一总线实例内串行，避免同文件并发写；失败/取消/关闭都会释放。它是插件内互斥，不是 OS 文件锁或跨进程保证；同一文件的相对/绝对、大小写等别名写法可能绕过互斥。
+- **唯一任务**：核心 Handler 接口支持 `dedupe:"payload"`；**0.12.1 起内置 host.* 不启用**——文件、权限或工作目录变化后缓存旧结果会静默返回过期内容。扩展 Handler 可显式声明并自行承担失效责任（失败/取消/unknown 不缓存）。
+
+**0.9.0 起，预算到期不再连带取消已受理执行。** `run_code` 因时间预算到期或程序结束时，宿主会中断其中的工具子调用；总线把这种中断视为**只停止等待**：已受理执行与宿主 Job 继续，程序结束或预算到期后，可在后续 `run_code` 中用同一 `requestId` 的 `status`/`result` 读快照，或重发同一 request 等待终态（`reused:true`），或用 `cancel` 取消。用户主动中断、会话取消、沙箱模式变化等其他原因仍会请求取消整个执行。该识别依赖 DSH 0.2.1-rc.2 的中断原因字符串（见[宿主兼容性](<docs/host-compatibility.md>)），不是宿主公开稳定契约；进程退出仍会丢失全部内存状态，保留期一小时。
 
 ## 如何理解任务状态？
 
@@ -280,7 +287,7 @@ npm run test:install    # 临时目录安装，不操作日常 DSH
 
 - [协议和投递语义](<docs/protocol.md>)：字段、状态、重复处理与取消规则。
 - [宿主兼容性与源码调用链](<docs/host-compatibility.md>)：为什么可以等待，为什么不能跨重启恢复。
-- [验证记录](<docs/validation.md>)、[0.11.3 发布说明](<docs/releases/0.11.3.md>)：已验证与未验证范围。
+- [验证记录](<docs/validation.md>)、[0.12.1 发布说明](<docs/releases/0.12.1.md>)：已验证与未验证范围。
 - [同类项目源码整合](<docs/INTEGRATION.md>)：固定来源、采用范围、许可与验证边界。
 - [维护者发布流程](<docs/RELEASING.md>)：标签 CI、安装包校验与正式发布门禁。
 

package/THIRD_PARTY_NOTICES.md

@@ -5,3 +5,5 @@
 CI 与发布组织方式参考 dsh-vcs，并按本项目执行能力重新实现；本包不含 Monaco、React 或 SVN 实现。
 
 0.5.0 定向参考 dsh-llm-rate-limit（MIT，hanruochong）、dsh-nightshift（MIT，contributors）和 dsh-input-traffic（MIT，contributors）的准入、生命周期和会话视图原则，按本项目契约自行实现，没有复制其源码或捆绑依赖。AsyncGate 与 cc-multi-process-mcp 仅用于边界比较，所查快照未发现 LICENSE，不复制代码。固定来源与阅读范围见 [整合说明](<docs/INTEGRATION.md>)。
+
+0.12.0 定向阅读 Temporal（文档；SDK MIT）、Restate（文档；BUSL-1.1，未复制代码）、DBOS（文档；Transact MIT）、Oban（Apache-2.0）、BullMQ（MIT）与 Resilience4j（Apache-2.0）的公开文档/README，按本插件边界重新实现调度隔离与资源互斥，没有复制第三方源码或新增运行依赖。fast-check（MIT，dubzzz）仅作为开发依赖用于属性测试，不进入本项目 tgz。

package/dist/bus.d.ts

@@ -6,6 +6,14 @@ export interface AdmissionPolicy {
     sessionQueueLimit?: number;
     maxQueueWaitMs?: number;
 }
+export interface SchedulerPolicy {
+    /** Handler.queue → 类别优先级（数值越小越先出队）。 */
+    queueClassOrder?: Readonly<Record<string, number>>;
+    /** 等待多久提升一级（最多提升两级）。 */
+    queueAgingMs?: number;
+    /** 运行超过该阈值时在状态快照标记 longRunning。 */
+    longRunningMs?: number;
+}
 /** Volatile single-process bus; no acceptance durability or automatic execution retry. */
 export declare class ExecutionBus {
     readonly options: {
@@ -16,11 +24,17 @@ export declare class ExecutionBus {
         retentionMs: number;
     };
     readonly admission: AdmissionPolicy;
+    readonly scheduler: Readonly<Required<SchedulerPolicy>>;
     private entries;
     private handlers;
     private queue;
     private readyOwners;
     private running;
+    private runningByHandler;
+    /** 资源键 → 占用它的运行中 Entry；有副作用 Handler 据此互斥。 */
+    private resourceLocks;
+    /** payload 指纹 → 已成功或运行中的 Entry，用于唯一任务复用。 */
+    private dedupeIndex;
     private retainedResultBytes;
     private closed;
     private telemetry;
@@ -40,6 +54,7 @@ export declare class ExecutionBus {
             job_released?: number | undefined;
             job_error?: number | undefined;
             reused?: number | undefined;
+            unique_reused?: number | undefined;
         };
         traces: {
             operation: number;
@@ -55,7 +70,7 @@ export declare class ExecutionBus {
         recordLimit: number;
         resultBytes: number;
         retentionMs: number;
-    }, admission?: AdmissionPolicy);
+    }, admission?: AdmissionPolicy, scheduler?: Readonly<Required<SchedulerPolicy>>);
     register(name: string, handler: Handler): () => void;
     private key;
     private emit;
@@ -81,6 +96,22 @@ export declare class ExecutionBus {
     private admitInvocation;
     /** 若启用了排队期限，登记到期结算为 QUEUE_WAIT_TIMEOUT 的计时器。 */
     private scheduleQueueDeadline;
+    /** 计算并校验 Handler 的资源键；失败则请求不进入队列。 */
+    private resourcesFor;
+    /** 唯一任务命中已成功终态时，构造一个不再执行 Handler 的只读结果记录。 */
+    private syntheticUnique;
+    private releaseResources;
+    /** 优先类别表按自有属性查；未知类别回退 default 权重，避免原型链 NaN。 */
+    private classRank;
+    /** 当前阻塞来源：Handler 舱壁优先于资源锁；undefined 表示可运行。 */
+    private blockedBy;
+    /** 是否有空闲槽位供此 Entry 开始执行（Handler 舱壁 + 资源互斥）。 */
+    private eligible;
+    /** 类别优先级 + 等待老化：等待越久提升越多（不封顶），最低到 0；
+     *  同分时按队列先后（FIFO）决出，避免低优先类别饥饿。 */
+    private effectivePriority;
+    /** 对已到期的排队任务结算 QUEUE_WAIT_TIMEOUT，再从队列移除。 */
+    private expireQueued;
     private attachment;
     command(owner: Owner, raw: unknown): RecordView;
     private removeQueued;
@@ -104,6 +135,7 @@ export declare class ExecutionBus {
             error: string | null;
             progress: number | null;
             waitReason: string | null;
+            longRunning: boolean;
             phase: string;
             queueMs: number;
             runMs: number;
@@ -113,7 +145,7 @@ export declare class ExecutionBus {
     };
     private cancel;
     private finish;
-    /** 按会话轮转挑选下一个出队项：各会话内部 FIFO，跨会话公平。 */
+    /** 按会话轮转选择下一个可执行项：会话内按类别优先级 + 老化，跨会话公平。 */
     private nextQueuedIndex;
     private pump;
     private run;

package/dist/bus.js

@@ -4,7 +4,7 @@ import { Diagnostics } from "./diagnostics.js";
 import { ERRORS } from "./error-codes.js";
 import { assertJson } from "./json.js";
 import { LIMITS } from "./limits.js";
-import { CORE_DEFAULTS } from "./product.js";
+import { CORE_DEFAULTS, SCHEDULER_POLICY } from "./product.js";
 import { canonical, freezeJson, object, parse } from "./protocol.js";
 export { object, parse };
 const isTerminal = (s) => !["queued", "running"].includes(s);
@@ -12,15 +12,25 @@ const isTerminal = (s) => !["queued", "running"].includes(s);
 function hashPayload(payload) {
     return createHash("sha256").update(canonical(payload)).digest("hex");
 }
+/** 消息身份只保存摘要，避免为每个 messageId 保留完整消息文本占用内存。 */
+function hashMessage(m) {
+    return createHash("sha256").update(canonical(m)).digest("hex");
+}
 /** Volatile single-process bus; no acceptance durability or automatic execution retry. */
 export class ExecutionBus {
     options;
     admission;
+    scheduler;
     entries = new Map();
     handlers = new Map();
     queue = [];
     readyOwners = [];
     running = 0;
+    runningByHandler = new Map();
+    /** 资源键 → 占用它的运行中 Entry；有副作用 Handler 据此互斥。 */
+    resourceLocks = new Map();
+    /** payload 指纹 → 已成功或运行中的 Entry，用于唯一任务复用。 */
+    dedupeIndex = new Map();
     retainedResultBytes = 0;
     closed = false;
     telemetry = new Diagnostics();
@@ -36,9 +46,55 @@ export class ExecutionBus {
     }
     closing;
     shutdownPhase = "open";
-    constructor(options = CORE_DEFAULTS, admission = {}) {
+    constructor(options = CORE_DEFAULTS, admission = {}, scheduler = SCHEDULER_POLICY) {
         this.options = options;
         this.admission = admission;
+        this.scheduler = scheduler;
+        const schedulerKeys = ["queueClassOrder", "queueAgingMs", "longRunningMs"];
+        if (!scheduler ||
+            typeof scheduler !== "object" ||
+            Array.isArray(scheduler) ||
+            Reflect.ownKeys(scheduler).some((key) => typeof key !== "string" || !schedulerKeys.includes(key)))
+            throw Error(ERRORS.INVALID_OPTIONS);
+        for (const key of Reflect.ownKeys(scheduler)) {
+            const descriptor = Object.getOwnPropertyDescriptor(scheduler, key);
+            if (!("value" in descriptor) || !descriptor.enumerable)
+                throw Error(ERRORS.INVALID_OPTIONS);
+        }
+        // 只读取一次：拒绝 accessor，避免校验值与落库值不一致。
+        const queueAgingMs = scheduler.queueAgingMs;
+        const longRunningMs = scheduler.longRunningMs;
+        const rawOrder = scheduler.queueClassOrder;
+        if (!Number.isSafeInteger(queueAgingMs) ||
+            queueAgingMs < 1 ||
+            !Number.isSafeInteger(longRunningMs) ||
+            longRunningMs < 1 ||
+            !rawOrder ||
+            typeof rawOrder !== "object" ||
+            Array.isArray(rawOrder))
+            throw Error(ERRORS.INVALID_OPTIONS);
+        const order = Object.create(null);
+        for (const className of Reflect.ownKeys(rawOrder)) {
+            if (typeof className !== "string")
+                throw Error(ERRORS.INVALID_OPTIONS);
+            if (["__proto__", "constructor", "prototype"].includes(className))
+                throw Error(ERRORS.INVALID_OPTIONS);
+            const descriptor = Object.getOwnPropertyDescriptor(rawOrder, className);
+            if (!("value" in descriptor) || !descriptor.enumerable)
+                throw Error(ERRORS.INVALID_OPTIONS);
+            const rank = descriptor.value;
+            if (className.length === 0 ||
+                className.length > 64 ||
+                !Number.isSafeInteger(rank) ||
+                rank < 0)
+                throw Error(ERRORS.INVALID_OPTIONS);
+            order[className] = rank;
+        }
+        this.scheduler = Object.freeze({
+            queueClassOrder: Object.freeze(order),
+            queueAgingMs: queueAgingMs,
+            longRunningMs: longRunningMs,
+        });
         const allowed = ["sessionQueueLimit", "maxQueueWaitMs"];
         if (!admission ||
             typeof admission !== "object" ||
@@ -79,7 +135,34 @@ export class ExecutionBus {
     register(name, handler) {
         if (this.handlers.has(name))
             throw Error(ERRORS.DUPLICATE_HANDLER);
-        const registration = { handler, token: Symbol(name) };
+        if (!handler ||
+            typeof handler !== "object" ||
+            typeof handler.validate !== "function" ||
+            typeof handler.run !== "function" ||
+            (handler.idempotent !== undefined && typeof handler.idempotent !== "boolean") ||
+            (handler.queue !== undefined &&
+                (typeof handler.queue !== "string" ||
+                    handler.queue.length === 0 ||
+                    handler.queue.length > 64 ||
+                    ["__proto__", "constructor", "prototype"].includes(handler.queue))) ||
+            (handler.maxConcurrency !== undefined &&
+                (!Number.isSafeInteger(handler.maxConcurrency) ||
+                    handler.maxConcurrency < 1)) ||
+            (handler.dedupe !== undefined && handler.dedupe !== "payload") ||
+            (handler.dedupe === "payload" && handler.idempotent !== true) ||
+            (handler.resources !== undefined && typeof handler.resources !== "function"))
+            throw Error(ERRORS.INVALID_HANDLER_OPTIONS);
+        // 注册时快照并冻结调度/复用选项，运行期修改原对象不再影响已注册行为。
+        const fixed = Object.freeze({
+            idempotent: handler.idempotent,
+            queue: handler.queue,
+            maxConcurrency: handler.maxConcurrency,
+            dedupe: handler.dedupe,
+            resources: handler.resources?.bind(handler),
+            validate: handler.validate.bind(handler),
+            run: handler.run.bind(handler),
+        });
+        const registration = { handler: fixed, token: Symbol(name) };
         this.handlers.set(name, registration);
         let disposed = false;
         return () => {
@@ -145,6 +228,10 @@ export class ExecutionBus {
                 this.retainedResultBytes -= e.resultBytes;
                 this.entries.delete(k);
             }
+        const live = new Set(this.entries.values());
+        for (const [key, e] of this.dedupeIndex)
+            if (!live.has(e))
+                this.dedupeIndex.delete(key);
     }
     submit(owner, raw, onEvent, invoke) {
         if (this.closed)
@@ -182,14 +269,14 @@ export class ExecutionBus {
         if (e.handler.idempotent === false && isTerminal(e.view.state))
             throw Error(ERRORS.MUTATING_REUSE_DENIED);
         const previous = e.messages.get(m.messageId);
-        if (previous && previous !== canonical(m))
+        if (previous && previous !== hashMessage(m))
             throw Error(ERRORS.MESSAGE_CONFLICT);
         if (!previous && e.messages.size >= LIMITS.messageAccountLimit)
             throw Error(ERRORS.MESSAGE_LIMIT);
         // 先取得附着，再提交消息身份：附着被拒（WAITER_LIMIT）时无副作用。
         const attached = this.attachment(e, onEvent, m.messageId, true);
         if (!previous)
-            e.messages.set(m.messageId, canonical(m));
+            e.messages.set(m.messageId, hashMessage(m));
         this.telemetry.record(e.trace, "reused");
         return attached;
     }
@@ -199,6 +286,32 @@ export class ExecutionBus {
         if (!handler)
             throw Error(ERRORS.UNKNOWN_HANDLER);
         handler.validate(parts.input);
+        // validate 是用户代码：可能在同步执行中触发 close()。
+        if (this.closed)
+            throw Error(ERRORS.CLOSED);
+        const dedupeKey = handler.dedupe === "payload"
+            ? JSON.stringify([owner.sessionId, parts.handler, fingerprint])
+            : undefined;
+        if (dedupeKey !== undefined) {
+            const target = this.dedupeIndex.get(dedupeKey);
+            if (target !== undefined &&
+                target.view.state === "succeeded" &&
+                isTerminal(target.view.state)) {
+                try {
+                    const unique = this.syntheticUnique(owner, m, parts, key, fingerprint, handler, target, dedupeKey);
+                    return this.attachment(unique, onEvent, m.messageId, true);
+                }
+                catch (error) {
+                    if (error instanceof Error && error.message === ERRORS.BACKPRESSURE)
+                        throw error;
+                    // 结果不可克隆时退回正常执行，避免把唯一缓存错误变成请求失败。
+                }
+            }
+        }
+        const resources = this.resourcesFor(handler, parts.input);
+        // resources 也是用户代码，返回后重新确认总线未在同步段关闭。
+        if (this.closed)
+            throw Error(ERRORS.CLOSED);
         if (this.entries.size >= this.options.recordLimit ||
             this.queue.length >= this.options.queueLimit)
             throw Error(ERRORS.BACKPRESSURE);
@@ -216,6 +329,10 @@ export class ExecutionBus {
             owner: owner.sessionId,
             fingerprint,
             handler,
+            handlerName: parts.handler,
+            queueClass: handler.queue ?? "default",
+            resources,
+            dedupeKey,
             input: structuredClone(parts.input),
             view: {
                 requestId: m.requestId,
@@ -232,9 +349,11 @@ export class ExecutionBus {
             dispatching: false,
             sourceSequence: 0,
             created: Date.now(),
-            messages: new Map([[m.messageId, canonical(m)]]),
+            messages: new Map([[m.messageId, hashMessage(m)]]),
         };
         this.entries.set(key, e);
+        if (dedupeKey !== undefined)
+            this.dedupeIndex.set(dedupeKey, e);
         this.telemetry.record(e.trace, "accepted");
         const attached = this.attachment(e, onEvent, m.messageId);
         this.queue.push(e);
@@ -262,6 +381,131 @@ export class ExecutionBus {
         };
         e.queueTimer = setTimeout(expire, this.admission.maxQueueWaitMs);
     }
+    /** 计算并校验 Handler 的资源键；失败则请求不进入队列。 */
+    resourcesFor(handler, input) {
+        if (handler.resources === undefined)
+            return [];
+        let raw;
+        try {
+            raw = handler.resources(input);
+        }
+        catch {
+            throw Error(ERRORS.INVALID_RESOURCES);
+        }
+        if (!Array.isArray(raw) || raw.length > 8)
+            throw Error(ERRORS.INVALID_RESOURCES);
+        const resources = [];
+        for (const resource of raw) {
+            if (typeof resource !== "string" ||
+                resource.length === 0 ||
+                resource.length > 256)
+                throw Error(ERRORS.INVALID_RESOURCES);
+            if (!resources.includes(resource))
+                resources.push(resource);
+        }
+        resources.sort();
+        return resources;
+    }
+    /** 唯一任务命中已成功终态时，构造一个不再执行 Handler 的只读结果记录。 */
+    syntheticUnique(owner, m, parts, key, fingerprint, handler, target, dedupeKey) {
+        if (this.entries.size >= this.options.recordLimit)
+            throw Error(ERRORS.BACKPRESSURE);
+        const snapshot = freezeJson(structuredClone({
+            requestId: m.requestId,
+            state: "succeeded",
+            sequence: 1,
+            cancelRequested: false,
+            delivery: "pending",
+            result: target.view.result,
+        }));
+        let resultBytes = 0;
+        try {
+            if (snapshot.result !== undefined)
+                resultBytes = Buffer.byteLength(JSON.stringify(snapshot.result));
+        }
+        catch {
+            resultBytes = target.resultBytes;
+        }
+        let resolve;
+        const done = new Promise((r) => (resolve = r));
+        const trace = this.telemetry.begin();
+        const e = {
+            trace,
+            resultBytes,
+            startedAt: trace.at,
+            finishedAt: trace.at,
+            invoke: undefined,
+            correlationId: m.messageId,
+            owner: owner.sessionId,
+            fingerprint,
+            handler,
+            handlerName: parts.handler,
+            queueClass: handler.queue ?? "default",
+            resources: [],
+            dedupeKey,
+            input: structuredClone(parts.input),
+            view: { ...snapshot, sequence: 1 },
+            controller: new AbortController(),
+            done,
+            resolve,
+            listeners: new Set(),
+            notifications: [],
+            dispatching: false,
+            sourceSequence: 0,
+            created: Date.now(),
+            messages: new Map([[m.messageId, hashMessage(m)]]),
+        };
+        this.entries.set(key, e);
+        this.retainedResultBytes += resultBytes;
+        this.telemetry.record(e.trace, "accepted");
+        this.telemetry.record(e.trace, "unique_reused");
+        e.resolve(snapshot);
+        return e;
+    }
+    releaseResources(e) {
+        for (const resource of e.resources)
+            if (this.resourceLocks.get(resource) === e)
+                this.resourceLocks.delete(resource);
+    }
+    /** 优先类别表按自有属性查；未知类别回退 default 权重，避免原型链 NaN。 */
+    classRank(queueClass) {
+        const order = this.scheduler.queueClassOrder;
+        return Object.hasOwn(order, queueClass) ? order[queueClass] : 3;
+    }
+    /** 当前阻塞来源：Handler 舱壁优先于资源锁；undefined 表示可运行。 */
+    blockedBy(e) {
+        const limit = e.handler.maxConcurrency;
+        if (limit !== undefined &&
+            (this.runningByHandler.get(e.handler) ?? 0) >= limit)
+            return "bulkhead";
+        for (const resource of e.resources)
+            if (this.resourceLocks.has(resource))
+                return "resource";
+        return undefined;
+    }
+    /** 是否有空闲槽位供此 Entry 开始执行（Handler 舱壁 + 资源互斥）。 */
+    eligible(e) {
+        return this.blockedBy(e) === undefined;
+    }
+    /** 类别优先级 + 等待老化：等待越久提升越多（不封顶），最低到 0；
+     *  同分时按队列先后（FIFO）决出，避免低优先类别饥饿。 */
+    effectivePriority(e, now) {
+        const boost = Math.floor(Math.max(0, now - e.trace.at) / this.scheduler.queueAgingMs);
+        return Math.max(0, this.classRank(e.queueClass) - boost);
+    }
+    /** 对已到期的排队任务结算 QUEUE_WAIT_TIMEOUT，再从队列移除。 */
+    expireQueued(now) {
+        for (const e of [...this.queue]) {
+            if (e.view.state !== "queued") {
+                this.removeQueued(e);
+                continue;
+            }
+            if (e.deadline !== undefined && now >= e.deadline) {
+                this.removeQueued(e);
+                this.finish(e, "failed", undefined, "QUEUE_WAIT_TIMEOUT");
+            }
+        }
+    }
     attachment(e, onEvent, id, reused = false) {
         // 每次附着独立占配额，即使调用方复用同一个回调。
         const listener = onEvent ? (event) => onEvent(event) : undefined;
@@ -306,7 +550,7 @@ export class ExecutionBus {
             throw Error(ERRORS.INVALID_CONTROL);
         this.sweep();
         const e = this.get(owner, m.requestId);
-        const previous = e.messages.get(m.messageId), fingerprint = canonical(m);
+        const previous = e.messages.get(m.messageId), fingerprint = hashMessage(m);
         if (previous && previous !== fingerprint)
             throw Error(ERRORS.MESSAGE_CONFLICT);
         if (!previous) {
@@ -349,8 +593,12 @@ export class ExecutionBus {
             waitReason: e.view.state === "queued"
                 ? this.running >= this.options.concurrency
                     ? "concurrency"
-                    : "dispatch"
+                    : (this.blockedBy(e) ?? "dispatch")
                 : null,
+            longRunning: e.view.state === "running" &&
+                e.startedAt !== undefined &&
+                (e.finishedAt ?? now) - e.startedAt >=
+                    this.scheduler.longRunningMs,
             phase: isTerminal(e.view.state)
                 ? e.view.delivery === "returned"
                     ? "returned"
@@ -393,6 +641,11 @@ export class ExecutionBus {
     finish(e, state, result, error, resultBytes = 0) {
         if (isTerminal(e.view.state))
             return;
+        this.releaseResources(e);
+        if (e.dedupeKey !== undefined &&
+            this.dedupeIndex.get(e.dedupeKey) === e &&
+            state !== "succeeded")
+            this.dedupeIndex.delete(e.dedupeKey);
         if (e.queueTimer !== undefined) {
             clearTimeout(e.queueTimer);
             e.queueTimer = undefined;
@@ -435,44 +688,66 @@ export class ExecutionBus {
         if (!e.dispatching)
             e.listeners.clear();
     }
-    /** 按会话轮转挑选下一个出队项：各会话内部 FIFO，跨会话公平。 */
-    nextQueuedIndex() {
-        let index = -1;
-        while (this.readyOwners.length && index < 0) {
+    /** 按会话轮转选择下一个可执行项：会话内按类别优先级 + 老化，跨会话公平。 */
+    nextQueuedIndex(now) {
+        const owners = this.readyOwners.length;
+        for (let n = 0; n < owners; n++) {
             const owner = this.readyOwners.shift();
-            const i = this.queue.findIndex((entry) => entry.owner === owner);
-            if (i >= 0) {
-                index = i;
-                // 找到后，若该会话仍有其它排队任务，保留其轮次避免单个会话饥饿。
-                if (this.queue.some((entry, j) => j !== i && entry.owner === owner))
+            let chosen = -1;
+            let chosenScore = Infinity;
+            for (let i = 0; i < this.queue.length; i++) {
+                const e = this.queue[i];
+                if (e.owner !== owner || !this.eligible(e))
+                    continue;
+                const score = this.effectivePriority(e, now);
+                if (score < chosenScore) {
+                    chosen = i;
+                    chosenScore = score;
+                }
+            }
+            if (chosen < 0) {
+                // 该会话暂时全部被舱壁/资源阻塞；保留轮次，等释放后重新争取。
+                if (this.queue.some((entry) => entry.owner === owner))
                     this.readyOwners.push(owner);
+                continue;
             }
+            if (this.queue.some((entry, i) => i !== chosen && entry.owner === owner))
+                this.readyOwners.push(owner);
+            return chosen;
         }
-        return index < 0 ? 0 : index;
+        return -1;
     }
     pump() {
-        while (!this.closed &&
-            this.running < this.options.concurrency &&
-            this.queue.length) {
-            const index = this.nextQueuedIndex();
+        while (!this.closed) {
+            const now = performance.now();
+            this.expireQueued(now);
+            if (this.running >= this.options.concurrency || this.queue.length === 0)
+                return;
+            const index = this.nextQueuedIndex(now);
+            if (index < 0)
+                return;
             const e = this.queue.splice(index, 1)[0];
             if (e.view.state !== "queued")
                 continue;
-            if (e.deadline !== undefined && performance.now() >= e.deadline) {
-                this.finish(e, "failed", undefined, "QUEUE_WAIT_TIMEOUT");
-                continue;
-            }
             if (e.queueTimer !== undefined) {
                 clearTimeout(e.queueTimer);
                 e.queueTimer = undefined;
             }
             e.startedAt = performance.now();
             this.running++;
+            this.runningByHandler.set(e.handler, (this.runningByHandler.get(e.handler) ?? 0) + 1);
+            for (const resource of e.resources)
+                this.resourceLocks.set(resource, e);
             e.view.state = "running";
             this.telemetry.record(e.trace, "started");
             this.emit(e, "started", {});
             void this.run(e).finally(() => {
                 this.running--;
+                const remaining = (this.runningByHandler.get(e.handler) ?? 1) - 1;
+                if (remaining > 0)
+                    this.runningByHandler.set(e.handler, remaining);
+                else
+                    this.runningByHandler.delete(e.handler);
                 this.pump();
             });
         }
@@ -545,6 +820,9 @@ export class ExecutionBus {
             await Promise.all(entries.map((e) => e.done));
             this.handlers.clear();
             this.entries.clear();
+            this.dedupeIndex.clear();
+            this.resourceLocks.clear();
+            this.runningByHandler.clear();
             this.retainedResultBytes = 0;
             this.queue = [];
             this.readyOwners = [];

package/dist/diagnostics.d.ts

@@ -1,4 +1,4 @@
-export type TraceStage = "accepted" | "started" | "cancel_requested" | "terminal" | "returned" | "job_created" | "job_released" | "job_error" | "reused";
+export type TraceStage = "accepted" | "started" | "cancel_requested" | "terminal" | "returned" | "job_created" | "job_released" | "job_error" | "reused" | "unique_reused";
 export interface Trace {
     operation: number;
     stage: TraceStage;
@@ -30,6 +30,7 @@ export declare class Diagnostics {
             job_released?: number | undefined;
             job_error?: number | undefined;
             reused?: number | undefined;
+            unique_reused?: number | undefined;
         };
         traces: {
             operation: number;

package/dist/error-codes.d.ts

@@ -38,6 +38,8 @@ export declare const ERRORS: Readonly<{
     INVALID_OPTIONS: "INVALID_OPTIONS";
     DUPLICATE_HANDLER: "DUPLICATE_HANDLER";
     MUTATING_REUSE_DENIED: "MUTATING_REUSE_DENIED";
+    INVALID_HANDLER_OPTIONS: "INVALID_HANDLER_OPTIONS";
+    INVALID_RESOURCES: "INVALID_RESOURCES";
     DUPLICATE_EXECUTION_HANDLE: "DUPLICATE_EXECUTION_HANDLE";
     INVALID_STATE_QUERY: "INVALID_STATE_QUERY";
     HOST_READ_FAILED: "HOST_READ_FAILED";

package/dist/error-codes.js

@@ -41,6 +41,8 @@ export const ERRORS = Object.freeze({
     INVALID_OPTIONS: "INVALID_OPTIONS",
     DUPLICATE_HANDLER: "DUPLICATE_HANDLER",
     MUTATING_REUSE_DENIED: "MUTATING_REUSE_DENIED",
+    INVALID_HANDLER_OPTIONS: "INVALID_HANDLER_OPTIONS",
+    INVALID_RESOURCES: "INVALID_RESOURCES",
     // —— 宿主投影（execution / plugin） ——
     DUPLICATE_EXECUTION_HANDLE: "DUPLICATE_EXECUTION_HANDLE",
     INVALID_STATE_QUERY: "INVALID_STATE_QUERY",

package/dist/execution.d.ts

@@ -49,6 +49,7 @@ export declare class ExecutionOwner {
             job_released?: number | undefined;
             job_error?: number | undefined;
             reused?: number | undefined;
+            unique_reused?: number | undefined;
         };
         traces: {
             operation: number;

package/dist/handlers.d.ts

@@ -5,9 +5,15 @@ export declare function hostToolHandler(toolName: string, opts: {
     idempotent: boolean;
     validate(input: Record<string, unknown>): void;
     prepare?(input: Record<string, unknown>): Record<string, unknown>;
+    queue?: string;
+    maxConcurrency?: number;
+    resources?(input: Record<string, unknown>): readonly string[];
+    dedupe?: "payload";
 }): Handler;
 export declare const testHandler: Handler;
-/** 读取：无副作用，幂等，终态结果可复用。 */
+/** 读取：无副作用，幂等，终态结果可复用。0.12.1 起内置 host.* 不再声明
+ *  payload 去重：文件/权限/工作目录会变化，缓存旧结果会静默返回过期内容。
+ *  扩展 Handler 可自行声明 dedupe 并承担失效责任。 */
 export declare const readHandler: Handler;
 /** 文件名搜索：只读，幂等，终态结果可复用；搜索基数由宿主工具限制。 */
 export declare const globHandler: Handler;

package/dist/handlers.js

@@ -8,6 +8,10 @@ export function hostToolHandler(toolName, opts) {
     void toolName;
     return {
         idempotent: opts.idempotent,
+        queue: opts.queue,
+        maxConcurrency: opts.maxConcurrency,
+        resources: opts.resources,
+        dedupe: opts.dedupe,
         validate: opts.validate,
         async run(input, ctx) {
             if (!ctx.invoke)
@@ -18,6 +22,7 @@ export function hostToolHandler(toolName, opts) {
 }
 export const testHandler = {
     idempotent: true,
+    queue: "diagnostic",
     validate(input) {
         if (Object.keys(input).some((k) => !["delayMs", "fail"].includes(k)) ||
             !Number.isSafeInteger(input.delayMs) ||
@@ -61,9 +66,17 @@ function validateEdit(input) {
         (input.replace_all !== undefined && typeof input.replace_all !== "boolean"))
         throw Error(ERRORS.INVALID_EDIT_INPUT);
 }
-/** 读取：无副作用，幂等，终态结果可复用。 */
+/** 同一路径的文件写入/编辑互斥；路径按调用原文作为资源键（不做跨平台归一化，
+ *  因此别名写法可能绕过互斥；见 docs/validation.md）。 */
+function fileResource(input) {
+    return ["file:" + String(input.file_path)];
+}
+/** 读取：无副作用，幂等，终态结果可复用。0.12.1 起内置 host.* 不再声明
+ *  payload 去重：文件/权限/工作目录会变化，缓存旧结果会静默返回过期内容。
+ *  扩展 Handler 可自行声明 dedupe 并承担失效责任。 */
 export const readHandler = hostToolHandler("read", {
     idempotent: true,
+    queue: "fs",
     validate: validateRead,
     prepare: (input) => ({
         ...input,
@@ -81,6 +94,7 @@ function validateGlob(input) {
 /** 文件名搜索：只读，幂等，终态结果可复用；搜索基数由宿主工具限制。 */
 export const globHandler = hostToolHandler("glob", {
     idempotent: true,
+    queue: "fs",
     validate: validateGlob,
 });
 function validateGrep(input) {
@@ -111,6 +125,7 @@ function validateGrep(input) {
 /** 内容搜索：只读，幂等，终态结果可复用；匹配上限由宿主工具限制。 */
 export const grepHandler = hostToolHandler("grep", {
     idempotent: true,
+    queue: "fs",
     validate: validateGrep,
 });
 function validateWrite(input) {
@@ -124,11 +139,15 @@ function validateWrite(input) {
 /** 写入：有副作用，非幂等，终态结果不可复用。 */
 export const writeHandler = hostToolHandler("write", {
     idempotent: false,
+    queue: "fs",
+    resources: fileResource,
     validate: validateWrite,
 });
 /** 编辑：有副作用，非幂等，终态结果不可复用。 */
 export const editHandler = hostToolHandler("edit", {
     idempotent: false,
+    queue: "fs",
+    resources: fileResource,
     validate: validateEdit,
 });
 /** 与宿主 pwsh 工具一致的提权目标；沙箱组合未提供提权面时由宿主拒绝。 */
@@ -170,5 +189,6 @@ function validatePwsh(input) {
 /** 命令执行：有副作用，非幂等，终态结果不可复用；后台模式返回 Job ID 不等于完成。 */
 export const pwshHandler = hostToolHandler("pwsh", {
     idempotent: false,
+    queue: "command",
     validate: validatePwsh,
 });

package/dist/product.d.ts

@@ -23,6 +23,12 @@ export declare const HANDLER_LIMITS: Readonly<{
     readPathChars: 2048;
     diagnosticDelayMs: 30000;
 }>;
+/** 调度策略：类别优先级 + 等待老化 + 长任务诊断阈值。 */
+export declare const SCHEDULER_POLICY: Readonly<{
+    longRunningMs: 30000;
+    queueAgingMs: 30000;
+    queueClassOrder: Readonly<Record<string, number>>;
+}>;
 export declare const REQUEST_PARAMETERS: {
     readonly oneOf: readonly [...{
         type: "object";

package/dist/product.js

@@ -23,6 +23,17 @@ export const HANDLER_LIMITS = Object.freeze({
     readPathChars: 2048,
     diagnosticDelayMs: 30000,
 });
+/** 调度策略：类别优先级 + 等待老化 + 长任务诊断阈值。 */
+export const SCHEDULER_POLICY = Object.freeze({
+    longRunningMs: 30000,
+    queueAgingMs: 30000,
+    queueClassOrder: Object.freeze({
+        fs: 0,
+        diagnostic: 1,
+        command: 2,
+        default: 3,
+    }),
+});
 /** 每个 Handler 的模型可见输入声明。只用于工具 schema/SDK 生成；运行时仍由 Handler.validate 严格校验。 */
 const INPUT_SCHEMAS = {
     test: {

package/dist/protocol.d.ts

@@ -24,6 +24,17 @@ export interface Handler {
     /** 是否可安全复用终态结果。省略默认 true（可复用，向后兼容）；
      *  显式 false = 有副作用，终态结果复用将被拒绝（运行中等待仍放行）。 */
     readonly idempotent?: boolean;
+    /** 调度队列类别；默认按 "default"。不同类别之间按类别优先级 + 等待老化排序，
+     *  避免长任务类独占出队顺序。 */
+    readonly queue?: string;
+    /** 同一 Handler 同时在跑的上限；省略表示只受全局并发限制（舱壁）。 */
+    readonly maxConcurrency?: number;
+    /** 可选资源键（如文件路径）：同键请求在总线内互斥，避免并发写同一资源。
+     *  由 Handler 在执行前从输入推导；返回空数组表示不占用资源。 */
+    resources?(input: Record<string, unknown>): readonly string[];
+    /** 唯一任务策略："payload" 表示幂等只读 Handler 可按 handler+input 指纹复用
+     *  已成功的终态结果（不同 requestId）；省略表示只按 requestId 去重。 */
+    readonly dedupe?: "payload";
     validate(input: Record<string, unknown>): void;
     run(input: Record<string, unknown>, ctx: {
         signal: AbortSignal;

package/docs/INTEGRATION.md

@@ -1,4 +1,4 @@
-# 同类项目源码参考与整合（0.5.0）
+# 同类项目源码参考与整合（0.5.0–0.12.1）
 
 ## 本轮交付
 
@@ -21,6 +21,33 @@
 | [cc-multi-process-mcp / 234823f1](https://github.com/L-x-C/cc-multi-process-mcp/tree/234823f15616d7e9c759072e940396d939f823c2) | main.py 的进程检测、信号回收、同步/异步执行、结果文件和清理路径 | 不引入自建进程池或轮询。源码的 skip_permissions 默认和 /tmp 存储不适合本插件宿主边界；未发现 LICENSE 文件，不复制代码 |
 
 这是相关路径的定向阅读，不是五仓全量逐文件安全审核。参考快照在开发目录，明确忽略，不进入源码提交或 npm 包。
+## 0.12.0 追加整合：调度隔离、资源互斥、唯一任务与属性测试
+
+本轮以 0.11.3 为基线，读取以下公开文档/README（2026-10-18，文档站点与仓库链接；未复制源码，未新增运行依赖），只采用与插件边界相符的机制：
+
+| 来源 | 实际阅读内容 | 采用与不采用 |
+|---|---|---|
+| [Temporal Workflow Id / Reuse Policy](https://docs.temporal.io/workflow-execution/workflowid-runid) | Workflow Id 唯一性、Run Id 区分、关闭后复用策略 | 参考“稳定逻辑编号 + 复用策略”分层；不引入持久化运行历史 |
+| [Restate 文档](https://docs.restate.dev/)（BUSL-1.1，仅文档） | exactly-once、按 scope 的并发/流量控制、virtual object 串行化 | 参考“按类别/资源隔离并发”；不复制代码，不引入其运行时 |
+| [DBOS 文档](https://docs.dbos.dev/) | durable queues、exactly-once、事务入队 | 仅对照边界；无持久化宿主契约，不实现 |
+| [Oban 文档](https://oban.hexdocs.pm/Oban.html)（Apache-2.0） | 队列独立并发上限、唯一任务、10 级优先级 | 实现 Handler.queue 类别 + 优先级 + 等待老化；不引入数据库/自动重试 |
+| [BullMQ README](https://github.com/taskforcesh/bullmq)（MIT） | priorities、concurrency、rate limiter、stalled jobs | 参考优先级/舱壁；不引入 Redis/停滞重排 |
+| [Resilience4j README](https://github.com/resilience4j/resilience4j)（Apache-2.0） | Bulkhead、TimeLimiter | 实现 Handler.maxConcurrency 舱壁；超时暂只做 longRunning 诊断 |
+| [fast-check](https://github.com/dubzzz/fast-check)（MIT，devDependency） | 属性测试 API | 新增随机序列不变量回归；仅开发依赖，不进入 tgz |
+
+本轮实现（0.12.0）：
+
+1. Handler 调度声明：queue、maxConcurrency、resources(input)、dedupe:"payload"；register 时校验。
+2. 调度：同会话内按类别优先级（fs < diagnostic < command < default）+ 等待老化（每 30 秒提升一级，不封顶，最低到 0）选择；跨会话仍按会话轮转；Handler.maxConcurrency 作为舱壁。0.12.1 修正老化封顶导致的 default 类饥饿。
+3. 资源互斥：Handler.resources 返回稳定字符串键（host.edit/host.write 使用 file:<file_path>）；同一总线实例内同键串行，失败/取消/关闭释放；排队期限仍然有效。
+4. 唯一任务：幂等 Handler 声明 dedupe:"payload"（host.read/glob/grep）；同会话同 handler+payload 已有 succeeded 终态时，新 requestId 直接复用快照并带 reused:true；失败结果不缓存。
+5. 诊断：execution_bus_state 任务增加 longRunning（30 秒阈值）；waitReason 增加 resource。
+6. 测试：新增 8 项调度/唯一/资源回归、2 项 fast-check 属性回归与 2 项插件级 Handler 回归。
+
+不采用：Oban/BullMQ 的数据库/Redis 持久化、自动重试、停滞重排；Temporal/DBOS 的持久化执行与跨重启恢复（缺宿主契约）；Restate 源码（BUSL-1.1）。资源互斥仅在单个总线实例内有效，不是 OS 文件锁或跨进程保证。
+
+许可：本轮未复制第三方源码；fast-check 作为 devDependency 使用（MIT），不进入 tgz；Restate 文档仅作机制参考（BUSL-1.1）。
+
 
 ## 许可与实现归属
 

package/docs/OPTIMIZATION.md

@@ -1,5 +1,7 @@
 # 引擎经验优化整合与验收
 
+> 历史文档：本页记录 0.4.0 的优化。其中“按资源串行”当时暂缓，已在 0.12.0 以 Handler.resources + 资源锁实现（见 [整合说明](<INTEGRATION.md>) 与 [0.12.1 发布说明](<releases/0.12.1.md>)）；冲突时以 README/protocol 与当前发布说明为准。
+
 本轮统一在 0.4.0 交付，不将普通 BUG 修复冒充整体架构优化，不声称模型性能已提高。运行逻辑仅作用于萧何总线及其 Job 关联；保留 0.3.0 的 PTC 派生方式、权限和原工具能力。
 
 ## 优先级与交付

package/docs/PRODUCT.md

@@ -12,6 +12,10 @@
 
 0.11.0 根据 pilot 收紧为收益导向触发：重复提交/重试去重、预算结束后继续/跨步骤取回、多等待者同一执行才用总线，时长本身不是理由；新增简化调用（requestId+handler+input，messageId 自动生成）与控制（requestId+type），完整 v1 消息仍兼容；快照在复用时带 reused:true，并新增只读的会话采用率统计脚本。
 
+0.12.0 补充调度隔离：Handler 可声明调度类别、舱壁、资源键与 payload 唯一任务；内置写 Handler 按文件路径互斥；状态快照增加 longRunning 与等待原因。参考来源与许可见 [整合说明](<INTEGRATION.md>)，未引入第三方运行依赖；fast-check 仅用于开发属性测试。
+
+0.12.1 修正 0.12.0 的默认行为风险：内置 host.* 关闭 payload 去重（文件/权限/工作目录变化后旧结果会静默过期），只保留核心 Handler 能力供扩展自担失效责任；等待老化不封顶，避免 default 类别饥饿；唯一复用副本计入保留字节并写入时间戳；waitReason 区分 bulkhead 与 resource；注册时校验并冻结调度选项、拒绝 accessor/原型污染键；validate/resources 内同步 close 后不再插入不可结算记录；消息身份改存摘要，降低同 requestId 多条消息的内存占用。
+
 ## 入口及配置层次
 
 | 入口 | 谁使用 | 责任 |

package/docs/protocol.md

@@ -28,8 +28,8 @@
 
 ### 去重与消息额度
 
-- 逻辑键是 **当前存活总线实例 + 宿主会话身份 + requestId**。不同会话不能查询/取消彼此记录；同预设仍共享容量。
-- 对参数规范排序后的摘要仅用于同 requestId 的冲突比较，不用于永久按参数去重。相同参数的新 requestId 仍是新操作。
+- 逻辑键是 **当前存活总线实例 + 宿主会话身份 + requestId**。不同会话不能查询/取消彼此记录；同一预设修订（generation）的会话共享总线容量。
+- 对参数规范排序后的摘要仅用于同 requestId 的冲突比较，不用于永久按参数去重。相同参数的新 requestId 默认仍是新操作；仅显式声明 `dedupe:"payload"` 的幂等 Handler 可复用同会话已成功的 payload 结果（0.12.1 起内置 host.* 不声明）。
 - 普通消息最多记账 128 条，含首次请求、重复请求及查询。满后拒绝普通新消息；首次尚未确认的有效取消可使用一个额外控制槽，最多 129 条。已记账消息的冲突检查不因控制槽而放松。
 - 活跃观察者附着最多 32 个；每个附着独立占名额，即使共用回调。附着被拒绝时不占用新消息编号/额度。
 - 终态超期清理后旧请求键失效，不应把此机制用于长期避免外部副作用重复。
@@ -110,7 +110,7 @@ core 不传配置时用默认值；显式配置必须完整包含 concurrency、
 
 期限使用单调时钟，计时器及出队前均检查，超期只将 queued 结算 failed / QUEUE_WAIT_TIMEOUT，不调用 Handler、不设置 cancelRequested、不重试，沿原 done/Job 返回。开始运行、取消或关闭时清除计时器。事件循环繁忙会令通知晚于期限，但不会让超期任务出队执行。已运行任务继续遵守原执行/取消规则。
 
-execution_bus_state 工具仅接受 {}，从宿主 Agent 取 sessionId，拒绝匿名或自报身份，关闭后拒绝查询。它读取 core inspect 的不可变快照，不创建 Job、不改变消息额度；查询会做正常终态 TTL 清理。不包含输入/输出，不访问其他会话。最多 50 条、活跃优先，其后按受理次序倒序列出终态；总数未截断，truncated 提示列表截断。元数据含 requestId、state、delivery、cancelRequested、固定 error/progress、waitReason、queueMs/runMs/remainingQueueMs。phase terminal 只表示执行终态且尚未标记返回，不代表可推断宿主 Job 清理进度。
+execution_bus_state 工具仅接受 {}，从宿主 Agent 取 sessionId，拒绝匿名或自报身份，关闭后拒绝查询。它读取 core inspect 的不可变快照，不创建 Job、不改变消息额度；查询会做正常终态 TTL 清理。不包含输入/输出，不访问其他会话。最多 50 条、活跃优先，其后按受理次序倒序列出终态；总数未截断，truncated 提示列表截断。元数据含 requestId、state、delivery、cancelRequested、固定 error/progress、waitReason（concurrency/bulkhead/resource/dispatch）、longRunning（运行超过 30 秒）、queueMs/runMs/remainingQueueMs。phase terminal 只表示执行终态且尚未标记返回，不代表可推断宿主 Job 清理进度。
 
 core inspect(trustedOwner) 要求非空 sessionId，但不提供鉴权，可信身份和访问控制属于嵌入宿主。勿把 core 的任意 owner 参数直接暴露给远端。状态不是持久审计/模型消费回执，不应循环调用。
 
@@ -128,4 +128,21 @@ core 实例的 `diagnostics()` 返回只读用途的独立快照：阶段计数
 
 0.11.0 起，模型可传简化输入：请求 `{requestId, handler, input, messageId?}`、控制 `{requestId, type, messageId?}`；插件在进入总线前补齐完整 v1 消息，完整 v1 消息仍被接受。返回快照在附着已有执行时追加可选 `reused:true`，只表示复用了逻辑执行，不代表外部副作用对账。
 
+0.12.0 扩展 Handler 可选声明：`queue`（调度类别，内置 fs/diagnostic/command）、`maxConcurrency`（同一 Handler 舱壁）、`resources(input)`（资源键串行）、`dedupe:"payload"`（幂等 Handler 的唯一任务复用）。调度和资源锁按总线实例生效；插件实例由同一预设修订（generation）的会话共享，跨进程/跨代际不保证。资源键是调用方提供的字符串，不是 OS 文件锁。唯一任务只复用 succeeded 终态，失败/取消/unknown 不缓存；命中时返回快照带 `reused:true`，且不会再次执行 Handler。
+
+0.12.1 起内置 host.read/host.glob/host.grep **不再声明** `dedupe:"payload"`：文件、权限或工作目录变化后缓存结果可能过期，扩展 Handler 如声明该能力需自行承担失效责任。同时 `waitReason` 区分 `bulkhead`（Handler 舱壁）与 `resource`（资源锁）。
+
 内置 test、host.read、host.glob 与 host.grep 没有副作用；host.edit、host.write 与 host.pwsh 是非幂等写/命令 Handler，通过 `Handler.idempotent=false` 显式声明，其终态结果复用被 `MUTATING_REUSE_DENIED` 拒绝，运行中的重复附着仍只等待同一执行。0.8.0 新增宿主工具输入错误码 INVALID_GLOB_INPUT、INVALID_GREP_INPUT 与 INVALID_PWSH_INPUT；协议既有错误码不改名。host.pwsh 的后台结果只是宿主 Job ID，不是完成回执。当前没有 ctx.executionBus 服务、远端传输、跨插件动态注册或外部副作用对账契约。扩展有副作用 Handler 前必须显式声明幂等并另行设计授权与崩溃对账，不能仅依赖本版请求键。
+
+
+## 9. 错误词汇（0.12.1 补录）
+
+错误码值即协议 v1 稳定词汇，不得重命名；完整定义见 `src/error-codes.ts`。
+
+- 协议解析：`INVALID_OBJECT`、`UNKNOWN_FIELD`、`UNSUPPORTED_VERSION`、`INVALID_ID`、`UNSUPPORTED_TYPE`、`MESSAGE_TOO_LARGE`。
+- 严格 JSON：`JSON_LIMIT`、`INVALID_JSON`、`CYCLIC_JSON`、`INVALID_JSON_ARRAY`、`INVALID_JSON_OBJECT`、`INVALID_JSON_KEY`、`INVALID_JSON_PROPERTY`。
+- 总线调度与准入：`CLOSED`、`EXPECTED_REQUEST`、`INVALID_REQUEST`、`REQUEST_CONFLICT`、`MESSAGE_CONFLICT`、`MESSAGE_LIMIT`、`UNKNOWN_HANDLER`、`BACKPRESSURE`、`SESSION_BACKPRESSURE`、`WAITER_LIMIT`、`EXPECTED_CONTROL`、`INVALID_CONTROL`、`NOT_FOUND`、`UNTRUSTED_CONTEXT`、`OWNING_SESSION_REQUIRED`、`QUEUE_WAIT_TIMEOUT`、`RESULT_NOT_RETAINED`、`CANCELLED`、`CANCELLATION_UNCONFIRMED`、`HANDLER_FAILED`、`INVALID_ADMISSION_POLICY`、`INVALID_OPTIONS`、`DUPLICATE_HANDLER`、`MUTATING_REUSE_DENIED`、`INVALID_HANDLER_OPTIONS`、`INVALID_RESOURCES`。
+- 宿主投影：`DUPLICATE_EXECUTION_HANDLE`、`INVALID_STATE_QUERY`、`HOST_READ_FAILED`、`HOST_TOOL_FAILED`、`HOST_JOB_UNAVAILABLE`。
+- 预设派生：`PTC_PRESET_TOO_LARGE`、`PTC_PRESET_ALREADY_CONTAINS_BUS`、`PTC_PRESET_RELATIVE_BASE_UNSUPPORTED`、`PTC_PRESET_UNAVAILABLE`。
+- 内置 Handler：`INVALID_TEST_INPUT`、`INVALID_READ_INPUT`、`INVALID_EDIT_INPUT`、`INVALID_WRITE_INPUT`、`INVALID_GLOB_INPUT`、`INVALID_GREP_INPUT`、`INVALID_PWSH_INPUT`、`READ_LIMIT`、`CONTROLLED_FAILURE`、`HOST_CAPABILITY_REQUIRED`。
+

package/docs/releases/0.11.1.md

@@ -1,5 +1,7 @@
 # 萧何 / Xiao He 0.11.1
 
+> **未发布版本**：本标签 CI 在 windows-latest + Node 22 上因真实 PTC 预算用例时序失败，未发布到 npm/GitHub；其提示与文档修正并入 [0.11.2](<0.11.2.md>)。保留本文仅用于历史追溯。
+
 ## 修正跨步骤取回说明（pilot 发现）
 
 本版只修正提示与文档，不改变执行机制。

package/docs/releases/0.12.0.md

@@ -0,0 +1,20 @@
+# 萧何 / Xiao He 0.12.0
+
+## 调度隔离、资源互斥与唯一任务（开源机制整合）
+
+本版把一组调度/可靠性机制收敛进总线。参考来源、实际阅读范围与许可见 [整合说明](<../INTEGRATION.md>)；本轮未复制第三方源码、未新增运行依赖。
+
+- **Handler 调度声明**：新增可选 `queue`（类别）、`maxConcurrency`（舱壁）、`resources(input)`（资源键）、`dedupe:"payload"`（唯一任务）；注册时校验（`INVALID_HANDLER_OPTIONS`/`INVALID_RESOURCES`）。
+- **调度**：同会话内按类别优先级（fs < diagnostic < command < default）+ 等待老化（每 30 秒削平一级，最多两级）选择；跨会话仍按会话轮转；`maxConcurrency` 限制同一 Handler 并发。排队期限、取消、关闭与结果语义不变。
+- **资源互斥**：`host.edit`/`host.write` 以 `file:<file_path>` 为资源键，在同一总线实例内串行执行；失败/取消/关闭释放资源；排队期限继续生效。**不是 OS 文件锁或跨进程保证。**
+- **唯一任务**：`host.read`/`host.glob`/`host.grep` 声明 payload 去重；同会话同 handler+input 已有 `succeeded` 终态时，新 requestId 直接复用快照并返回 `reused:true`，不重复执行 Handler；失败/取消/unknown 不缓存。
+- **诊断**：`execution_bus_state` 任务增加 `longRunning`（运行超过 30 秒）；`waitReason` 增加 `resource`。
+- **开发验证**：新增 8 项调度/唯一/资源回归、2 项 fast-check 属性回归与 2 项插件级 Handler 回归；全量 **122** 项测试通过。fast-check 仅 devDependency（MIT），不进入 tgz。
+
+## 升级说明
+
+需要 DSH 0.2.1-rc.2。wire 协议与工具调用形状不变；新增能力只在 core/Handler 层，宿主预设、工具名与既有错误码不变。默认调度对内置 Handler 生效（类别优先级与文件互斥），如需完全旧行为应自行评估 effect。不自动安装、重写日常配置或重启 DSH。
+
+## 验证与限制
+
+本地全量 122 项测试通过；属性测试固定种子，不是穷尽证明。调度与资源锁只在单个总线实例内；跨会话/跨进程/OS 级互斥、外部副作用对账、持久化与自动重试均未实现。真实模型、桌面 UI 与实际沙箱仍未完整验收。

package/docs/releases/0.12.1.md

@@ -0,0 +1,30 @@
+# 萧何 / Xiao He 0.12.1
+
+## 0.12.0 行为风险热修
+
+本版修正 0.12.0 默认 payload 去重导致的数据正确性问题，并处理同轮审查发现的高优先级调度/生命周期/文档缺陷。**wire 协议与工具调用形状不变。**
+
+## 修正
+
+- **关闭内置 host.* 的 payload 去重**：0.12.0 给 `host.read`/`host.glob`/`host.grep` 默认声明了 `dedupe:"payload"`。文件被编辑、会话切换工作目录或权限变化后，同输入的新 requestId 会静默返回旧内容（现场已复现：read 记 v1 → write 改 v2 → 再 read 仍返回 v1）。0.12.1 起内置 Handler 不再声明该能力，恢复“相同参数的新 requestId 是新操作”；核心 `Handler.dedupe` 能力保留，扩展 Handler 如声明须自行承担失效责任。
+- **等待老化不封顶**：原 `boost=min(2,...)` 削不平 default(3) 与 fs(0) 的差距，持续 fs 负载下 default 类可饥饿/必超时；改为按等待时间持续提升、最低到 0，同分按 FIFO。
+- **唯一复用记录计入保留字节与时间戳**：`syntheticUnique` 深拷贝结果但 `resultBytes=0`，且无 startedAt/finishedAt 导致 `queueMs` 随保留期增长；现按结果字节计入、写入时间戳，sweep/close 正常递减。
+- **waitReason 区分舱壁与资源**：新增 `bulkhead`，不再把 Handler.maxConcurrency 等待误报为 `resource`。
+- **注册时校验并快照 Handler 选项**：校验 run/validate 为函数、idempotent 严格布尔、queue/dedupe 合法；冻结调度字段并拒绝 `__proto__` 等类名，避免运行期篡改、NaN 优先级和永不调度；scheduler 策略拒绝 accessor 与原型污染键，数值只读取一次后校验。
+- **关闭重入**：validate/resources 同步执行中触发 `close()` 后不再向已关闭总线插入永不结算的记录，改为拒绝准入（CLOSED）。
+- **消息身份改存 SHA-256 摘要**：同一 requestId 多条消息不再保存完整 canonical 文本，避免消息额度内无字节上限的内存放大；冲突检测语义等价。
+- **文档修正**：protocol 恢复“新 requestId 新操作”并补错误词汇表；validation 更新 PTC 预算参数（8s/12s）、资源互斥跨会话范围（同一预设修订共享，跨进程/跨代际不保证）、修正 0.12.0 发布说明中的范围表述；0.11.1 标注“未发布”；OPTIMIZATION 标注历史并链接当前实现；INTEGRATION 标题与老化说明同步。
+
+## 验证
+
+- 新增 6 项回归：default 类老化不饥饿、bulkhead/resource 等待原因、注册负例、scheduler accessor/原型污染、关闭重入、唯一复用字节/时间戳、资源锁失败/取消释放。
+- 本地全量测试通过（122 + 6 = 128 项；以 `npm run check` 实际输出为准）。
+- 未复制第三方源码、未新增运行依赖；fast-check 仍仅为 devDependency。
+
+## 升级说明
+
+需要 DSH 0.2.1-rc.2。工具名、wire 协议与既有错误码不变；行为变更仅影响内置 host.* 的 payload 去重（默认关闭）。旧版创建的总线实例/记录不迁移；重载或升级会创建新的预设修订，旧 requestId 不可取回。
+
+## 验证与限制
+
+调度与资源锁按预设修订共享总线实例，跨进程、跨代际、OS 级文件锁均不保证；资源键别名（相对/绝对、大小写）可能绕过互斥。真实模型、桌面 UI 与实际沙箱仍未完整验收。

package/docs/validation.md

@@ -1,6 +1,6 @@
 # 验证范围与使用限制
 
-本文说明当前版本的证据边界，不是生产环境认证。当前能力基线为 **v0.11.3**，在 0.5.0 的会话准入/排队、0.7.0 的宿主工具转发、0.8.0 的搜索/命令 Handler、0.9.0 的预算分离等待与 0.10.0 的采用面改造上，收紧为收益导向触发并加入简化调用、复用标记与本地采用率统计；0.11.1 补充跨步骤取回姿势，0.11.3 补记收益导向 vs 总线优先的指引级 A/B 证据；预设沿用 v0.3.0 的宿主 PTC 声明派生方式。验证环境为 Windows、Node.js 24.21.0，宿主组件锁定 DSH 0.2.1-rc.2、Cordis 4.0.4。
+本文说明当前版本的证据边界，不是生产环境认证。当前能力基线为 **v0.12.1**，在 0.5.0 的会话准入/排队、0.7.0 的宿主工具转发、0.8.0 的搜索/命令 Handler、0.9.0 的预算分离等待与 0.10.0 的采用面改造上，收紧为收益导向触发并加入简化调用、复用标记与本地采用率统计；0.11.1 补充跨步骤取回姿势，0.11.3 补记指引级 A/B 证据，0.12.0 加入调度类别/舱壁/资源互斥/唯一任务与属性测试，0.12.1 关闭内置 host.* 的 payload 去重并修正老化/字节计数/等待原因/注册校验/关闭重入问题；预设沿用 v0.3.0 的宿主 PTC 声明派生方式。验证环境为 Windows、Node.js 24.21.0，宿主组件锁定 DSH 0.2.1-rc.2、Cordis 4.0.4。
 
 ## 已验证什么？
 
@@ -9,9 +9,12 @@
 | 总线核心 | 参数、队列、并发、重复请求、冲突、取消竞争、结果保存、TTL、监听与注销 | 程序内部约束及已覆盖异常路径可重复检查 |
 | 真实宿主组件 | Cordis、ToolRuntime、LocalJobs、LocalFS、文件工具；host.glob/host.grep/host.pwsh 的转发测试使用宿主工具桩 | 请求经过真实工具管线；权限拒绝、Job 进度、共享任务、参数校验、幂等分流与清理逻辑有效；Agent 身份与工具实现为夹具，桩不证明真实搜索/命令工具实现 |
 | 真实会话循环 | AgentLoop、AgentRegistry、SessionStore；脚本模型适配器 | 内存会话中原工具结果只提交一次，完成后再进入下一次适配器调用 |
-| PTC 预算分离等待 | 真实 Node PTC `run_code` 以 2 秒预算等待 5 秒总线执行：预算到期后执行继续、宿主 Job 保留、同 requestId 取回结果；外部中断仍取消执行 | 在 DSH 0.2.1-rc.2 实际中断原因下成立；固定字符串不是跨版本契约 |
+| PTC 预算分离等待 | 真实 Node PTC `run_code` 以 8 秒预算等待 12 秒总线执行：预算到期后执行继续、宿主 Job 保留、同 requestId 取回结果；外部中断仍取消执行 | 在 DSH 0.2.1-rc.2 实际中断原因下成立；固定字符串不是跨版本契约 |
 | 简化调用与复用标记 | 简化请求/控制、完整 v1 消息兼容、终态与运行中复用返回 `reused:true`、非法形状拒绝 | 组件级测试确认；不改变 wire 语义与副作用边界 |
 | 采用策略 A/B（指引级） | 同一版本 0.11.2、同一模型、5 类任务各 5 个全新子会话：可选触发 vs 总线优先指引，统计总线调用/复用/耗时 | 指出可选触发更优（总线优先把一次性长命令也包装、并有约 19s 排队延迟）；非预设级、并发单机小样本，非统计显著 |
+| 调度隔离与资源互斥 | Handler queue/maxConcurrency/resources、类别优先级 + 等待老化（不封顶）、资源等待期限、waitReason（含 bulkhead）/longRunning、唯一任务只复用 succeeded | 组件级回归确认；按预设修订共享总线实例，跨进程/跨代际不保证，不是 OS 锁 |
+| 0.12.1 热修 | 内置 host.* 关闭 payload 去重、老化不封顶、唯一复用字节/时间戳、注册选项快照校验、validate/resources 内 close 重入、消息身份改摘要 | 组件级回归确认；不改变 wire 协议与工具调用形状 |
+| 属性测试 | fast-check 随机提交/重放与容量压力不变量（固定种子） | 开发依赖（MIT）；随机覆盖不是穷尽验证，种子固定保证可复现 |
 | 预设隔离 | AgentPresetRegistry 与 Loader | 派生预设可激活；源 ptc 声明不变、普通 Agent 不可见总线；原 write/edit/Job 工具保留，宿主前置策略拒绝仍有效 |
 | 故障注入 | 克隆失败、观察者拒绝、Job 等待/清理异常、先行移除与卸载交错 | 指定故障下的回归约束；不证明所有故障组合都已覆盖 |
 | 候选包 | 严格文件白名单、临时目录生产依赖安装、入口注册 | 包可安装和加载；安装验证使用简化宿主夹具，不是桌面插件管理器验收 |
@@ -51,6 +54,7 @@ eb95b4e51675f5f1821275e0812ef4dd4984b1aba45a52fbc6bab3518bbf6f38
 | 从真实 tgz 经宿主插件管理器加载预设、卸载与回滚 | 未完成完整桌面流程；源码工作区的 Loader 测试不能替代 |
 | 真实 glob/grep/pwsh 工具实现 | 未在测试环境启用：真实搜索工具依赖打包 ripgrep 与 subprocess 服务，真实 pwsh 依赖 shell/sandbox/审批组合；本版只验证按 handler 名转发、输入校验、幂等分流与失败固定码 |
 | 跨版本 PTC 中断原因 | 分离等待只识别 DSH 0.2.1-rc.2 实际使用的固定中断原因字符串；宿主升级后未知原因保守按取消处理，需复核 |
+| 跨会话/跨进程资源互斥 | 同一预设修订（generation）的会话共享总线实例，资源锁/舱壁/容量跨会话生效；不提供 OS 级文件锁，跨进程、跨代际不保证；同一文件的相对/绝对、大小写等别名写法可能绕过文件互斥 |
 | 模式采用率与效果 | 已完成指引级 A/B（可选触发 vs 总线优先），但非预设级、并发单机小样本，不具统计显著性；轮次/耗时/成功率的大样本对照仍未完成，不能由 schema 或单元测试推断 |
 | 磁盘会话结果提交及重启恢复原调用 | 未验收磁盘提交；本插件不支持跨重启恢复 |
 | 减少真实模型轮次、状态查询或总耗时的对照 | 未验证，不给提升比例 |
@@ -59,7 +63,7 @@ eb95b4e51675f5f1821275e0812ef4dd4984b1aba45a52fbc6bab3518bbf6f38
 ## 需要知道的运行约束
 
 1. 受理、队列、结果及交付标记均在内存。进程关闭会丢失，宿主会话日志不等于插件恢复执行权。
-2. 同一预设的会话共享总线容量，已受理任务会话轮转、会话内 FIFO；结果访问按会话隔离，不是独立进程或资源安全隔离，也不保证入队名额公平。
+2. 同一预设修订（generation）的会话共享总线容量，已受理任务会话轮转、会话内 FIFO；结果访问按会话隔离，不是独立进程或资源安全隔离，也不保证入队名额公平。重载/升级会创建新的预设修订，旧实例状态、容量与资源锁不延续。
 3. 取消任一正在等待的重复调用会请求取消整个逻辑执行，不是仅停止该等待者。
 4. 已终态且未过期的请求可直接复用结果，不申请新 Job；仍须通过身份、冲突及消息额度检查。
 5. 等待服务异常后先排空原执行，再有界检查宿主记录；服务持续不可用时记录可能留到所属生命周期清理。不合作 Handler 仍可能阻碍关闭。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feng0531/dsh-execution-bus",
-  "version": "0.11.3",
+  "version": "0.12.1",
   "type": "module",
   "private": false,
   "license": "SEE LICENSE IN LICENSE",
@@ -74,6 +74,7 @@
     "@deepseek-ai/dsh-tool-jobs": "0.2.1-rc.2",
     "@types/js-yaml": "4.0.9",
     "@types/node": "^22",
+    "fast-check": "^4.10.2",
     "prettier": "3.6.2",
     "typescript": "~5.9.3",
     "yaml": "2.9.1"