@actiondock/core 2.5.1 → 2.6.0

package/dist/process/control-arbiter.js

@@ -0,0 +1,251 @@
+import { randomUUID } from "node:crypto";
+import { ACCESS_DENIED, CONTROL_BUSY, CONTROL_EXPIRED, CONTROL_REVOKED, PROCESS_QUARANTINED, QUOTA_EXCEEDED, ProcessError, } from "../errors.js";
+/**
+ * 控制权仲裁器。
+ *
+ * 单一职责：独占控制权状态机的全部推进路径——
+ * - 直接授予与 FIFO 等待队列（唯一唤醒）
+ * - TTL 定时器生命周期（设置、续租换新、清理）
+ * - 到期复核（复合控制态与凭据双重校验，转隔离而非释放）
+ * - 操作授权校验（write/control 提交前与调度复核共用）
+ * - 终态等待者单一拒绝入口
+ */
+export class ControlArbiter {
+    host;
+    constructor(host) {
+        this.host = host;
+    }
+    /**
+     * 尝试立即授予控制权：控制权空闲且无等待者时直接授予，
+     * 否则按 FIFO 进入等待队列并返回等待 Promise。
+     *
+     * 调用方（原 acquire 请求）在排队路径 resolve 后负责预约结算；
+     * 唤醒方负责凭据落盘，保持两阶段时序不变。
+     */
+    tryAcquire(proc, input, call, runId) {
+        // 若控制权空闲且无等待者，直接授予
+        if (proc.info.control === "free" && proc.acquireWaiters.length === 0) {
+            const grant = this.grantControl(proc, input.requestId, input.ttlMs, runId);
+            return { granted: true, waiter: Promise.resolve(grant) };
+        }
+        // 控制权已被持有，检查等待队列配额并进入 FIFO 排队
+        if (proc.acquireWaiters.length >= this.host.maxWaitersPerProcess) {
+            throw new ProcessError(QUOTA_EXCEEDED, "Process acquire waiter quota exceeded", {
+                limit: this.host.maxWaitersPerProcess,
+            });
+        }
+        const totalHostWaiters = this.host.countHostAcquireWaiters();
+        if (totalHostWaiters >= this.host.maxWaitersPerHost) {
+            throw new ProcessError(QUOTA_EXCEEDED, "Host acquire waiter quota exceeded", {
+                limit: this.host.maxWaitersPerHost,
+            });
+        }
+        // 排队路径：由唤醒方在授予时落盘凭据；原请求 resolve 后负责预约 commit
+        const waiter = this.enqueueWaiter(proc, input, call, runId);
+        return { granted: false, waiter };
+    }
+    /**
+     * FIFO 入队单个等待者：注册超时定时器、中止监听与自清理钩子。
+     */
+    enqueueWaiter(proc, input, call, runId) {
+        return new Promise((resolve, reject) => {
+            let timer;
+            const waiter = {
+                requestId: input.requestId,
+                waitMs: input.waitMs,
+                ttlMs: input.ttlMs,
+                runId,
+                resolve: (granted) => {
+                    cleanup();
+                    resolve(granted);
+                },
+                reject: (err) => {
+                    cleanup();
+                    reject(err);
+                },
+            };
+            const cleanup = () => {
+                if (timer)
+                    clearTimeout(timer);
+                const idx = proc.acquireWaiters.indexOf(waiter);
+                if (idx !== -1) {
+                    proc.acquireWaiters.splice(idx, 1);
+                }
+                if (call?.signal && waiter.onAbort) {
+                    call.signal.removeEventListener("abort", waiter.onAbort);
+                }
+            };
+            if (call?.signal) {
+                if (call.signal.aborted) {
+                    reject(call.signal.reason ?? new ProcessError(CONTROL_BUSY, "Acquire cancelled"));
+                    return;
+                }
+                waiter.onAbort = () => {
+                    cleanup();
+                    reject(call.signal?.reason ?? new ProcessError(CONTROL_BUSY, "Acquire cancelled"));
+                };
+                call.signal.addEventListener("abort", waiter.onAbort, { once: true });
+            }
+            timer = setTimeout(() => {
+                cleanup();
+                reject(new ProcessError(CONTROL_BUSY, "Timed out waiting for process control", {
+                    waitMs: input.waitMs,
+                }));
+            }, input.waitMs);
+            if (typeof timer?.unref === "function") {
+                timer.unref();
+            }
+            proc.acquireWaiters.push(waiter);
+        });
+    }
+    /**
+     * 授予指定受管进程控制令牌：递增控制纪元、登记凭据并设置 TTL 定时器。
+     */
+    grantControl(proc, requestId, ttlMs, runId) {
+        proc.controlEpoch += 1;
+        const token = `tok_${proc.info.id}_${proc.controlEpoch}_${randomUUID().replace(/-/g, "")}`;
+        const expiresAt = new Date(Date.now() + ttlMs).toISOString();
+        proc.info.control = "held";
+        proc.currentGrant = {
+            token,
+            epoch: proc.controlEpoch,
+            ttlMs,
+            expiresAt,
+            runId,
+            requestId,
+        };
+        proc.ttlTimer = setTimeout(() => {
+            this.handleGrantTtlExpired(proc);
+        }, ttlMs);
+        if (typeof proc.ttlTimer.unref === "function") {
+            proc.ttlTimer.unref();
+        }
+        void this.host.persistState(proc.info.id, {
+            control: "held",
+            controlState: "held",
+        });
+        return {
+            token,
+            expiresAt,
+        };
+    }
+    /**
+     * 续租当前有效控制令牌：先清理旧 TTL 定时器再设置新定时器，
+     * 刷新到期时刻并联动空闲定时器。
+     */
+    renewGrant(proc, ttlMs) {
+        if (proc.ttlTimer) {
+            clearTimeout(proc.ttlTimer);
+        }
+        const expiresAt = new Date(Date.now() + ttlMs).toISOString();
+        proc.currentGrant.ttlMs = ttlMs;
+        proc.currentGrant.expiresAt = expiresAt;
+        proc.ttlTimer = setTimeout(() => {
+            this.handleGrantTtlExpired(proc);
+        }, ttlMs);
+        if (typeof proc.ttlTimer.unref === "function") {
+            proc.ttlTimer.unref();
+        }
+        // 延长控制权刷新 idleTimeout
+        this.host.refreshIdleTimer(proc);
+        return {
+            token: proc.currentGrant.token,
+            expiresAt,
+        };
+    }
+    /**
+     * 显式释放控制令牌：清理 TTL 定时器、凭据置空并唤醒下一个等待者。
+     */
+    releaseGrant(proc) {
+        if (proc.ttlTimer) {
+            clearTimeout(proc.ttlTimer);
+            proc.ttlTimer = undefined;
+        }
+        proc.currentGrant = undefined;
+        proc.info.control = "free";
+        void this.host.persistState(proc.info.id, {
+            control: "free",
+            controlState: "free",
+        });
+        // 正常 release 唤醒下一个等待者
+        this.wakeNextAcquireWaiter(proc);
+    }
+    /**
+     * 唤醒排队等待控制权的下一个调用者（唯一唤醒入口）：
+     * 授予令牌、由唤醒方落盘排队凭据并 resolve 原等待 Promise。
+     */
+    wakeNextAcquireWaiter(proc) {
+        if (proc.acquireWaiters.length === 0) {
+            return;
+        }
+        const next = proc.acquireWaiters.shift();
+        const grant = this.grantControl(proc, next.requestId, next.ttlMs, next.runId);
+        void this.host.persistGrantReceipt(grant, next, proc);
+        next.resolve(grant);
+    }
+    /**
+     * 控制权到期未释放时的复核：仍处于 held 且凭据有效时转隔离（隔离而非释放）。
+     */
+    handleGrantTtlExpired(proc) {
+        if (proc.info.control !== "held" || !proc.currentGrant) {
+            return;
+        }
+        void this.host.quarantineProcess(proc.owner, proc.info.id, proc.currentGrant.token, "Control token TTL expired");
+    }
+    /**
+     * 操作提交前校验持有者令牌与授权（write/control 入队前与调度链路共用）。
+     */
+    validateOperation(proc, token) {
+        if (proc.info.control === "quarantined") {
+            throw new ProcessError(PROCESS_QUARANTINED, "Process is in quarantined state");
+        }
+        if (proc.info.control !== "held" || !proc.currentGrant) {
+            throw new ProcessError(ACCESS_DENIED, "Process control is not currently held");
+        }
+        if (proc.currentGrant.token !== token) {
+            throw new ProcessError(ACCESS_DENIED, "Invalid control token");
+        }
+        if (new Date(proc.currentGrant.expiresAt).getTime() <= Date.now()) {
+            throw new ProcessError(CONTROL_EXPIRED, "Control token has expired");
+        }
+    }
+    /**
+     * 校验当前持有凭据有效性（token 匹配且未过期），供 renew/release 提交前判定。
+     */
+    validateHeldGrant(proc, token) {
+        if (proc.info.control === "quarantined") {
+            throw new ProcessError(PROCESS_QUARANTINED, "Process is in quarantined state");
+        }
+        if (proc.info.control !== "held" || !proc.currentGrant) {
+            throw new ProcessError(CONTROL_REVOKED, "Process control is not currently held");
+        }
+        if (proc.currentGrant.token !== token) {
+            throw new ProcessError(ACCESS_DENIED, "Invalid control token");
+        }
+        if (new Date(proc.currentGrant.expiresAt).getTime() <= Date.now()) {
+            throw new ProcessError(CONTROL_EXPIRED, "Control token has expired");
+        }
+    }
+    /**
+     * 终态等待者单一拒绝入口：按 FIFO 拒绝全部排队等待者。
+     *
+     * 终态转移（exit/error/stop/quarantine）必须经由此方法清空等待队列，
+     * 禁止直接操作 acquireWaiters 数组。
+     */
+    revokeAllWaiters(proc, reason) {
+        while (proc.acquireWaiters.length > 0) {
+            const waiter = proc.acquireWaiters.shift();
+            waiter.reject(new ProcessError(reason.code, reason.message));
+        }
+    }
+    /**
+     * 清理进程全部控制权相关定时器与等待队列（stop/退出/故障路径统一入口）。
+     */
+    disposeProcess(proc) {
+        if (proc.ttlTimer) {
+            clearTimeout(proc.ttlTimer);
+            proc.ttlTimer = undefined;
+        }
+        proc.currentGrant = undefined;
+    }
+}

