@feng0531/dsh-execution-bus 0.4.1 → 0.5.0

package/README.md

@@ -4,7 +4,7 @@
 
 “萧何”是产品与模式显示名，执行总线是其技术功能；不新增人物 Agent，不进行角色扮演。仓库 dsh-execution-bus、npm 包名、execution_bus 工具名及 execution-bus-test 预设 ID 保持不变。历史版本发布说明保留当时名称。
 
-DSH 独立插件：`@feng0531/dsh-execution-bus` · 当前版本 **0.4.1**
+DSH 独立插件：`@feng0531/dsh-execution-bus` · 当前版本 **0.5.0**
 
 > 萧何模式从宿主已声明的 PTC 组合派生，保留日常工具，再叠加可选执行总线。已验证隔离的真实 Node PTC → 原 read + 总线调用，以及脚本模型内存会话；真实模型、桌面界面与实际沙箱仍未验收。**不支持重启后恢复任务。**
 
@@ -115,7 +115,7 @@ flowchart TD
 2. 在你选定的隔离 DSH 配置依赖目录安装固定版本，不要在 DSH 程序安装目录执行：
 
    ```powershell
-   npm install --ignore-scripts @feng0531/dsh-execution-bus@0.4.1
+   npm install --ignore-scripts @feng0531/dsh-execution-bus@0.5.0
    ```
 
    这是 npm 目录示例。若目标配置使用 pnpm，应沿用其包管理器，不混用锁文件。遇到宿主 peer 版本冲突就停止，不用强制安装绕过。
@@ -204,7 +204,7 @@ stateDiagram-v2
 | `queued` | 已受理，尚未执行；不代表成功 |
 | `running` | 正在执行；等待窗口超时不自动把它变成失败 |
 | `succeeded` | 执行成功且总线保存了结果 |
-| `failed` | 处理器执行失败 |
+| `failed` | 处理器失败，或排队期限到达但尚未执行；查看 error 区分 |
 | `cancelled` | 已确认取消 |
 | `unknown` | 不能可靠保留或确认结果，不可盲目重跑有副作用操作 |
 
@@ -212,13 +212,19 @@ stateDiagram-v2
 
 ## 调度与诊断
 
-0.4.0 起对已受理的排队请求按会话轮转，同一会话保持 FIFO；不抢占运行任务，也不保证队列满时为其他会话预留名额。执行结果仍由 core 唯一提交，宿主 Job 只负责任务展示、控制与生命周期关联。
+0.4.0 起对已受理的排队请求按会话轮转，同一会话保持 FIFO；0.5.0 再增加每会话准入配额与排队期限。不抢占运行任务，也不保证队列满时为其他会话预留名额。执行结果仍由 core 唯一提交，宿主 Job 只负责任务展示、控制与生命周期关联。
 
 core 开发者可调用实例 `diagnostics()` 取得队列、运行数、保留结果字节及最近 128 条数值阶段轨迹。不含请求/会话 ID、输入、输出或错误文本，不写日志；诊断不增加模型调用工具，也不是跨重启审计记录。详见[优化范围与验证](<docs/OPTIMIZATION.md>)。
 
+### 查看本会话状态
+
+在 PTC 中按需执行 `return await tools.execution_bus_state({})`，仅在用户诊断时调用，不循环轮询。返回本会话排队/运行/终态数量、默认策略，以及最多 50 条任务元数据（活跃优先，其余最近受理的终态优先）。有 requestId、状态、等待原因、取消标记、单调时钟时长、固定错误码和 delivery，不含输入、结果或其他会话信息。delivery 不是模型已消费回执，也不能从视图断言 Job 正在清理。
+
+core 开发者可用 `new ExecutionBus(options, {sessionQueueLimit:16,maxQueueWaitMs:120000})` 和 `inspect(trustedOwner)`；第二参数省略时保持旧版无限会话配额/无排队期限行为，原五项 options 不变。该可信 owner 由调用者提供，core 不是身份认证边界，宿主工具从真实 Agent 取得身份且只接受空对象。
+
 ## 容量与重要限制
 
