@feng0531/dsh-execution-bus 0.3.0 → 0.4.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.3.0**
+DSH 独立插件：`@feng0531/dsh-execution-bus` · 当前版本 **0.4.0**
 
 > 萧何模式从宿主已声明的 PTC 组合派生，保留日常工具，再叠加可选执行总线。已验证隔离的真实 Node PTC → 原 read + 总线调用，以及脚本模型内存会话；真实模型、桌面界面与实际沙箱仍未验收。**不支持重启后恢复任务。**
 
@@ -115,7 +115,7 @@ flowchart TD
 2. 在你选定的隔离 DSH 配置依赖目录安装固定版本，不要在 DSH 程序安装目录执行：
 
    ```powershell
-   npm install --ignore-scripts @feng0531/dsh-execution-bus@0.3.0
+   npm install --ignore-scripts @feng0531/dsh-execution-bus@0.4.0
    ```
 
    这是 npm 目录示例。若目标配置使用 pnpm，应沿用其包管理器，不混用锁文件。遇到宿主 peer 版本冲突就停止，不用强制安装绕过。
@@ -210,6 +210,12 @@ stateDiagram-v2
 
 执行终态不会再改成另一个终态。取消与成功竞争时，若处理器最终正常返回，仍可能是成功。`delivery` 是另一个字段：`pending` 表示尚未走到返回标记，`returned` 只表示插件已走到工具返回路径，**不证明会话结果已经写入磁盘或模型已经消费**。
 
+## 调度与诊断
+
+0.4.0 起对已受理的排队请求按会话轮转，同一会话保持 FIFO；不抢占运行任务，也不保证队列满时为其他会话预留名额。执行结果仍由 core 唯一提交，宿主 Job 只负责任务展示、控制与生命周期关联。
+
+core 开发者可调用实例 `diagnostics()` 取得队列、运行数、保留结果字节及最近 128 条数值阶段轨迹。不含请求/会话 ID、输入、输出或错误文本，不写日志；诊断不增加模型调用工具，也不是跨重启审计记录。详见[优化范围与验证](<docs/OPTIMIZATION.md>)。
+
 ## 容量与重要限制
 
 默认并发 **2**，排队上限 **32**，最多保存 **256** 条任务记录，单结果最多 **64 KiB**，完成结果保留期 **1 小时**，在新请求和查询时惰性清理；不是一小时一到即定时删除。队列或记录满时拒绝新任务；宿主 Job 自身也有容量限制。
@@ -244,7 +250,7 @@ npm run test:install    # 临时目录安装，不操作日常 DSH
 
 - [协议和投递语义](<docs/protocol.md>)：字段、状态、重复处理与取消规则。
 - [宿主兼容性与源码调用链](<docs/host-compatibility.md>)：为什么可以等待，为什么不能跨重启恢复。
-- [验证记录](<docs/validation.md>)、[0.3.0 发布说明](<docs/releases/0.3.0.md>)：已验证与未验证范围。
+- [验证记录](<docs/validation.md>)、[0.4.0 发布说明](<docs/releases/0.4.0.md>)：已验证与未验证范围。
 - [维护者发布流程](<docs/RELEASING.md>)：标签 CI、安装包校验与正式发布门禁。
 
 ## 许可

package/dist/bus.d.ts