package/dist/process/diagnostics-sink.d.ts

@@ -0,0 +1,26 @@
+import type { Logger } from "@actiondock/sdk";
+/**
+ * 内部诊断日志汇聚器。
+ *
+ * 持有最近的持久化失败与驱动终止失败等诊断信息：优先写入注入的 logger，
+ * 缺失时保留在内存环形缓冲区，避免静默吞没异常。
+ */
+export declare class DiagnosticsSink {
+    /** 注入的 logger 缺失时保留最近诊断条目的环形缓冲容量，默认 100 */
+    static readonly DEFAULT_BUFFER_LIMIT = 100;
+    private readonly logger?;
+    private readonly bufferLimit;
+    private readonly diagnostics;
+    constructor(options?: {
+        logger?: Logger;
+        bufferLimit?: number;
+    });
+    /**
+     * 记录内部诊断信息：优先写入注入的 logger，缺失时保留在内存环形缓冲区。
+     */
+    record(message: string, err?: unknown): void;
+    /**
+     * 获取最近的内部诊断日志快照（最近条目在前）。
+     */
+    recent(): string[];
+}

package/dist/process/diagnostics-sink.js

@@ -0,0 +1,35 @@
+/**
+ * 内部诊断日志汇聚器。
+ *
+ * 持有最近的持久化失败与驱动终止失败等诊断信息：优先写入注入的 logger，
+ * 缺失时保留在内存环形缓冲区，避免静默吞没异常。
+ */
+export class DiagnosticsSink {
+    /** 注入的 logger 缺失时保留最近诊断条目的环形缓冲容量，默认 100 */
+    static DEFAULT_BUFFER_LIMIT = 100;
+    logger;
+    bufferLimit;
+    diagnostics = [];
+    constructor(options) {
+        this.logger = options?.logger;
+        this.bufferLimit = options?.bufferLimit ?? DiagnosticsSink.DEFAULT_BUFFER_LIMIT;
+    }
+    /**
+     * 记录内部诊断信息：优先写入注入的 logger，缺失时保留在内存环形缓冲区。
+     */
+    record(message, err) {
+        const detail = err instanceof Error ? `${err.name}: ${err.message}` : err !== undefined ? String(err) : "";
+        const line = detail ? `${message} (${detail})` : message;
+        this.diagnostics.push(`${new Date().toISOString()} ${line}`);
+        if (this.diagnostics.length > this.bufferLimit) {
+            this.diagnostics.shift();
+        }
+        this.logger?.warn("[ProcessManager] " + line);
+    }
+    /**
+     * 获取最近的内部诊断日志快照（最近条目在前）。
+     */
+    recent() {
+        return [...this.diagnostics].reverse();
+    }
+}