-默认并发 **2**，排队上限 **32**，最多保存 **256** 条任务记录，单结果最多 **64 KiB**，完成结果保留期 **1 小时**，在新请求和查询时惰性清理；不是一小时一到即定时删除。队列或记录满时拒绝新任务；宿主 Job 自身也有容量限制。
+宿主插件默认并发 **2**，全局排队上限 **32**，每会话排队上限 **16**；排队超过 **120 秒**且尚未开始执行时结算为 `failed / QUEUE_WAIT_TIMEOUT`，不调用 Handler。运行后不会被该排队期限中止，PTC 外层仍有独立时间预算。最多保存 **256** 条任务记录，单结果最多 **64 KiB**，完成结果保留期 **1 小时**，在新请求和查询时惰性清理；不是一小时一到即定时删除。队列或记录满时拒绝新任务；宿主 Job 自身也有容量限制。
 
 - **全部状态在内存中。** 受理没有落盘，插件关闭或进程崩溃后，不能依靠它恢复原调用或保证请求不丢失。
 - **不自动重跑任务。** 通信超时不等于执行失败，取消不等于回滚。Job 等待服务异常会在原执行排空后返回服务错误，执行可能已成功；应核对原 requestId 的状态，不要换编号盲目重跑。
@@ -250,7 +256,8 @@ npm run test:install    # 临时目录安装，不操作日常 DSH
 
 - [协议和投递语义](<docs/protocol.md>)：字段、状态、重复处理与取消规则。
 - [宿主兼容性与源码调用链](<docs/host-compatibility.md>)：为什么可以等待，为什么不能跨重启恢复。
-- [验证记录](<docs/validation.md>)、[0.4.1 发布说明](<docs/releases/0.4.1.md>)：已验证与未验证范围。
+- [验证记录](<docs/validation.md>)、[0.5.0 发布说明](<docs/releases/0.5.0.md>)：已验证与未验证范围。
+- [同类项目源码整合](<docs/INTEGRATION.md>)：固定来源、采用范围、许可与验证边界。
 - [维护者发布流程](<docs/RELEASING.md>)：标签 CI、安装包校验与正式发布门禁。
 
 ## 许可

package/THIRD_PARTY_NOTICES.md

@@ -3,3 +3,5 @@
 本包没有捆绑 DSH、Cordis、TypeScript、测试依赖或宿主源码快照。DSH 与 Cordis 作为宿主 peer 使用，其独立包分别受原许可证约束，本项目非商业许可证不限制第三方已授予的权利。开发依赖不进入本项目 tgz。js-yaml 为 MIT 许可的独立运行依赖，由包管理器按声明安装，不捆绑进 tgz；其源码和许可见 https://github.com/nodeca/js-yaml ，本项目许可不限制其原有权利。
 
 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>)。

package/dist/bus.d.ts

@@ -1,3 +1,7 @@
+export interface AdmissionPolicy {
+    sessionQueueLimit?: number;
+    maxQueueWaitMs?: number;
+}
 export type State = "queued" | "running" | "succeeded" | "failed" | "cancelled" | "unknown";
 export type Owner = {
     sessionId: string;
@@ -50,6 +54,7 @@ export declare class ExecutionBus {
         resultBytes: number;
         retentionMs: number;
     };
+    readonly admission: AdmissionPolicy;
     private entries;
     private handlers;
     private queue;
@@ -89,7 +94,7 @@ export declare class ExecutionBus {
         recordLimit: number;
         resultBytes: number;
         retentionMs: number;
-    });
+    }, admission?: AdmissionPolicy);
     register(name: string, handler: Handler): () => void;
     private key;
     private emit;
@@ -105,6 +110,34 @@ export declare class ExecutionBus {
     };
     private attachment;
     command(owner: Owner, raw: unknown): RecordView;