@@ -53,8 +53,35 @@ export declare class ExecutionBus {
     private entries;
     private handlers;
     private queue;
+    private readyOwners;
     private running;
     private closed;
+    private telemetry;
+    diagnostics(): {
+        phase: "open" | "cancelling" | "draining" | "closed";
+        queued: number;
+        running: number;
+        records: number;
+        retainedResultBytes: number;
+        counts: {
+            accepted?: number | undefined;
+            started?: number | undefined;
+            cancel_requested?: number | undefined;
+            terminal?: number | undefined;
+            returned?: number | undefined;
+            job_created?: number | undefined;
+            job_released?: number | undefined;
+            job_error?: number | undefined;
+            reused?: number | undefined;
+        };
+        traces: {
+            operation: number;
+            stage: import("./diagnostics.js").TraceStage;
+            elapsedMs: number;
+        }[];
+    };
+    private closing?;
+    private shutdownPhase;
     constructor(options?: {
         concurrency: number;
         queueLimit: number;

package/dist/bus.js

@@ -1,5 +1,6 @@
 import { randomUUID, createHash } from "node:crypto";
 import { assertJson } from "./json.js";
+import { Diagnostics } from "./diagnostics.js";
 export function object(v) {
     if (!v || typeof v !== "object" || Array.isArray(v))
         throw Error("INVALID_OBJECT");
@@ -58,8 +59,25 @@ export class ExecutionBus {
     entries = new Map();
     handlers = new Map();
     queue = [];
+    readyOwners = [];
     running = 0;
     closed = false;
+    telemetry = new Diagnostics();
+    diagnostics() {
+        return {
+            ...this.telemetry.snapshot(),
+            phase: this.shutdownPhase,
+            queued: this.queue.length,
+            running: this.running,
+            records: this.entries.size,
+            retainedResultBytes: [...this.entries.values()].reduce((sum, e) => sum +
+                (e.view.result === undefined
+                    ? 0
+                    : Buffer.byteLength(JSON.stringify(e.view.result))), 0),
+        };
+    }
+    closing;
+    shutdownPhase = "open";
     constructor(options = {
         concurrency: 2,
         queueLimit: 32,
@@ -119,16 +137,30 @@ export class ExecutionBus {
             type,
             payload,
         });
-        for (const f of e.listeners)
-            try {
-                // Observe promise rejection without awaiting or blocking task settlement.
-                void Promise.resolve(f(event)).catch(() => {
-                    /* Async observers are best-effort; never leak their error text. */
-                });
-            }
-            catch {
-                /* Observers cannot alter execution. */
+        // Snapshot and enqueue before invoking user code: nested cancellation cannot
+        // overtake the current event for later observers. Removed listeners are skipped.
+        e.notifications.push({ event, listeners: [...e.listeners] });
+        if (e.dispatching)
+            return;
+        e.dispatching = true;
+        try {
+            while (e.notifications.length) {
+                const batch = e.notifications.shift();
+                for (const listener of batch.listeners) {
+                    if (!e.listeners.has(listener))
+                        continue;
+                    try {
+                        void Promise.resolve(listener(batch.event)).catch(() => { });
+                    }
+                    catch { }
+                }
             }
+        }
+        finally {
+            e.dispatching = false;
+            if (terminal(e.view.state))
+                e.listeners.clear();
+        }
     }
     view(e) {
         return structuredClone(e.view);
@@ -170,6 +202,7 @@ export class ExecutionBus {
             const attached = this.attachment(e, onEvent, m.messageId);
             if (!previous)
                 e.messages.set(m.messageId, canonical(m));
+            this.telemetry.record(e.trace, "reused");
             return attached;
         }
         const handler = this.handlers.get(p.handler)?.handler;
@@ -182,6 +215,7 @@ export class ExecutionBus {
         let resolve;
         const done = new Promise((r) => (resolve = r));
         e = {
+            trace: this.telemetry.begin(),
             invoke,
             correlationId: m.messageId,
             owner: owner.sessionId,
@@ -199,13 +233,18 @@ export class ExecutionBus {
             done,
             resolve,
             listeners: new Set(),
+            notifications: [],
+            dispatching: false,
             sourceSequence: 0,
             created: Date.now(),
             messages: new Map([[m.messageId, canonical(m)]]),
         };
         this.entries.set(key, e);
+        this.telemetry.record(e.trace, "accepted");
         const attached = this.attachment(e, onEvent, m.messageId);
         this.queue.push(e);
+        if (!this.readyOwners.includes(e.owner))
+            this.readyOwners.push(e.owner);
         queueMicrotask(() => this.pump());
         return attached;
     }
@@ -235,6 +274,8 @@ export class ExecutionBus {
                     e.listeners.delete(listener);
             },
             returned: () => {
+                if (e.view.delivery !== "returned")
+                    this.telemetry.record(e.trace, "returned");
                 e.view.delivery = "returned";
             },
         };
@@ -268,10 +309,13 @@ export class ExecutionBus {
         if (terminal(e.view.state) || e.view.cancelRequested)
             return;
         e.view.cancelRequested = true;
+        this.telemetry.record(e.trace, "cancel_requested");
         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.finish(e, "cancelled");
         }
     }
@@ -302,19 +346,33 @@ export class ExecutionBus {
         }
         e.created = Date.now();
         e.view = { ...next, sequence: next.sequence - 1 };
-        this.emit(e, state, { state });
+        this.telemetry.record(e.trace, "terminal");
         e.resolve(snapshot);
-        e.listeners.clear();
+        this.emit(e, state, { state });
+        // A reentrant terminal notification may still be queued behind this batch.
+        if (!e.dispatching)
+            e.listeners.clear();
     }
     pump() {
         while (!this.closed &&
             this.running < this.options.concurrency &&
             this.queue.length) {
-            const e = this.queue.shift();
+            let index = -1;
+            while (this.readyOwners.length && index < 0) {
+                const owner = this.readyOwners.shift();
+                index = this.queue.findIndex((entry) => entry.owner === owner);
+                if (index >= 0 &&
+                    this.queue.some((entry, i) => i !== index && entry.owner === owner))
+                    this.readyOwners.push(owner);
+            }
+            if (index < 0)
+                index = 0;
+            const e = this.queue.splice(index, 1)[0];
             if (e.view.state !== "queued")
                 continue;
             this.running++;
             e.view.state = "running";
+            this.telemetry.record(e.trace, "started");
             this.emit(e, "started", {});
             void this.run(e).finally(() => {
                 this.running--;
@@ -372,12 +430,28 @@ export class ExecutionBus {
                     : "HANDLER_FAILED");
         }
     }
-    async close() {
+    close() {
+        if (this.closing)
+            return this.closing;
         this.closed = true;
-        for (const e of this.entries.values())
-            this.cancel(e);
-        await Promise.all([...this.entries.values()].map((e) => e.done));
-        this.handlers.clear();
-        this.entries.clear();
+        this.shutdownPhase = "cancelling";
+        let resolve, reject;
+        this.closing = new Promise((r, j) => {
+            resolve = r;
+            reject = j;
+        });
+        void (async () => {
+            const entries = [...this.entries.values()];
+            for (const e of entries)
+                this.cancel(e);
+            this.shutdownPhase = "draining";
+            await Promise.all(entries.map((e) => e.done));
+            this.handlers.clear();
+            this.entries.clear();
+            this.queue = [];
+            this.readyOwners = [];
+            this.shutdownPhase = "closed";
+        })().then(resolve, reject);
+        return this.closing;
     }
 }

package/dist/diagnostics.d.ts

@@ -0,0 +1,38 @@
+export type TraceStage = "accepted" | "started" | "cancel_requested" | "terminal" | "returned" | "job_created" | "job_released" | "job_error" | "reused";
+export interface Trace {
+    operation: number;
+    stage: TraceStage;
+    elapsedMs: number;
+}
+/** In-memory numeric metadata only: never accepts request/session strings, input, output or error text. */
+export declare class Diagnostics {
+    private next;
+    private events;
+    private counts;
+    begin(): {
+        operation: number;
+        at: number;
+    };
+    record(context: {
+        operation: number;
+        at: number;
+    }, stage: TraceStage): void;
+    snapshot(): {
+        counts: {
+            accepted?: number | undefined;
+            started?: number | undefined;
+            cancel_requested?: number | undefined;
+            terminal?: number | undefined;
+            returned?: number | undefined;
+            job_created?: number | undefined;
+            job_released?: number | undefined;
+            job_error?: number | undefined;
+            reused?: number | undefined;
+        };
+        traces: {
+            operation: number;
+            stage: TraceStage;
+            elapsedMs: number;
+        }[];
+    };
+}

package/dist/diagnostics.js

@@ -0,0 +1,26 @@
+import { performance } from "node:perf_hooks";
+/** In-memory numeric metadata only: never accepts request/session strings, input, output or error text. */
+export class Diagnostics {
+    next = 0;
+    events = [];
+    counts = {};
+    begin() {
+        return { operation: ++this.next, at: performance.now() };
+    }
+    record(context, stage) {
+        this.counts[stage] = (this.counts[stage] ?? 0) + 1;
+        this.events.push({
+            operation: context.operation,
+            stage,
+            elapsedMs: Math.max(0, performance.now() - context.at),
+        });
+        if (this.events.length > 128)
+            this.events.shift();
+    }
+    snapshot() {
+        return {
+            counts: { ...this.counts },
+            traces: this.events.map((e) => ({ ...e })),
+        };
+    }
+}

package/dist/execution.d.ts

@@ -0,0 +1,61 @@
+import type { JobRegistry, JobId } from "@deepseek-ai/dsh-jobs";
+import type { SessionId } from "@deepseek-ai/dsh-session";
+import type { RecordView, Event } from "./bus.js";
+import { Diagnostics } from "./diagnostics.js";
+export interface ExecutionAttachment {
+    done: Promise<RecordView>;
+    cancel(): void;
+}
+/** One host projection of a logical execution. The core completion remains authoritative. */
+export declare class ExecutionHandle {
+    private jobs;
+    private owner;
+    private execution;
+    private telemetry;
+    readonly completion: Promise<RecordView>;
+    readonly settled: Promise<void>;
+    readonly job: JobId;
+    private progressHandle?;
+    private trace;
+    constructor(jobs: JobRegistry, owner: SessionId, execution: ExecutionAttachment, telemetry?: Diagnostics);
+    requestCancel(): void;
+    progress(event: Event): void;
+    private absent;
+    private waitAndClean;
+}
+export type ShutdownPhase = "open" | "stopping" | "draining" | "releasing" | "closed";
+/** Owns host projections and active deliveries, not a second execution state machine. */
+export declare class ExecutionOwner {
+    private handles;
+    private deliveries;
+    private closing?;
+    private telemetry;
+    create(key: string, jobs: JobRegistry, owner: SessionId, execution: ExecutionAttachment): ExecutionHandle;
+    diagnostics(): {
+        phase: ShutdownPhase;
+        activeProjections: number;
+        deliveries: number;
+        counts: {
+            accepted?: number | undefined;
+            started?: number | undefined;
+            cancel_requested?: number | undefined;
+            terminal?: number | undefined;
+            returned?: number | undefined;
+            job_created?: number | undefined;
+            job_released?: number | undefined;
+            job_error?: number | undefined;
+            reused?: number | undefined;
+        };
+        traces: {
+            operation: number;
+            stage: import("./diagnostics.js").TraceStage;
+            elapsedMs: number;
+        }[];
+    };
+    private currentPhase;
+    get phase(): ShutdownPhase;
+    get(key: string): ExecutionHandle | undefined;
+    add(key: string, handle: ExecutionHandle): void;
+    track<T>(delivery: Promise<T>): Promise<T>;
+    close(drainCore: () => Promise<void>): Promise<void>;
+}

package/dist/execution.js

@@ -0,0 +1,174 @@
+import { setTimeout as pause } from "node:timers/promises";
+import { Diagnostics } from "./diagnostics.js";
+/** One host projection of a logical execution. The core completion remains authoritative. */
+export class ExecutionHandle {
+    jobs;
+    owner;
+    execution;
+    telemetry;
+    completion;
+    settled;
+    job;
+    progressHandle;
+    trace;
+    constructor(jobs, owner, execution, telemetry = new Diagnostics()) {
+        this.jobs = jobs;
+        this.owner = owner;
+        this.execution = execution;
+        this.telemetry = telemetry;
+        this.trace = telemetry.begin();
+        this.completion = execution.done;
+        const outcome = this.completion.then((v) => ({
+            status: v.state === "succeeded"
+                ? "completed"
+                : v.state === "cancelled"
+                    ? "killed"
+                    : "failed",
+            detail: v.state,
+        }));
+        this.job = jobs.start({
+            kind: "execution-bus",
+            label: "萧何 / Xiao He",
+            owner,
+            run: (handle) => {
+                this.progressHandle = handle;
+                return { done: outcome, cancel: () => this.requestCancel() };
+            },
+        });
+        telemetry.record(this.trace, "job_created");
+        this.settled = this.waitAndClean();
+    }
+    requestCancel() {
+        this.execution.cancel();
+    }
+    progress(event) {
+        this.progressHandle?.updateProgress(event.type === "progress"
+            ? String(event.payload.percent) + "%"
+            : event.type);
+    }
+    absent(error) {
+        try {
+            return (error instanceof Error &&
+                error.message === "unknown job " + this.job &&
+                !this.jobs.list(this.owner).some((v) => v.id === this.job));
+        }
+        catch {
+            return false;
+        }
+    }
+    async waitAndClean() {
+        try {
+            for (;;) {
+                const view = await this.jobs.wait(this.job, 60000, this.owner);
+                if (view.status !== "running" && view.status !== "stopping")
+                    break;
+            }
+            this.jobs.remove(this.job, this.owner);
+            this.telemetry.record(this.trace, "job_released");
+        }
+        catch (error) {
+            this.telemetry.record(this.trace, "job_error");
+            const removed = this.absent(error);
+            // Retain the original execution, including while its caller/owner is being disposed.
+            await this.completion;
+            if (removed)
+                this.telemetry.record(this.trace, "job_released");
+            if (!removed) {
+                for (let attempt = 0; attempt < 20; attempt++) {
+                    try {
+                        const view = this.jobs
+                            .list(this.owner)
+                            .find((v) => v.id === this.job && v.owner === this.owner);
+                        if (!view) {
+                            this.telemetry.record(this.trace, "job_released");
+                            break;
+                        }
+                        if (view.status !== "running" && view.status !== "stopping") {
+                            this.jobs.remove(this.job, this.owner);
+                            this.telemetry.record(this.trace, "job_released");
+                            break;
+                        }
+                    }
+                    catch {
+                        break;
+                    }
+                    await pause(10);
+                }
+                throw error;
+            }
+        }
+        finally {
+            this.progressHandle = undefined;
+        }
+    }
+}
+/** Owns host projections and active deliveries, not a second execution state machine. */
+export class ExecutionOwner {
+    handles = new Map();
+    deliveries = new Set();
+    closing;
+    telemetry = new Diagnostics();
+    create(key, jobs, owner, execution) {
+        if (this.phase !== "open")
+            throw Error("CLOSED");
+        if (this.handles.has(key))
+            throw Error("DUPLICATE_EXECUTION_HANDLE");
+        const handle = new ExecutionHandle(jobs, owner, execution, this.telemetry);
+        this.add(key, handle);
+        return handle;
+    }
+    diagnostics() {
+        return {
+            ...this.telemetry.snapshot(),
+            phase: this.phase,
+            activeProjections: this.handles.size,
+            deliveries: this.deliveries.size,
+        };
+    }
+    currentPhase = "open";
+    get phase() {
+        return this.currentPhase;
+    }
+    get(key) {
+        return this.handles.get(key);
+    }
+    add(key, handle) {
+        if (this.phase !== "open")
+            throw Error("CLOSED");
+        if (this.handles.has(key))
+            throw Error("DUPLICATE_EXECUTION_HANDLE");
+        this.handles.set(key, handle);
+        const release = () => {
+            if (this.handles.get(key) === handle)
+                this.handles.delete(key);
+        };
+        void handle.settled.then(release, release);
+    }
+    track(delivery) {
+        this.deliveries.add(delivery);
+        const release = () => this.deliveries.delete(delivery);
+        void delivery.then(release, release);
+        return delivery;
+    }
+    close(drainCore) {
+        if (this.closing)
+            return this.closing;
+        this.currentPhase = "stopping";
+        let resolve, reject;
+        this.closing = new Promise((r, j) => {
+            resolve = r;
+            reject = j;
+        });
+        void (async () => {
+            const core = drainCore();
+            this.currentPhase = "draining";
+            await core;
+            await Promise.allSettled([...this.deliveries]);
+            this.currentPhase = "releasing";
+            await Promise.allSettled([...this.handles.values()].map((h) => h.settled));
+            this.handles.clear();
+            this.currentPhase = "closed";
+        })().then(resolve, reject);
+        return this.closing;
+    }
+}

package/dist/plugin.js

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { setTimeout as pause } from "node:timers/promises";
+import { ExecutionOwner } from "./execution.js";
 import { ExecutionBus, parse } from "./bus.js";
 import { testHandler, readHandler } from "./handlers.js";
 export const name = "execution-bus";
@@ -8,12 +8,8 @@ export function apply(ctx) {
     const bus = new ExecutionBus();
     bus.register("test", testHandler);
     bus.register("host.read", readHandler);
-    const sharedJobs = new Map();
-    ctx.effect(() => async () => {
-        await bus.close();
-        await Promise.allSettled(sharedJobs.values());
-        sharedJobs.clear();
-    });
+    const executions = new ExecutionOwner();
+    ctx.effect(() => () => executions.close(() => bus.close()));
     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.",
@@ -42,147 +38,79 @@ export function apply(ctx) {
             schema: {},
             render: (_a, v) => [{ type: "text", text: JSON.stringify(v) }],
         },
-        async execute(raw, exec) {
-            if (!exec.agent)
-                throw Error("OWNING_SESSION_REQUIRED");
-            const owner = {
-                sessionId: String(exec.agent.id),
-                callId: String(exec.callId),
-            }, m = parse(raw);
-            if (m.type !== "request")
-                return bus.command(owner, m);
-            let handle;
-            const attached = bus.submit(owner, m, (event) => handle?.updateProgress(event.type === "progress"
-                ? String(event.payload.percent) + "%"
-                : event.type), async (input, signal) => {
-                const result = await ctx.tools.execute({
-                    name: "read",
-                    callId: (String(exec.callId) +
-                        ":bus:" +
-                        randomUUID()),
-                    rootCallId: exec.rootCallId,
-                    parent: exec.token,
-                    agent: exec.agent,
-                    arguments: input,
-                    signal,
-                });
-                if (result.isError)
-                    throw Error("HOST_READ_FAILED");
-                return result.value;
+        execute(raw, exec) {
+            if (executions.phase !== "open")
+                return Promise.reject(Error("CLOSED"));
+            return executions.track(dispatch(raw, exec));
+        },
+    });
+    async function dispatch(raw, exec) {
+        if (!exec.agent)
+            throw Error("OWNING_SESSION_REQUIRED");
+        const owner = {
+            sessionId: String(exec.agent.id),
+            callId: String(exec.callId),
+        }, m = parse(raw);
+        if (m.type !== "request")
+            return bus.command(owner, m);
+        let projection;
+        const attached = bus.submit(owner, m, (event) => projection?.progress(event), async (input, signal) => {
+            const result = await ctx.tools.execute({
+                name: "read",
+                callId: (String(exec.callId) +
+                    ":bus:" +
+                    randomUUID()),
+                rootCallId: exec.rootCallId,
+                parent: exec.token,
+                agent: exec.agent,
+                arguments: input,
+                signal,
             });
-            // Terminal reuse is a read of an existing result, not admission of new work.
-            if (attached.accepted.payload.state !== "queued" &&
-                attached.accepted.payload.state !== "running") {
-                try {
-                    const value = await attached.done;
-                    attached.returned();
-                    return value;
-                }
-                finally {
-                    attached.detach();
-                }
-            }
-            const abort = () => attached.cancel();
-            const jobKey = JSON.stringify([owner.sessionId, m.requestId]);
-            let settled = sharedJobs.get(jobKey);
-            if (!settled) {
-                try {
-                    const outcome = attached.done.then((v) => ({
-                        status: v.state === "succeeded"
-                            ? "completed"
-                            : v.state === "cancelled"
-                                ? "killed"
-                                : "failed",
-                        detail: v.state,
-                    }));
-                    const job = ctx.jobs.start({
-                        kind: "execution-bus",
-                        label: "萧何 / Xiao He",
-                        owner: exec.agent.id,
-                        run(h) {
-                            handle = h;
-                            return {
-                                done: outcome,
-                                cancel: abort,
-                            };
-                        },
-                    });
-                    const ownerId = exec.agent.id;
-                    // One registered host waiter suppresses extra completion messages for every attachment.
-                    settled = (async () => {
-                        try {
-                            for (;;) {
-                                const view = await ctx.jobs.wait(job, 60000, ownerId);
-                                if (view.status !== "running" && view.status !== "stopping")
-                                    break;
-                            }
-                            ctx.jobs.remove(job, ownerId);
-                        }
-                        catch (error) {
-                            // rc.2 has no typed not-found code. Match only this minted Job and
-                            // confirm absence in the original owner scope; never swallow access/service errors.
-                            let alreadyRemoved = false;
-                            try {
-                                alreadyRemoved =
-                                    error instanceof Error &&
-                                        error.message === `unknown job ${job}` &&
-                                        !ctx.jobs.list(ownerId).some((view) => view.id === job);
-                            }
-                            catch {
-                                /* Preserve the original wait/cleanup error. */
-                            }
-                            // A broken wait channel does not terminate execution. Keep caller cancellation
-                            // attached, drain both producer and host outcome, then attempt cleanup once.
-                            await attached.done;
-                            if (!alreadyRemoved) {
-                                // No scope-owned observer: teardown can remove it before settlement.
-                                // After producer drain, allow a bounded host commit window. This is
-                                // program-side cleanup only, never execution retry or model polling.
-                                for (let attempt = 0; attempt < 20; attempt++) {
-                                    try {
-                                        const view = ctx.jobs
-                                            .list(ownerId)
-                                            .find((view) => view.id === job && view.owner === ownerId);
-                                        if (!view)
-                                            break;
-                                        if (view.status !== "running" &&
-                                            view.status !== "stopping") {
-                                            ctx.jobs.remove(job, ownerId);
-                                            break;
-                                        }
-                                    }
-                                    catch {
-                                        break;
-                                    }
-                                    await pause(10);
-                                }
-                                throw error;
-                            }
-                        }
-                    })();
-                    sharedJobs.set(jobKey, settled);
-                    void settled.then(() => sharedJobs.delete(jobKey), () => sharedJobs.delete(jobKey));
-                }
-                catch {
-                    abort();
-                    await attached.done;
-                    attached.detach();
-                    throw Error("HOST_JOB_UNAVAILABLE");
-                }
-            }
-            exec.signal.addEventListener("abort", abort, { once: true });
-            if (exec.signal.aborted)
-                abort();
+            if (result.isError)
+                throw Error("HOST_READ_FAILED");
+            return result.value;
+        });
+        // Terminal reuse is a read of an existing result, not admission of new work.
+        if (attached.accepted.payload.state !== "queued" &&
+            attached.accepted.payload.state !== "running") {
             try {
-                await settled;
                 const value = await attached.done;
                 attached.returned();
                 return value;
             }
             finally {
-                exec.signal.removeEventListener("abort", abort);
                 attached.detach();
             }
-        },
-    });
+        }
+        const abort = () => attached.cancel();
+        const jobKey = JSON.stringify([owner.sessionId, m.requestId]);
+        let execution = executions.get(jobKey);
+        if (execution)
+            attached.detach(); // only the first attachment projects progress into the shared Job
+        if (!execution) {
+            try {
+                execution = executions.create(jobKey, ctx.jobs, exec.agent.id, attached);
+                projection = execution;
+            }
+            catch {
+                abort();
+                await attached.done;
+                attached.detach();
+                throw Error("HOST_JOB_UNAVAILABLE");
+            }
+        }
+        exec.signal.addEventListener("abort", abort, { once: true });
+        if (exec.signal.aborted)
+            abort();
+        try {
+            await execution.settled;
+            const value = await attached.done;
+            attached.returned();
+            return value;
+        }
+        finally {
+            exec.signal.removeEventListener("abort", abort);
+            attached.detach();
+        }
+    }
 }

package/docs/OPTIMIZATION.md

@@ -0,0 +1,47 @@
+# 引擎经验优化整合与验收
+
+本轮统一在 0.4.0 交付，不将普通 BUG 修复冒充整体架构优化，不声称模型性能已提高。运行逻辑仅作用于萧何总线及其 Job 关联；保留 0.3.0 的 PTC 派生方式、权限和原工具能力。
+
+## 优先级与交付
+
+| 优先级 | 交付 | 范围与限制 |
+|---|---|---|
+| P1 | 执行所有权集中 | 内部 ExecutionHandle 关联 core completion、请求级取消、宿主 Job 和进度；ExecutionOwner 集中跟踪共享投影及工具交付。不是第二个执行状态机 |
+| P1 | 阶段化关闭 | 停止受理 → 请求取消及排空 core → 等待活跃工具交付 → 等待并释放 Job 关联。重复关闭返回同一 Promise，先发布 closing 再触发取消，允许回调重入 |
+| P1 | 通知批次边界 | 每次固定名单；新增监听从后续事件接收；解除的监听跳过；嵌套事件按请求内序号排在当前批之后。同步与异步错误继续隔离 |
+| P2 | 有界脱敏诊断 | core diagnostics 快照及内部 Job 聚合轨迹。每个环最近 128 条；只存数值编号、阶段、耗时、计数，不存业务内容 |
+| P2 | 会话轮转 | 两会话积压测试确认 FIFO 的队头延迟后，实现受理后轮转；保持会话内 FIFO 和并发上限，无入队公平保证或时间 SLA |
+| 暂缓 | 按资源串行 | 没有真实写 Handler，不引入资源锁；PTC 原工具不被全局接管 |
+| 不做 | 工作流/线程系统 | 不加入 DAG、线程池、无锁队列、对象池或按引用数自动取消 |
+
+## 实测证据及不能推导的结论
+
+确定性压力用例中，A0 已运行，A1–A12 排队后 B0 入队：
+
+```text
+原 FIFO： A0,A1,A2,A3,A4,A5,A6,A7,A8,A9,A10,A11,A12,B0
+会话轮转：A0,A1,B0,A2,A3,A4,A5,A6,A7,A8,A9,A10,A11,A12
+```
+
+这是已受理任务的开始顺序对比，不是生产延迟、吞吐或模型轮次提升比例。运行任务不可抢占，新会话可能仍因队列满被拒绝。同一会话多个长任务也可能占用并发槽，轮转不等于资源配额。
+
+另外验证三会话、并发为二、取消一个排队任务：只执行其余 23 个不同请求，未超过并发上限，同会话开始顺序保持 FIFO。已有真实宿主等待/清理故障与卸载回归继续执行，不以纯 core 测试替代。
+
+## 如何查看诊断
+
+从包的 ./core 使用 ExecutionBus，调用 `bus.diagnostics()`。这不是新的 Agent 工具，也不提供跨会话读取入口；生产插件内部所有者的诊断尚未公开为服务或 UI。
+
+阶段 elapsedMs 相对于本次受理的单调时钟时间：started 减 accepted 为排队时间、terminal 减 started 为执行时间、returned 减 terminal 为首次返回标记延迟。cancel_requested 与 terminal 间隔只能解释为取消请求到执行终态，未必为成功取消。
+
+查询快照会遍历最多 recordLimit 条记录计算保留结果字节数；只在开发者调用时发生。环形轨迹不会记录结果内容，但仍是内部运行信息，不作为可信审计/授权依据。进程关闭后不恢复。
+
+## 引擎经验来源
+
+- [Bevy Task v0.16.1](https://github.com/bevyengine/bevy/blob/v0.16.1/crates/bevy_tasks/src/task.rs)：区分任务完成、取消和 detach；没有照搬 Rust Drop 语义。
+- [Bevy CommandQueue v0.16.1](https://github.com/bevyengine/bevy/blob/v0.16.1/crates/bevy_ecs/src/world/command_queue.rs)：先确定消费边界再调用外部代码；未移植 unsafe/字节布局。
+- [Godot 4.4 MessageQueue](https://github.com/godotengine/godot/blob/4.4/core/object/message_queue.cpp)：派发重入与消费位置的明确约束。
+- [Godot 4.4 WorkerThreadPool](https://github.com/godotengine/godot/blob/4.4/core/object/worker_thread_pool.h)：分阶段关闭；没有增加线程池。
+- [Unity Addressables](https://docs.unity3d.com/Packages/com.unity.addressables@1.21/manual/AddressableAssetsAsyncOperationHandle.html)：区分异步操作所有权、释放和取消，不增加模拟指针引用计数。
+- [Stride Scheduler](https://github.com/stride3d/stride/blob/master/sources/core/Stride.Core.MicroThreading/Scheduler.cs)、[O3DE JobCancelGroup](https://github.com/o3de/o3de/blob/development/Code/Framework/AzCore/AzCore/Jobs/JobCancelGroup.h)：作为调研参考，分支链接可变；不宣称固定 SHA 或已构建这些引擎。
+
+本项目是依据原则自行实现，没有复制这些引擎的源码或引入其运行依赖。

package/docs/protocol.md

@@ -44,7 +44,7 @@ core 的 `submit()` 返回 `accepted`、`done` Promise 和取消/解除通知/
 
 通知包含版本、消息 ID、请求 ID、关联 ID（correlationId）、请求内序号、类型与 payload。accepted 的 correlationId 对应本次提交消息，序号是当前快照；后续事件关联首次请求 messageId，新增序号。类型包括 started、progress、cancel_requested 和 succeeded、failed、cancelled、unknown 四种终态事件。
 
-Handler 报告的进度序号必须递增；重复、乱序及终态后进度忽略，百分比须在 0–100 内。事件及 payload 在通知前冻结。每个附着独立解除通知，detach 不取消执行；取消是另一个操作。观察者抛错或异步拒绝被隔离，不记录异常原文，也不等待观察者资源完成。
+Handler 报告的进度序号必须递增；重复、乱序及终态后进度忽略，百分比须在 0–100 内。事件及 payload 在通知前冻结。每个附着独立解除通知，detach 不取消执行；取消是另一个操作。派发开始时固定本批名单，派发期间新增监听从下个事件开始接收；已解除且尚未轮到的回调跳过。回调中触发的嵌套事件按序排在当前批之后，不跨越当前通知。观察者抛错或异步拒绝被隔离，不记录异常原文，也不等待观察者资源完成。
 
 ## 3. 执行状态和交付标记
 
@@ -80,13 +80,13 @@ queued → running → succeeded / failed / cancelled / unknown
 | 单结果 JSON | 64 KiB |
 | 终态保留期 | 自完成起 1 小时 |
 
-新执行请求受队列和记录容量限制；运行中重复附着受消息/监听名额限制；未过期终态复用不申请新 Job。宿主新 Job 准入还有独立容量要求。没有公平性 SLA，单会话可能占满总线。
+新执行请求受队列和记录容量限制；运行中重复附着受消息/监听名额限制；未过期终态复用不申请新 Job。宿主新 Job 准入还有独立容量要求。已受理的排队任务按会话轮转，各会话内部 FIFO；不抢占运行任务，没有完成时间 SLA，单会话仍可占满受理容量，不保证其他会话一定获得入队名额。
 
 core 不传配置时用默认值；显式配置必须完整包含 concurrency、queueLimit、recordLimit、resultBytes、retentionMs 五项正安全整数。拒绝缺项、额外字段与访问器；构造时复制冻结，无动态更新接口。
 
 保留期通过新请求或控制消息触发惰性清理，也可调用实例 `sweep()`；不是精确的一小时定时删除，闲置时记录可能继续占内存，但后续正常查询会先清理过期记录。无磁盘任务库。结果大小检查在 Handler 返回后进行，Handler 自身也必须限制内存分配。敏感返回内容仍可能进入宿主会话日志，本插件不是秘密识别器。
 
-关闭停止受理，取消队列和运行任务，等待合作 Handler。正常路径复用 Job 窗口等待；服务异常后仍先排空执行，再有界检查记录并保留原服务错误。持续故障可能留记录到宿主生命周期清理，不合作 Handler 可能阻碍关闭。
+关闭幂等且可重入，多次 close 返回同一 Promise。core 先停止受理，取消队列和运行任务，排空后清理内存；宿主执行所有者继续等原工具交付路径及 Job 关联结束，再释放。等待某个 Handler 的通知回调里不应反向 await 整个关闭完成。正常路径复用 Job 窗口等待；服务异常后仍先排空执行，再有界检查记录并保留原服务错误。持续故障可能留记录到宿主生命周期清理，不合作 Handler 可能阻碍关闭。
 
 ## 5. 重试与恢复语义
 
@@ -94,7 +94,13 @@ core 不传配置时用默认值；显式配置必须完整包含 concurrency、
 
 同存活实例、保存期内的请求复用不是端到端 exactly-once；每个实际工具调用仍有自己的宿主结果记录。没有外部终态注入接口，也没有跨重启恢复：任一阶段进程崩溃都会丢失插件内存状态。宿主日志不能复活旧 Promise，不追加聊天消息冒充原调用恢复。
 
-## 6. 扩展 Handler
+## 6. 诊断
+
+core 实例的 `diagnostics()` 返回只读用途的独立快照：阶段计数、最近 128 条 `{operation,stage,elapsedMs}` 轨迹、关闭阶段、队列/运行/记录数及保留结果字节数。operation 是实例内递增数值，不是消息或会话 ID；elapsedMs 以单调时钟计算，阶段时间均相对受理时间，可相减得到排队/执行/返回延迟。复用计数仅在附着受理成功时增加；返回阶段按逻辑结果首次标记，不代表每个工具调用都持久化。
+
+宿主执行所有者另有内部 Job 创建/释放/异常聚合轨迹，不作为模型工具或公开服务导出；其 operation 是独立编号，不能与 core 轨迹按编号关联。数据只在内存，不保存参数、结果、Handler 名称、请求/会话 ID、异常文本或聊天记录。总计数会持续累积，环形轨迹有界；异常计数不等于每次清理最终失败。
+
+## 7. 扩展 Handler
 
 包的 `./core` 导出 ExecutionBus、Handler、Capability 类型。Handler 只接收输入、requestId、signal、progress 和可选最小 capability，不接收聊天历史。register 返回绑定唯一注册令牌的幂等注销函数，不会误删后来同名注册；已受理请求继续持有原 Handler。
 

package/docs/releases/0.4.0.md

@@ -0,0 +1,17 @@
+# 萧何 / Xiao He 0.4.0
+
+## 本版变化
+
+统一交付引擎调研中优先级最高的生命周期优化，不改变请求级取消、内存保存或宿主权限规则。
+
+- 内部执行句柄集中持有完成结果、请求取消及宿主 Job 投影，core 仍是执行状态唯一事实源。共享执行只由首个附着投影进度，重复调用不重复创建 Job。
+- 关闭分阶段、可重入并幂等，多次 close 返回同一完成 Promise，等待已启动执行和活跃工具交付后释放关联。
+- 固定事件通知批次：回调中新增监听不接收当前事件，解除监听跳过尚未调用部分；嵌套取消/终态按序派发。事件仍不可变，观察者异常继续隔离。
+- core 增加 diagnostics()：最近 128 条数值阶段轨迹及容量快照，内部执行所有者另计 Job 事件。无业务参数、结果、请求/会话 ID 或错误文本，无新增模型工具。
+- 压力验证后将已受理调度改为按会话轮转，保持会话内 FIFO；不抢占、不保证入队公平或完成时间。
+
+## 验证和范围
+
+新增通知重入/关闭、诊断脱敏及多会话调度回归。确定性用例 B0 从 A 的 12 个积压任务之后提前至 A1 后执行，不代表真实模型性能提升；具体顺序与边界见优化说明。
+
+沿用 PTC 声明派生，原工具不强制经过总线；Handler 仍只含 test/host.read。资源锁、DAG、线程池、对象池、跨重启恢复不在本版。真实模型、桌面 UI 和实际沙箱仍未验收。兼容 DSH 0.2.0-rc.2，非商业源码公开许可；不安装或重启日常 DSH。

package/docs/validation.md

@@ -1,6 +1,6 @@
 # 验证范围与使用限制
 
-本文说明当前版本的证据边界，不是生产环境认证。当前预设能力基线为 **v0.3.0**；总线执行核心沿用此前验证，新增的是宿主 PTC 声明派生与叠加模式。验证环境为 Windows、Node.js 24.21.0，宿主组件锁定 DSH 0.2.0-rc.2、Cordis 4.0.4。
+本文说明当前版本的证据边界，不是生产环境认证。当前优化基线为 **v0.4.0**，新增执行所有权/关闭、通知重入边界、数值诊断及会话轮转；预设沿用 v0.3.0 的宿主 PTC 声明派生方式。验证环境为 Windows、Node.js 24.21.0，宿主组件锁定 DSH 0.2.0-rc.2、Cordis 4.0.4。
 
 ## 已验证什么？
 
@@ -13,7 +13,7 @@
 | 故障注入 | 克隆失败、观察者拒绝、Job 等待/清理异常、先行移除与卸载交错 | 指定故障下的回归约束；不证明所有故障组合都已覆盖 |
 | 候选包 | 严格文件白名单、临时目录生产依赖安装、入口注册 | 包可安装和加载；安装验证使用简化宿主夹具，不是桌面插件管理器验收 |
 
-v0.2.11 本地回归基线为 **48/48 通过**；本版新增声明保真、真实注册生命周期及真实 Node PTC 桥接测试，最新数量以命令输出为准。测试项数量是用例数量，不是全部产品验收条数。当前结果请重新运行下述命令；文档测试数不应代替实际输出。
+此前 v0.3.0 本地回归为 **51/51 通过**；本轮新增生命周期与多会话压力回归，最新数量以命令输出为准。测试项数量是用例数量，不是全部产品验收条数。当前结果请重新运行下述命令；文档测试数不应代替实际输出。
 
 ```powershell
 npm ci --include=dev --ignore-scripts
@@ -49,7 +49,7 @@ eb95b4e51675f5f1821275e0812ef4dd4984b1aba45a52fbc6bab3518bbf6f38
 ## 需要知道的运行约束
 
 1. 受理、队列、结果及交付标记均在内存。进程关闭会丢失，宿主会话日志不等于插件恢复执行权。
-2. 同一预设的会话共享总线容量，结果访问按会话隔离；不是独立进程或资源安全隔离。
+2. 同一预设的会话共享总线容量，已受理任务会话轮转、会话内 FIFO；结果访问按会话隔离，不是独立进程或资源安全隔离，也不保证入队名额公平。
 3. 取消任一正在等待的重复调用会请求取消整个逻辑执行，不是仅停止该等待者。
 4. 已终态且未过期的请求可直接复用结果，不申请新 Job；仍须通过身份、冲突及消息额度检查。
 5. 等待服务异常后先排空原执行，再有界检查宿主记录；服务持续不可用时记录可能留到所属生命周期清理。不合作 Handler 仍可能阻碍关闭。

package/package.json

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