package/dist/process/index.d.ts

@@ -2,5 +2,12 @@ export * from "./cursor.js";
 export * from "./output-log.js";
 export * from "./metadata-store.js";
 export * from "./driver.js";
+export * from "./diagnostics-sink.js";
+export * from "./reservation-table.js";
+export * from "./terminal-output-cache.js";
+export * from "./run-executor.js";
+export * from "./managed-record.js";
+export * from "./control-arbiter.js";
+export * from "./input-dispatcher.js";
 export * from "./process-manager.js";
 export * from "./context-process.js";

package/dist/process/index.js

@@ -2,5 +2,12 @@ export * from "./cursor.js";
 export * from "./output-log.js";
 export * from "./metadata-store.js";
 export * from "./driver.js";
+export * from "./diagnostics-sink.js";
+export * from "./reservation-table.js";
+export * from "./terminal-output-cache.js";
+export * from "./run-executor.js";
+export * from "./managed-record.js";
+export * from "./control-arbiter.js";
+export * from "./input-dispatcher.js";
 export * from "./process-manager.js";
 export * from "./context-process.js";

package/dist/process/input-dispatcher.d.ts

@@ -0,0 +1,88 @@
+import type { OperationReceipt } from "@actiondock/sdk";
+import type { ManagedProcessRecord, ProcessOwner, QueuedOperation } from "./managed-record.js";
+import type { ControlArbiter } from "./control-arbiter.js";
+import type { ProcessRequestKey, StoredProcessRecord } from "./metadata-store.js";
+/**
+ * 输入调度器宿主协作回调集合。
+ *
+ * 持有者始终为 ProcessManager：调度器仅经回调透传副作用，不反向依赖管理器。
+ */
+export interface InputDispatcherHost {
+    /** 收据与状态落盘（异步尽力而为，失败仅记录诊断） */
+    persistReceipt(key: ProcessRequestKey, receipt: OperationReceipt, payloadHash?: string): Promise<void>;
+    persistState(processId: string, patch: Partial<StoredProcessRecord>): Promise<void>;
+    /** 写入不确定失败后的隔离处置 */
+    quarantineProcess(owner: ProcessOwner, processId: string, token?: string, reason?: string): Promise<void> | unknown;
+    /** 成功输入后的空闲定时器刷新 */
+    refreshIdleTimer(proc: ManagedProcessRecord): void;
+    /** 内部诊断记录 */
+    recordDiagnostic(message: string, err?: unknown): void;
+    /** 宿主级输入队列待写字节统计 */
+    countHostPendingInputBytes(): number;
+    /** 输入队列容量配额 */
+    readonly maxPendingQueueBytesPerProcess: number;
+    readonly maxPendingQueueBytesPerHost: number;
+}
+/**
+ * write 入队请求参数。
+ */
+export interface EnqueueWriteInput {
+    requestId: string;
+    token: string;
+    data: Uint8Array;
+    key: ProcessRequestKey;
+    payloadHash: string;
+}
+/**
+ * control 入队请求参数。
+ */
+export interface EnqueueControlInput {
+    requestId: string;
+    token: string;
+    action: QueuedOperation["action"];
+    key: ProcessRequestKey;
+    payloadHash: string;
+}
+/**
+ * 输入调度器。
+ *
+ * 单一职责：待写入输入队列的入队、串行调度与接管——
+ * - 入队：同步阶段完成容量检查与字节预扣（同一同步块，杜绝 await 窗口配额穿透），异步阶段落盘并推送队列
+ * - 调度：inputQueue 串行循环，全部 await 返回点保留取消纪元与队首身份双重校验
+ * - 接管：takeoverQueue 同步原子原语（纪元递增、标记失败、落盘回调、清空、字节归零）
+ *
+ * 调度循环对控制权的复核经控制权仲裁器委托执行。
+ */
+export declare class InputDispatcher {
+    private readonly host;
+    private readonly arbiter;
+    constructor(host: InputDispatcherHost, arbiter: ControlArbiter);
+    /**
+     * 入队写入操作：同步阶段完成授权校验、输入通道校验、队列容量检查与字节预扣；
+     * 异步阶段落盘排队收据并推送队列，随后触发串行调度。
+     *
+     * 返回的 Promise 在收据成功入队后 resolve（state 为 queued）；
+     * 落盘或推送失败时回滚字节预扣并原样抛出。
+     */
+    enqueueWrite(proc: ManagedProcessRecord, input: EnqueueWriteInput): Promise<OperationReceipt>;
+    /**
+     * 入队控制指令：异步阶段落盘排队收据并推送队列，随后触发串行调度。
+     */
+    enqueueControl(proc: ManagedProcessRecord, input: EnqueueControlInput): Promise<OperationReceipt>;
+    /**
+     * 输入队列接管原语：递增取消纪元、标记全部待调度操作失败并清空队列。
+     *
+     * 同步原子序列（无 await 窗口）：纪元递增 -> 逐条标记 failed ->
+     * 逐条登记落盘回调（fire-and-forget，落盘函数内部自捕获异常）->
+     * 清空队列 -> 待写字节归零。
+     * stop 与 quarantine 接管输入队列必须经由此单一入口。
+     */
+    takeoverQueue(proc: ManagedProcessRecord, errorCode: string): void;
+    /**
+     * 串行调度执行输入队列操作。
+     *
+     * 全部 await 返回点保留双重校验：取消纪元一致（未被 stop/quarantine 接管）
+     * 且队首身份未变（未被并发结算改写）。
+     */
+    private dispatchNext;
+}