+    private removeQueued;
+    /** Trusted host owner required. Never exposes other sessions or business payloads. */
+    inspect(owner: Owner): {
+        phase: "open" | "cancelling" | "draining" | "closed";
+        policy: {
+            sessionQueueLimit?: number;
+            maxQueueWaitMs?: number;
+        };
+        counts: {
+            queued: number;
+            running: number;
+            terminal: number;
+        };
+        tasks: {
+            requestId: string;
+            state: State;
+            delivery: "returned" | "pending";
+            cancelRequested: boolean;
+            error: string | null;
+            progress: number | null;
+            waitReason: string | null;
+            phase: string;
+            queueMs: number;
+            runMs: number;
+            remainingQueueMs: number | null;
+        }[];
+        truncated: boolean;
+    };
     private cancel;
     private finish;
     private pump;

package/dist/bus.js

@@ -1,6 +1,7 @@
 import { randomUUID, createHash } from "node:crypto";
 import { assertJson } from "./json.js";
 import { Diagnostics } from "./diagnostics.js";
+import { performance } from "node:perf_hooks";
 export function object(v) {
     if (!v || typeof v !== "object" || Array.isArray(v))
         throw Error("INVALID_OBJECT");
@@ -56,6 +57,7 @@ const terminal = (s) => !["queued", "running"].includes(s);
 /** Volatile single-process bus; no acceptance durability or automatic execution retry. */
 export class ExecutionBus {
     options;
+    admission;
     entries = new Map();
     handlers = new Map();
     queue = [];
@@ -82,8 +84,25 @@ export class ExecutionBus {
         recordLimit: 256,
         resultBytes: 65536,
         retentionMs: 3600000,
-    }) {
+    }, admission = {}) {
         this.options = options;
+        this.admission = admission;
+        const allowed = ["sessionQueueLimit", "maxQueueWaitMs"];
+        if (!admission ||
+            typeof admission !== "object" ||
+            Array.isArray(admission) ||
+            Reflect.ownKeys(admission).some((key) => typeof key !== "string" || !allowed.includes(key)))
+            throw Error("INVALID_ADMISSION_POLICY");
+        for (const key of Reflect.ownKeys(admission)) {
+            const descriptor = Object.getOwnPropertyDescriptor(admission, key);
+            if (!("value" in descriptor) ||
+                !descriptor.enumerable ||
+                !Number.isSafeInteger(descriptor.value) ||
+                descriptor.value < 1 ||
+                descriptor.value > 2147483647)
+                throw Error("INVALID_ADMISSION_POLICY");
+        }
+        this.admission = Object.freeze({ ...admission });
         const keys = [
             "concurrency",
             "queueLimit",
@@ -213,6 +232,10 @@ export class ExecutionBus {
         if (this.entries.size >= this.options.recordLimit ||
             this.queue.length >= this.options.queueLimit)
             throw Error("BACKPRESSURE");
+        if (this.admission.sessionQueueLimit !== undefined &&
+            this.queue.filter((entry) => entry.owner === owner.sessionId).length >=
+                this.admission.sessionQueueLimit)
+            throw Error("SESSION_BACKPRESSURE");
         let resolve;
         const done = new Promise((r) => (resolve = r));
         e = {
@@ -245,6 +268,22 @@ export class ExecutionBus {
         this.telemetry.record(e.trace, "accepted");
         const attached = this.attachment(e, onEvent, m.messageId);
         this.queue.push(e);
+        if (this.admission.maxQueueWaitMs !== undefined) {
+            e.deadline = performance.now() + this.admission.maxQueueWaitMs;
+            const entry = e;
+            const expire = () => {
+                if (entry.view.state !== "queued")
+                    return;
+                const remaining = entry.deadline - performance.now();
+                if (remaining > 0) {
+                    entry.queueTimer = setTimeout(expire, Math.ceil(remaining));
+                    return;
+                }
+                this.removeQueued(entry);
+                this.finish(entry, "failed", undefined, "QUEUE_WAIT_TIMEOUT");
+            };
+            e.queueTimer = setTimeout(expire, this.admission.maxQueueWaitMs);
+        }
         if (!this.readyOwners.includes(e.owner))
             this.readyOwners.push(e.owner);
         queueMicrotask(() => this.pump());
@@ -307,6 +346,61 @@ export class ExecutionBus {
         }
         return this.view(e);
     }
+    removeQueued(e) {
+        this.queue = this.queue.filter((entry) => entry !== e);
+        if (!this.queue.some((entry) => entry.owner === e.owner))
+            this.readyOwners = this.readyOwners.filter((owner) => owner !== e.owner);
+    }
+    /** Trusted host owner required. Never exposes other sessions or business payloads. */
+    inspect(owner) {
+        if (!owner || typeof owner.sessionId !== "string" || !owner.sessionId)
+            throw Error("OWNING_SESSION_REQUIRED");
+        this.sweep();
+        const now = performance.now();
+        const records = [...this.entries.values()].filter((e) => e.owner === owner.sessionId);
+        // Active work must not disappear behind newer terminal history.
+        const active = records.filter((e) => !terminal(e.view.state));
+        const history = records.filter((e) => terminal(e.view.state)).reverse();
+        const selected = [...active, ...history].slice(0, 50);
+        const tasks = selected.map((e) => ({
+            requestId: e.view.requestId,
+            state: e.view.state,
+            delivery: e.view.delivery,
+            cancelRequested: e.view.cancelRequested,
+            error: e.view.error ?? null,
+            progress: e.view.progress ?? null,
+            waitReason: e.view.state === "queued"
+                ? this.running >= this.options.concurrency
+                    ? "concurrency"
+                    : "dispatch"
+                : null,
+            phase: terminal(e.view.state)
+                ? e.view.delivery === "returned"
+                    ? "returned"
+                    : "terminal"
+                : e.view.cancelRequested
+                    ? "cancelling"
+                    : e.view.state,
+            queueMs: Math.max(0, (e.startedAt ?? e.finishedAt ?? now) - e.trace.at),
+            runMs: e.startedAt === undefined
+                ? 0
+                : Math.max(0, (e.finishedAt ?? now) - e.startedAt),
+            remainingQueueMs: e.view.state === "queued" && e.deadline !== undefined
+                ? Math.max(0, e.deadline - now)
+                : null,
+        }));
+        return freezeJson({
+            phase: this.shutdownPhase,
+            policy: { ...this.admission },
+            counts: {
+                queued: records.filter((e) => e.view.state === "queued").length,
+                running: records.filter((e) => e.view.state === "running").length,
+                terminal: records.filter((e) => terminal(e.view.state)).length,
+            },
+            tasks,
+            truncated: records.length > 50,
+        });
+    }
     cancel(e) {
         if (terminal(e.view.state) || e.view.cancelRequested)
             return;
@@ -315,15 +409,18 @@ export class ExecutionBus {
         e.controller.abort();
         this.emit(e, "cancel_requested", {});
         if (e.view.state === "queued") {
-            this.queue = this.queue.filter((x) => x !== e);
-            if (!this.queue.some((entry) => entry.owner === e.owner))
-                this.readyOwners = this.readyOwners.filter((owner) => owner !== e.owner);
+            this.removeQueued(e);
             this.finish(e, "cancelled");
         }
     }
     finish(e, state, result, error, resultBytes = 0) {
         if (terminal(e.view.state))
             return;
+        if (e.queueTimer !== undefined) {
+            clearTimeout(e.queueTimer);
+            e.queueTimer = undefined;
+        }
+        e.finishedAt = performance.now();
         // Prepare the delivery snapshot BEFORE committing an irreversible terminal state.
         let next = { ...e.view, state, sequence: e.view.sequence + 1 };
         if (result !== undefined)
@@ -375,6 +472,15 @@ export class ExecutionBus {
             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++;
             e.view.state = "running";
             this.telemetry.record(e.trace, "started");

package/dist/plugin.js

@@ -5,11 +5,38 @@ import { testHandler, readHandler } from "./handlers.js";
 export const name = "execution-bus";
 export const inject = ["tools", "jobs"];
 export function apply(ctx) {
-    const bus = new ExecutionBus();
+    const bus = new ExecutionBus(undefined, {
+        sessionQueueLimit: 16,
+        maxQueueWaitMs: 120000,
+    });
     bus.register("test", testHandler);
     bus.register("host.read", readHandler);
     const executions = new ExecutionOwner();
     ctx.effect(() => () => executions.close(() => bus.close()));
+    ctx.tools.register({
+        name: "execution_bus_state",
+        description: "Read a bounded metadata-only snapshot of this agent session’s bus tasks. No inputs/results, no cross-session access. Do not poll during an awaited request.",
+        parameters: { type: "object", properties: {}, additionalProperties: false },
+        output: {
+            schema: {},
+            render: (_a, v) => [{ type: "text", text: JSON.stringify(v) }],
+        },
+        async execute(raw, exec) {
+            if (executions.phase !== "open")
+                throw Error("CLOSED");
+            if (!exec.agent)
+                throw Error("OWNING_SESSION_REQUIRED");
+            if (!raw ||
+                typeof raw !== "object" ||
+                Array.isArray(raw) ||
+                Reflect.ownKeys(raw).length)
+                throw Error("INVALID_STATE_QUERY");
+            return bus.inspect({
+                sessionId: String(exec.agent.id),
+                callId: String(exec.callId),
+            });
+        },
+    });
     ctx.tools.register({
         name: "execution_bus",
         description: "萧何 / Xiao He. Submit a version 1 request and WAIT for its terminal result in this tool call. Reuse requestId only for the same logical operation. Handlers: test {delayMs:0..30000,fail:boolean}, host.read {file_path,offset?,limit?<=100}. Control types status/result/cancel use empty payload. Acceptance is volatile, not execution success. No polling needed; no restart resume.",

package/dist/test-mode.js

@@ -9,7 +9,7 @@ export function apply(ctx) {
     ctx.effect(() => ctx.systemPrompt.section({
         name: "XIAO_HE_EXECUTION_BUS",
         order: 1700,
-        text: "你正在萧何模式中。这不是角色扮演。保留宿主 PTC 的日常工具能力与权限规则。普通编辑、搜索、命令、安装和其他工作使用原工具，不要声称此模式只读。execution_bus 是可选协调入口，目前只支持 test 与 host.read，不支持任意命令，不要强制所有任务走总线。通过 run_code 调用 await tools.execution_bus(...)，受原有时间预算约束。总线请求只提交一次并等待结果，不循环查询；同一逻辑操作重发沿用 requestId。cancelRequested 不等于已取消，unknown 不代表执行失败，不承诺跨重启恢复。后台命令仅返回 Job ID 不代表命令已经完成。",
+        text: "你正在萧何模式中。这不是角色扮演。保留宿主 PTC 的日常工具能力与权限规则。普通编辑、搜索、命令、安装和其他工作使用原工具，不要声称此模式只读。execution_bus 是可选协调入口，目前只支持 test 与 host.read，不支持任意命令，不要强制所有任务走总线。通过 run_code 调用 await tools.execution_bus(...)，受原有时间预算约束。总线默认每会话最多排队16项，排队超过120秒且尚未开始执行会返回QUEUE_WAIT_TIMEOUT，不自动重试。execution_bus_state只用于用户明确诊断本会话的元数据状态，不在等待期间循环查询。总线请求只提交一次并等待结果，不循环查询；同一逻辑操作重发沿用 requestId。cancelRequested 不等于已取消，unknown 不代表执行失败，不承诺跨重启恢复。后台命令仅返回 Job ID 不代表命令已经完成。",
     }));
     applyBus(ctx);
 }

package/docs/INTEGRATION.md

@@ -0,0 +1,35 @@
+# 同类项目源码参考与整合（0.5.0）
+
+## 本轮交付
+
+以本项目 0.4.1 为基线，固定五个候选仓库提交，阅读相关源文件和测试，不将“看过 README”表述成源码审计或全部项目验收。没有运行这些第三方项目的测试，没有合入其整个插件或直接复制源码。
+
+1. **会话准入配额**：宿主插件每会话最多 16 个排队请求，全局 32 不变；相同请求复用不占新槽，拒绝不保留 requestId。不是为每个会话预留槽位，不限制已运行数或终态记录数。
+2. **排队等待期限**：宿主插件默认 120 秒。计时器和出队前均使用单调时钟检查；只有尚未运行任务超时才 failed / QUEUE_WAIT_TIMEOUT，不调用 Handler、不重试。运行任务继续等待或合作取消。
+3. **会话只读快照**：新增 execution_bus_state({})，可信 Agent 身份由宿主提供。只返回本会话元数据，最多 50 项、活跃优先、其余最近受理终态优先；不返回输入/结果，不创建 Job，不增加后台轮询。没有 UI 面板或额外 HTTP 路由。
+
+原 core 五项 options 与默认策略不变，新增第二构造参数 AdmissionPolicy；部署插件选择启用上述默认值。普通任务无权覆盖策略，宿主授权、PTC 原工具和 Job 生命周期不变。
+
+## 固定来源、实际阅读范围与采用判断
+
+| 来源（固定提交） | 相关文件/范围 | 采用与不采用 |
+|---|---|---|
+| [dsh-llm-rate-limit / 8222d017](https://github.com/Asong6824/dsh-llm-rate-limit/tree/8222d0179a64c898986c69062ca86d998873e756) | src/index.ts 的配置校验、settleEntry、pump、acquire、cancelQueued、release、卸载；src/invariant.ts；tests/rate-limit.spec.ts 的准入、取消、超时和卸载用例 | 参考“有界准入、期限先于执行、卸载清理计时器后排空”。会话配额是本项目自拟适配，不宣称上游提供同样会话公平策略。不引入令牌桶、LLM 中间件或自动限流 |
+| [dsh-nightshift / 35805240](https://github.com/mikasaxin529/dsh-nightshift/tree/358052402749c2830045216bdb0345250f6f32f1) | lib/queue.js 与 test/queue.test.js；index.js 的排队/运行恢复、分发锁、只读状态、卸载路径；test/index.test.js 的并发分发、状态/历史和卸载用例；client.js 前端入口及状态读取结构 | 参考“由事实源生成有界视图、活跃与历史分开”。不复制前端/HTTP；不采用崩溃后 running 重新排队、自动 retry 或 continuation |
+| [AsyncGate / 36197be8](https://github.com/PStryder/AsyncGate/tree/36197be84fca835b9edca16aa46fbf2f8d694b47) | tests/test_p18_stale_lease_cannot_write.py；src/asyncgate/db/repositories.py 的按 lease_id release | 对照旧执行者不能释放新授权的原则；本项目已有注册令牌和关联对象身份检查，无需引入远端租约/数据库。本快照未发现 LICENSE 文件，不复制代码，不推断可再分发授权 |
+| [dsh-input-traffic / bc4b298b](https://github.com/drscrewdriver/dsh-input-traffic/tree/bc4b298be1a831cf09a68722a8f0d0607b5a9ff8) | src/client/freeze-store.ts 的 sessionId 键控与快照隔离；LICENSE | 参考会话隔离思路，不接管输入、冻结、重排或 UI store |
+| [cc-multi-process-mcp / 234823f1](https://github.com/L-x-C/cc-multi-process-mcp/tree/234823f15616d7e9c759072e940396d939f823c2) | main.py 的进程检测、信号回收、同步/异步执行、结果文件和清理路径 | 不引入自建进程池或轮询。源码的 skip_permissions 默认和 /tmp 存储不适合本插件宿主边界；未发现 LICENSE 文件，不复制代码 |
+
+这是相关路径的定向阅读，不是五仓全量逐文件安全审核。参考快照在开发目录，明确忽略，不进入源码提交或 npm 包。
+
+## 许可与实现归属
+
+dsh-llm-rate-limit、dsh-nightshift、dsh-input-traffic 的 LICENSE 已阅读，均为 MIT，分别保留各自权利；本轮只参考行为原则并重新实现，无第三方源码片段合入，无新增运行依赖。项目自身非商业源码公开许可不改变上游独立许可。未来复制实质代码需另行保留上游版权和完整许可。
+
+## 验证及边界
+
+新增 core 回归覆盖会话容量/拒绝可重试身份、满配额请求复用、队列超时不执行、运行任务不受队列期限中止、计时器延迟仍出队前拒绝、取消/关闭清理、不可变及会话隔离状态、50 项截断与活跃优先、非法策略和输入访问器。宿主 ToolRuntime 检查匿名/伪造 session 拒绝；真实 Node PTC 验证新工具绑定。
+
+默认策略真实值由宿主组件测试核对；超时测试缩短 core 期限，未让宿主挂满 120 秒。真实 Node PTC 使用测试 Agent 和非约束策略，不代表当前桌面、实际沙箱或真实模型验收。
+
+状态工具用于用户明确诊断，不用于等待中的模型轮询。requestId 是本会话元数据而非匿名统计，因此不要在编号里写敏感业务内容；core diagnostics 的脱敏数值轨迹仍不含请求编号。外部副作用不会因排队期限、取消或查询自动回滚。

package/docs/protocol.md

@@ -80,7 +80,7 @@ queued → running → succeeded / failed / cancelled / unknown
 | 单结果 JSON | 64 KiB |
 | 终态保留期 | 自完成起 1 小时 |
 
-新执行请求受队列和记录容量限制；运行中重复附着受消息/监听名额限制；未过期终态复用不申请新 Job。宿主新 Job 准入还有独立容量要求。已受理的排队任务按会话轮转，各会话内部 FIFO；不抢占运行任务，没有完成时间 SLA，单会话仍可占满受理容量，不保证其他会话一定获得入队名额。
+新执行请求受队列和记录容量限制；运行中重复附着受消息/监听名额限制；未过期终态复用不申请新 Job。宿主新 Job 准入还有独立容量要求。已受理的排队任务按会话轮转，各会话内部 FIFO；不抢占运行任务，没有完成时间 SLA，core 未启用会话配额时单会话可占满队列；宿主插件启用每会话16项，但终态记录与多会话总量仍可占满容量，不保证其他会话一定获得入队名额。
 
 core 不传配置时用默认值；显式配置必须完整包含 concurrency、queueLimit、recordLimit、resultBytes、retentionMs 五项正安全整数。拒绝缺项、额外字段与访问器；构造时复制冻结，无动态更新接口。
 
@@ -94,13 +94,25 @@ core 不传配置时用默认值；显式配置必须完整包含 concurrency、
 
 同存活实例、保存期内的请求复用不是端到端 exactly-once；每个实际工具调用仍有自己的宿主结果记录。没有外部终态注入接口，也没有跨重启恢复：任一阶段进程崩溃都会丢失插件内存状态。宿主日志不能复活旧 Promise，不追加聊天消息冒充原调用恢复。
 
-## 6. 诊断
+## 6. 准入与会话状态（0.5.0）
+
+原五项 core options 不变。第二构造参数 AdmissionPolicy 可含 sessionQueueLimit、maxQueueWaitMs，均为 1..2147483647 安全整数，省略表示不启用该约束。策略复制冻结，未知键和访问器拒绝。宿主插件启用每会话排队 16、排队 120000ms，普通请求不可覆盖策略。
+
+相同 requestId 的复用先于新准入检查，不重复占槽或重置原期限。每会话超额返回 SESSION_BACKPRESSURE，不受理、不占 requestId；全局/记录容量仍优先返回 BACKPRESSURE。两者只限制准入，不保留所有会话的专用槽。终态记录仍可占满 recordLimit。
+
+期限使用单调时钟，计时器及出队前均检查，超期只将 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 清理进度。
+
+core inspect(trustedOwner) 要求非空 sessionId，但不提供鉴权，可信身份和访问控制属于嵌入宿主。勿把 core 的任意 owner 参数直接暴露给远端。状态不是持久审计/模型消费回执，不应循环调用。
+
+## 7. 诊断
 
 core 实例的 `diagnostics()` 返回只读用途的独立快照：阶段计数、最近 128 条 `{operation,stage,elapsedMs}` 轨迹、关闭阶段、队列/运行/记录数及保留结果字节数。operation 是实例内递增数值，不是消息或会话 ID；elapsedMs 以单调时钟计算，阶段时间均相对受理时间，可相减得到排队/执行/返回延迟。复用计数仅在附着受理成功时增加；返回阶段按逻辑结果首次标记，不代表每个工具调用都持久化。
 
 宿主执行所有者另有内部 Job 创建/释放/异常聚合轨迹，不作为模型工具或公开服务导出；其 operation 是独立编号，不能与 core 轨迹按编号关联。数据只在内存，不保存参数、结果、Handler 名称、请求/会话 ID、异常文本或聊天记录。总计数会持续累积，128 槽环形轨迹有界且按时间顺序导出；结果字节只在保存/过期/关闭时更新，查询不读取结果内容或重复序列化。异常计数不等于每次清理最终失败。
 
-## 7. 扩展 Handler
+## 8. 扩展 Handler
 
 包的 `./core` 导出 ExecutionBus、Handler、Capability 类型。Handler 只接收输入、requestId、signal、progress 和可选最小 capability，不接收聊天历史。register 返回绑定唯一注册令牌的幂等注销函数，不会误删后来同名注册；已受理请求继续持有原 Handler。
 

package/docs/releases/0.5.0.md

@@ -0,0 +1,16 @@
+# 萧何 / Xiao He 0.5.0
+
+## 有意义的同类项目整合
+
+阅读固定提交的同类 DSH 队列/限流插件与 MCP 执行项目相关源码和测试后，重新实现适合本插件的能力，不直接合并第三方源码或新增运行依赖。
+
+- 宿主插件新增每会话排队上限 16（全局仍 32），拒绝错误 SESSION_BACKPRESSURE；重复请求复用不重复占名额。不是全局入队公平保证。
+- 默认排队期限 120 秒，仅尚未运行任务到期 failed / QUEUE_WAIT_TIMEOUT，保证不调用 Handler。计时器及出队均校验单调期限，运行任务仍使用原合作取消，不超时强杀或自动重跑。
+- 新增 execution_bus_state({}) 只读工具，身份来自宿主 Agent，拒绝匿名或自报身份；只返回本会话元数据/计数/策略，最多 50 项、活跃优先，其余终态按最近受理排序。不含输入或结果，不创建 Job。没有 UI 面板。
+- core 原五项 options 不变，第二参数可选配置 AdmissionPolicy；不传策略保持旧行为。inspect(trustedOwner) 为可信嵌入方接口，不是独立鉴权系统。
+
+## 验证与限制
+
+新增准入、期限、竞态、关闭计时器、隐私隔离、活跃优先及策略校验回归；真实宿主和 Node PTC 验证状态工具与身份规则。120 秒语义用缩短 core 期限测试，默认值由宿主组件检查，不声称真实模型/桌面沙箱已验收。
+
+不引入数据库、租约、崩溃重排、自动副作用重试或独立进程池。普通 PTC 工具能力、宿主权限/沙箱、总线原始调用等待不变。DSH 0.2.0-rc.2，非商业源码公开许可；不安装或重启日常 DSH。

package/docs/validation.md

@@ -1,6 +1,6 @@
 # 验证范围与使用限制
 
-本文说明当前版本的证据边界，不是生产环境认证。当前优化基线为 **v0.4.0**，新增执行所有权/关闭、通知重入边界、数值诊断及会话轮转；预设沿用 v0.3.0 的宿主 PTC 声明派生方式。验证环境为 Windows、Node.js 24.21.0，宿主组件锁定 DSH 0.2.0-rc.2、Cordis 4.0.4。
+本文说明当前版本的证据边界，不是生产环境认证。当前能力基线为 **v0.5.0**，在此前生命周期、数值诊断及轮转上新增会话准入配额、排队期限和隔离状态工具；预设沿用 v0.3.0 的宿主 PTC 声明派生方式。验证环境为 Windows、Node.js 24.21.0，宿主组件锁定 DSH 0.2.0-rc.2、Cordis 4.0.4。
 
 ## 已验证什么？
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feng0531/dsh-execution-bus",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "type": "module",
   "private": false,
   "license": "SEE LICENSE IN LICENSE",