package/dist/process/input-dispatcher.js

@@ -0,0 +1,240 @@
+import { CONTROL_REVOKED, INPUT_CLOSED, INPUT_OUTCOME_UNKNOWN, PROCESS_QUARANTINED, QUEUE_FULL, ProcessError, } from "../errors.js";
+/**
+ * 输入调度器。
+ *
+ * 单一职责：待写入输入队列的入队、串行调度与接管——
+ * - 入队：同步阶段完成容量检查与字节预扣（同一同步块，杜绝 await 窗口配额穿透），异步阶段落盘并推送队列
+ * - 调度：inputQueue 串行循环，全部 await 返回点保留取消纪元与队首身份双重校验
+ * - 接管：takeoverQueue 同步原子原语（纪元递增、标记失败、落盘回调、清空、字节归零）
+ *
+ * 调度循环对控制权的复核经控制权仲裁器委托执行。
+ */
+export class InputDispatcher {
+    host;
+    arbiter;
+    constructor(host, arbiter) {
+        this.host = host;
+        this.arbiter = arbiter;
+    }
+    /**
+     * 入队写入操作：同步阶段完成授权校验、输入通道校验、队列容量检查与字节预扣；
+     * 异步阶段落盘排队收据并推送队列，随后触发串行调度。
+     *
+     * 返回的 Promise 在收据成功入队后 resolve（state 为 queued）；
+     * 落盘或推送失败时回滚字节预扣并原样抛出。
+     */
+    async enqueueWrite(proc, input) {
+        // 入队前校验授权与控制状态
+        this.arbiter.validateOperation(proc, input.token);
+        if (proc.inputClosed) {
+            throw new ProcessError(INPUT_CLOSED, "Input stream is closed");
+        }
+        const rawBytes = input.data;
+        const dataSize = rawBytes.byteLength;
+        // 待写入队列容量检查：在任何 await 前同步原子校验并预占配额
+        if (proc.pendingInputBytes + dataSize > this.host.maxPendingQueueBytesPerProcess) {
+            throw new ProcessError(QUEUE_FULL, "Process pending input queue limit exceeded", {
+                limit: this.host.maxPendingQueueBytesPerProcess,
+            });
+        }
+        const totalHostPending = this.host.countHostPendingInputBytes();
+        if (totalHostPending + dataSize > this.host.maxPendingQueueBytesPerHost) {
+            throw new ProcessError(QUEUE_FULL, "Host pending input queue limit exceeded", {
+                limit: this.host.maxPendingQueueBytesPerHost,
+            });
+        }
+        // 同步占位预扣队列配额，杜绝并发 await 窗口穿透
+        proc.pendingInputBytes += dataSize;
+        let pendingBytesCommitted = false;
+        try {
+            const receipt = {
+                requestId: input.requestId,
+                state: "queued",
+            };
+            await this.host.persistReceipt(input.key, receipt, input.payloadHash);
+            proc.inputQueue.push({
+                type: "write",
+                requestId: input.requestId,
+                token: input.token,
+                bytes: rawBytes,
+                receipt,
+                key: input.key,
+                payloadHash: input.payloadHash,
+                cancelEpoch: proc.cancelEpoch,
+            });
+            pendingBytesCommitted = true;
+            // 异步调度推进
+            queueMicrotask(() => void this.dispatchNext(proc));
+            return { ...receipt };
+        }
+        finally {
+            if (!pendingBytesCommitted) {
+                proc.pendingInputBytes = Math.max(0, proc.pendingInputBytes - dataSize);
+            }
+        }
+    }
+    /**
+     * 入队控制指令：异步阶段落盘排队收据并推送队列，随后触发串行调度。
+     */
+    async enqueueControl(proc, input) {
+        // 入队前校验授权与控制状态
+        this.arbiter.validateOperation(proc, input.token);
+        const receipt = {
+            requestId: input.requestId,
+            state: "queued",
+        };
+        await this.host.persistReceipt(input.key, receipt, input.payloadHash);
+        proc.inputQueue.push({
+            type: "control",
+            requestId: input.requestId,
+            token: input.token,
+            action: input.action,
+            receipt,
+            key: input.key,
+            payloadHash: input.payloadHash,
+            cancelEpoch: proc.cancelEpoch,
+        });
+        queueMicrotask(() => void this.dispatchNext(proc));
+        return { ...receipt };
+    }
+    /**
+     * 输入队列接管原语：递增取消纪元、标记全部待调度操作失败并清空队列。
+     *
+     * 同步原子序列（无 await 窗口）：纪元递增 -> 逐条标记 failed ->
+     * 逐条登记落盘回调（fire-and-forget，落盘函数内部自捕获异常）->
+     * 清空队列 -> 待写字节归零。
+     * stop 与 quarantine 接管输入队列必须经由此单一入口。
+     */
+    takeoverQueue(proc, errorCode) {
+        // 递增取消纪元：接管输入队列，使挂起中的 dispatch 放弃过期结算
+        proc.cancelEpoch = (proc.cancelEpoch ?? 0) + 1;
+        for (const op of proc.inputQueue) {
+            op.receipt.state = "failed";
+            op.receipt.errorCode = errorCode;
+            void this.host.persistReceipt(op.key, op.receipt, op.payloadHash);
+        }
+        proc.inputQueue = [];
+        proc.pendingInputBytes = 0;
+    }
+    /**
+     * 串行调度执行输入队列操作。
+     *
+     * 全部 await 返回点保留双重校验：取消纪元一致（未被 stop/quarantine 接管）
+     * 且队首身份未变（未被并发结算改写）。
+     */
+    async dispatchNext(proc) {
+        if (proc.isDispatching || proc.inputQueue.length === 0) {
+            return;
+        }
+        proc.isDispatching = true;
+        try {
+            while (proc.inputQueue.length > 0) {
+                const op = proc.inputQueue[0];
+                // dispatch 前校验 token、epoch 与授权（经控制权仲裁器委托复核）
+                if (proc.info.control !== "held" ||
+                    !proc.currentGrant ||
+                    proc.currentGrant.token !== op.token ||
+                    new Date(proc.currentGrant.expiresAt).getTime() <= Date.now() ||
+                    op.cancelEpoch !== proc.cancelEpoch) {
+                    if (op.cancelEpoch === proc.cancelEpoch) {
+                        op.receipt.state = "failed";
+                        op.receipt.errorCode =
+                            proc.info.control === "quarantined" ? PROCESS_QUARANTINED : CONTROL_REVOKED;
+                        await this.host.persistReceipt(op.key, op.receipt, op.payloadHash);
+                    }
+                    proc.inputQueue.shift();
+                    if (op.bytes && op.cancelEpoch === proc.cancelEpoch) {
+                        proc.pendingInputBytes -= op.bytes.byteLength;
+                    }
+                    continue;
+                }
+                op.receipt.state = "dispatching";
+                await this.host.persistReceipt(op.key, op.receipt, op.payloadHash);
+                if (op.type === "write" && op.bytes) {
+                    try {
+                        if (!proc.handle) {
+                            throw new Error("Missing driver handle");
+                        }
+                        await proc.handle.write(op.bytes);
+                        // 写入返回后校验取消纪元与队首位置：已被 stop 或 quarantine 接管则放弃过期结算
+                        if (op.cancelEpoch !== proc.cancelEpoch || proc.inputQueue[0] !== op) {
+                            continue;
+                        }
+                        op.receipt.state = "completed";
+                        op.receipt.acceptedBytes = op.bytes.byteLength;
+                        this.host.refreshIdleTimer(proc);
+                    }
+                    catch (err) {
+                        // 写入返回异常时同样校验取消纪元：被接管则放弃过期结算
+                        if (op.cancelEpoch !== proc.cancelEpoch || proc.inputQueue[0] !== op) {
+                            continue;
+                        }
+                        // 若写入出现不确定失败，结果标记为 unknown，进程转入 quarantined
+                        op.receipt.state = "unknown";
+                        op.receipt.errorCode = INPUT_OUTCOME_UNKNOWN;
+                        await this.host.persistReceipt(op.key, op.receipt, op.payloadHash);
+                        proc.inputQueue.shift();
+                        proc.pendingInputBytes -= op.bytes.byteLength;
+                        await this.host.quarantineProcess(proc.owner, proc.info.id, op.token, "Write failed with uncertain outcome");
+                        break;
+                    }
+                }
+                else if (op.type === "control" && op.action) {
+                    try {
+                        if (!proc.handle) {
+                            throw new Error("Missing driver handle");
+                        }
+                        if (op.action.type === "input-eof") {
+                            if (proc.handle.sendInputEOF) {
+                                await proc.handle.sendInputEOF();
+                            }
+                        }
+                        else if (op.action.type === "interrupt-foreground") {
+                            if (proc.handle.interruptForeground) {
+                                await proc.handle.interruptForeground();
+                            }
+                        }
+                        else if (op.action.type === "resize") {
+                            if (proc.handle.resize) {
+                                await proc.handle.resize(op.action.cols, op.action.rows);
+                            }
+                        }
+                        // 控制指令返回后校验取消纪元与队首位置：已被 stop 或 quarantine 接管则放弃过期结算
+                        if (op.cancelEpoch !== proc.cancelEpoch || proc.inputQueue[0] !== op) {
+                            continue;
+                        }
+                        if (op.action.type === "input-eof") {
+                            proc.inputClosed = true;
+                            await this.host.persistState(proc.info.id, { inputClosed: true });
+                        }
+                        op.receipt.state = "completed";
+                        this.host.refreshIdleTimer(proc);
+                    }
+                    catch (err) {
+                        if (op.cancelEpoch !== proc.cancelEpoch || proc.inputQueue[0] !== op) {
+                            continue;
+                        }
+                        op.receipt.state = "failed";
+                        op.receipt.errorCode = err instanceof ProcessError ? err.code : "CONTROL_FAILED";
+                        if (err instanceof Error && err.message) {
+                            op.receipt.errorMessage = err.message;
+                        }
+                        this.host.recordDiagnostic(`Control action '${op.action.type}' failed for request '${op.requestId}'`, err);
+                    }
+                }
+                // 结算前再次校验：若结算窗口内被 stop 或 quarantine 接管则放弃改写
+                if (op.cancelEpoch !== proc.cancelEpoch || proc.inputQueue[0] !== op) {
+                    continue;
+                }
+                await this.host.persistReceipt(op.key, op.receipt, op.payloadHash);
+                proc.inputQueue.shift();
+                if (op.bytes) {
+                    proc.pendingInputBytes -= op.bytes.byteLength;
+                }
+            }
+        }
+        finally {
+            proc.isDispatching = false;
+        }
+    }
+}