@actiondock/core 2.5.1 → 2.7.0

package/dist/process/process-manager.js

@@ -1,10 +1,16 @@
 import { createHash, randomUUID } from "node:crypto";
 import { decodeBytes, encodeBytes, } from "@actiondock/sdk";
-import { ACCESS_DENIED, CONTROL_BUSY, CONTROL_EXPIRED, CONTROL_REVOKED, INPUT_CLOSED, INPUT_OUTCOME_UNKNOWN, INPUT_VALIDATION_FAILED, NOT_FOUND, PROCESS_CANCELLED, PROCESS_LOST, PROCESS_QUARANTINED, PROCESS_SPAWN_ERROR, PROCESS_TIMEOUT, QUEUE_FULL, QUOTA_EXCEEDED, REQUEST_CONFLICT, SERVER_ERROR, UNSUPPORTED_CAPABILITY, INVALID_CURSOR, OUTPUT_UNAVAILABLE, ProcessError, } from "../errors.js";
+import { ACCESS_DENIED, CONTROL_BUSY, CONTROL_REVOKED, INPUT_VALIDATION_FAILED, NOT_FOUND, PROCESS_CANCELLED, PROCESS_LOST, PROCESS_QUARANTINED, PROCESS_SPAWN_ERROR, QUOTA_EXCEEDED, REQUEST_CONFLICT, SERVER_ERROR, UNSUPPORTED_CAPABILITY, INVALID_CURSOR, OUTPUT_UNAVAILABLE, ProcessError, } from "../errors.js";
 import { parseCursor, compareCursorPos } from "./cursor.js";
 import { ContextProcessAPI } from "./context-process.js";
+import { ControlArbiter } from "./control-arbiter.js";
+import { InputDispatcher } from "./input-dispatcher.js";
+import { DiagnosticsSink } from "./diagnostics-sink.js";
 import { MemoryProcessMetadataStore, } from "./metadata-store.js";
 import { ProcessOutputLog } from "./output-log.js";
+import { ReservationTable, } from "./reservation-table.js";
+import { RunExecutor } from "./run-executor.js";
+import { TerminalOutputCache } from "./terminal-output-cache.js";
 /**
  * 格式化生成作用域唯一隔离字符串。
  */
@@ -95,12 +101,6 @@ function toStoredProcessRecord(owner, info, startRequestId) {
         startRequestId,
     };
 }
-/**
- * 格式化同步幂等预占键。
- */
-function formatReservationKey(key, operation) {
-    return `${key.hostEpoch}:${key.scope}:${key.processId ?? ""}:${operation}:${key.requestId}`;
-}
 /**
  * 校验正整数毫秒时长参数，非法时抛出参数错误。
  */
@@ -129,18 +129,21 @@ export class ProcessManager {
     defaultLimits;
     drainDeadlineMs;
     terminalLogRetentionMs;
-    logger;
     processes = new Map();
-    /** 已驱逐进程的输出日志缓存：附带时间戳支撑 TTL 过期回收与 LRU 淘汰 */
-    evictedOutputLogs = new Map();
-    /** 已淘汰输出日志的墓碑缓存：防止因日志淘汰静默丢失输出数据，支撑缺口明确告知与不可用异常 */
-    evictedOutputTombstones = new Map();
+    /** 内部诊断日志汇聚器：未注入 logger 时保留最近的持久化与驱动错误，避免静默吞没异常 */
+    diagnosticsSink;
     /** 同步幂等预占表：以复合键在异步落盘窗口内锁定并发重复请求 */
-    requestReservations = new Map();
+    reservationTable;
+    /** 终态输出日志保留缓存：附带 TTL 过期回收与 LRU 淘汰，及墓碑登记 */
+    terminalOutputCache;
+    /** 一次性 run 执行器：仅依赖驱动、错误映射与输入校验，不触碰进程注册表 */
+    runExecutor;
+    /** 控制权仲裁器：独占控制权状态机全部推进路径的唯一持有者 */
+    controlArbiter;
+    /** 输入调度器：输入队列入队、串行调度与接管原语的唯一持有者 */
+    inputDispatcher;
     initPromise;
     isShutdown = false;
-    /** 内部诊断日志：未注入 logger 时保留最近的持久化与驱动错误，避免静默吞没异常 */
-    diagnostics = [];
     constructor(options) {
         this.hostEpoch = options.hostEpoch ?? `epoch-${Date.now()}-${randomUUID().slice(0, 8)}`;
         this.driver = options.driver;
@@ -162,7 +165,37 @@ export class ProcessManager {
         };
         this.drainDeadlineMs = options.drainDeadlineMs ?? 5000;
         this.terminalLogRetentionMs = options.terminalLogRetentionMs ?? 10 * 60 * 1000;
-        this.logger = options.logger;
+        this.diagnosticsSink = new DiagnosticsSink({ logger: options.logger });
+        this.reservationTable = new ReservationTable();
+        this.terminalOutputCache = new TerminalOutputCache({
+            retentionMs: this.terminalLogRetentionMs,
+            maxHostBufferBytes: this.quotas.maxOutputBufferBytesPerHost,
+        });
+        this.runExecutor = new RunExecutor(this.driver);
+        this.controlArbiter = new ControlArbiter({
+            persistState: (processId, patch) => this.persistState(processId, patch),
+            persistGrantReceipt: (grant, wait, proc) => this.persistReceipt({
+                hostEpoch: this.hostEpoch,
+                scope: proc.scope,
+                processId: proc.info.id,
+                requestId: wait.requestId,
+            }, grant, hashRequestPayload({ waitMs: wait.waitMs, ttlMs: wait.ttlMs })),
+            refreshIdleTimer: (proc) => this.refreshIdleTimer(proc),
+            quarantineProcess: (owner, processId, token, reason) => this.quarantineProcess(owner, processId, token, reason),
+            countHostAcquireWaiters: () => this.countHostAcquireWaiters(),
+            maxWaitersPerProcess: this.quotas.maxWaitersPerProcess,
+            maxWaitersPerHost: this.quotas.maxWaitersPerHost,
+        });
+        this.inputDispatcher = new InputDispatcher({
+            persistReceipt: (key, receipt, payloadHash) => this.persistReceipt(key, receipt, payloadHash),
+            persistState: (processId, patch) => this.persistState(processId, patch),
+            quarantineProcess: (owner, processId, token, reason) => this.quarantineProcess(owner, processId, token, reason),
+            refreshIdleTimer: (proc) => this.refreshIdleTimer(proc),
+            recordDiagnostic: (message, err) => this.recordDiagnostic(message, err),
+            countHostPendingInputBytes: () => this.countHostPendingInputBytes(),
+            maxPendingQueueBytesPerProcess: this.quotas.maxPendingQueueBytesPerProcess,
+            maxPendingQueueBytesPerHost: this.quotas.maxPendingQueueBytesPerHost,
+        }, this.controlArbiter);
     }
     /**
      * 初始化宿主环境，原子性收敛旧宿主遗留的非终态进程。
@@ -192,19 +225,13 @@ export class ProcessManager {
      * 记录内部诊断信息：优先写入注入的 logger，缺失时保留在内存环形缓冲区。
      */
     recordDiagnostic(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 > 100) {
-            this.diagnostics.shift();
-        }
-        this.logger?.warn("[ProcessManager] " + line);
+        this.diagnosticsSink.record(message, err);
     }
     /**
      * 获取最近的内部诊断日志快照（最近条目在前）。
      */
     get recentDiagnostics() {
-        return [...this.diagnostics].reverse();
+        return this.diagnosticsSink.recent();
     }
     /**
      * 异步落盘进程状态：捕获并记录持久化失败，杜绝静默吞没异常。
@@ -230,52 +257,16 @@ export class ProcessManager {
     }
     /**
      * 同步预占幂等请求：跨 await 的检查与落盘窗口内锁定同复合键并发调用。
-     * 返回 undefined 表示预占成功，调用方继续异步路径并在完成时调用 commit/cancel。
-     * 返回 RequestReservation 表示已有同请求进行中，调用方可等待其结果。
-     * 若已有请求负载或操作类型不同，立即抛出 REQUEST_CONFLICT 杜绝混用结果。
+     * 实现委托给独立持有的预占表，语义详见 ReservationTable.reserve。
      */
     reserveRequest(key, payloadHash, operation) {
-        const reservationKey = formatReservationKey(key, operation);
-        const existing = this.requestReservations.get(reservationKey);
-        if (existing) {
-            if (existing.payloadHash !== payloadHash || existing.operation !== operation) {
-                throw new ProcessError(REQUEST_CONFLICT, "Request conflict: identical requestId with different payload", { requestId: key.requestId });
-            }
-            return existing;
-        }
-        let resolveFn = () => { };
-        let rejectFn = () => { };
-        const promise = new Promise((res, rej) => {
-            resolveFn = res;
-            rejectFn = rej;
-        });
-        // 预占 promise 可能永远无人等待：预先挂接空捕获，避免拒绝时触发 unhandledRejection
-        promise.catch(() => { });
-        const reservation = {
-            payloadHash,
-            operation,
-            promise,
-            resolve: resolveFn,
-            reject: rejectFn,
-        };
-        this.requestReservations.set(reservationKey, reservation);
-        return undefined;
+        return this.reservationTable.reserve(key, payloadHash, operation);
     }
     commitReservation(key, operation, value) {
-        const reservationKey = formatReservationKey(key, operation);
-        const reservation = this.requestReservations.get(reservationKey);
-        if (reservation) {
-            this.requestReservations.delete(reservationKey);
-            reservation.resolve(value);
-        }
+        this.reservationTable.commit(key, operation, value);
     }
     rejectReservation(key, operation, err) {
-        const reservationKey = formatReservationKey(key, operation);
-        const reservation = this.requestReservations.get(reservationKey);
-        if (reservation) {
-            this.requestReservations.delete(reservationKey);
-            reservation.reject(err);
-        }
+        this.reservationTable.reject(key, operation, err);
     }
     /**
      * 停止全部受管进程、清理全部定时器并置为关闭态，供宿主优雅退出使用。
@@ -319,10 +310,7 @@ export class ProcessManager {
                 proc.drainTimer = undefined;
             }
         }
-        for (const [reservationKey, res] of Array.from(this.requestReservations.entries())) {
-            this.requestReservations.delete(reservationKey);
-            res.reject(new ProcessError(PROCESS_CANCELLED, "Process manager has been shut down"));
-        }
+        this.reservationTable.rejectAll(new ProcessError(PROCESS_CANCELLED, "Process manager has been shut down"));
     }
     assertNotShutdown() {
         if (this.isShutdown) {
@@ -602,75 +590,13 @@ export class ProcessManager {
                 this.commitReservation(key, "acquire", cached);
                 return cached;
             }
-            // 若控制权空闲且无等待者，直接授予
-            if (proc.info.control === "free" && proc.acquireWaiters.length === 0) {
-                const grant = this.grantControl(proc, input.requestId, input.ttlMs, runId);
+            // 控制权仲裁：空闲且无等待者时直接授予，否则 FIFO 排队等待
+            // 排队路径凭据由唤醒方落盘；原请求 resolve 后在此处结算预约，保持两阶段时序不变
+            const outcome = this.controlArbiter.tryAcquire(proc, { requestId: input.requestId, waitMs: input.waitMs, ttlMs: input.ttlMs }, call, runId);
+            const grant = await outcome.waiter;
+            if (outcome.granted) {
                 await this.metadataStore.recordRequest(key, grant, payloadHash);
-                this.commitReservation(key, "acquire", grant);
-                return grant;
             }
-            // 控制权已被持有，检查等待队列配额并进入 FIFO 排队
-            if (proc.acquireWaiters.length >= this.quotas.maxWaitersPerProcess) {
-                throw new ProcessError(QUOTA_EXCEEDED, "Process acquire waiter quota exceeded", {
-                    limit: this.quotas.maxWaitersPerProcess,
-                });
-            }
-            const totalHostWaiters = this.countHostAcquireWaiters();
-            if (totalHostWaiters >= this.quotas.maxWaitersPerHost) {
-                throw new ProcessError(QUOTA_EXCEEDED, "Host acquire waiter quota exceeded", {
-                    limit: this.quotas.maxWaitersPerHost,
-                });
-            }
-            // 排队路径：由 wakeNextAcquireWaiter 在授予时落盘凭据并结算预占
-            const grant = await 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(PROCESS_CANCELLED, "Acquire cancelled"));
-                        return;
-                    }
-                    waiter.onAbort = () => {
-                        cleanup();
-                        reject(call.signal?.reason ?? new ProcessError(PROCESS_CANCELLED, "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);
-            });
             this.commitReservation(key, "acquire", grant);
             return grant;
         }
@@ -686,36 +612,9 @@ export class ProcessManager {
         checkPositiveDurationMs(ttlMs, "ttlMs");
         await this.ensureInitialized();
         const proc = await this.getOrLoadProcess(owner, id);
-        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");
-        }
-        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.refreshIdleTimer(proc);
-        return {
-            token: proc.currentGrant.token,
-            expiresAt,
-        };
+        // 提交前校验持有凭据有效性，随后由仲裁器清理旧定时器并设置新定时器
+        this.controlArbiter.validateHeldGrant(proc, token);
+        return this.controlArbiter.renewGrant(proc, ttlMs);
     }
     /**
      * 显式释放控制令牌，允许后续控制者申请。
@@ -723,6 +622,7 @@ export class ProcessManager {
     async release(owner, id, token, call) {
         await this.ensureInitialized();
         const proc = await this.getOrLoadProcess(owner, id);
+        // 提交前校验持有凭据有效性
         if (proc.info.control === "quarantined") {
             throw new ProcessError(PROCESS_QUARANTINED, "Process is in quarantined state");
         }
@@ -736,18 +636,8 @@ export class ProcessManager {
         if (proc.inputQueue.length > 0) {
             throw new ProcessError(CONTROL_BUSY, "Cannot release control while operations are pending in queue");
         }
-        if (proc.ttlTimer) {
-            clearTimeout(proc.ttlTimer);
-            proc.ttlTimer = undefined;
-        }
-        proc.currentGrant = undefined;
-        proc.info.control = "free";
-        await this.persistState(id, {
-            control: "free",
-            controlState: "free",
-        });
-        // 正常 release 唤醒下一个等待者
-        this.wakeNextAcquireWaiter(proc);
+        // 仲裁器完成清理定时器、凭据置空与唯一唤醒下一个等待者
+        this.controlArbiter.releaseGrant(proc);
     }
     /**
      * 向受管进程输入流写入原始字节数据。
@@ -780,56 +670,17 @@ export class ProcessManager {
                 this.commitReservation(key, "write", cached);
                 return cached;
             }
-            // 入队前校验授权与控制状态
-            this.checkOperationAuth(proc, input.token);
-            if (proc.inputClosed) {
-                throw new ProcessError(INPUT_CLOSED, "Input stream is closed");
-            }
+            // 输入调度器同步阶段完成授权校验与队列容量预扣，异步阶段落盘入队
             const rawBytes = decodeBytes(input.data);
-            const dataSize = rawBytes.byteLength;
-            // 待写入队列容量检查：在任何 await 前同步原子校验并预占配额
-            if (proc.pendingInputBytes + dataSize > this.quotas.maxPendingQueueBytesPerProcess) {
-                throw new ProcessError(QUEUE_FULL, "Process pending input queue limit exceeded", {
-                    limit: this.quotas.maxPendingQueueBytesPerProcess,
-                });
-            }
-            const totalHostPending = this.countHostPendingInputBytes();
-            if (totalHostPending + dataSize > this.quotas.maxPendingQueueBytesPerHost) {
-                throw new ProcessError(QUEUE_FULL, "Host pending input queue limit exceeded", {
-                    limit: this.quotas.maxPendingQueueBytesPerHost,
-                });
-            }
-            // 同步占位预扣队列配额，杜绝并发 await 窗口穿透
-            proc.pendingInputBytes += dataSize;
-            let pendingBytesCommitted = false;
-            try {
-                const receipt = {
-                    requestId: input.requestId,
-                    state: "queued",
-                };
-                await this.metadataStore.recordRequest(key, receipt, payloadHash);
-                proc.inputQueue.push({
-                    type: "write",
-                    requestId: input.requestId,
-                    token: input.token,
-                    bytes: rawBytes,
-                    receipt,
-                    key,
-                    payloadHash,
-                    cancelEpoch: proc.cancelEpoch,
-                });
-                pendingBytesCommitted = true;
-                // 异步调度推进
-                queueMicrotask(() => void this.dispatchNext(proc));
-                const queued = { ...receipt };
-                this.commitReservation(key, "write", queued);
-                return queued;
-            }
-            finally {
-                if (!pendingBytesCommitted) {
-                    proc.pendingInputBytes = Math.max(0, proc.pendingInputBytes - dataSize);
-                }
-            }
+            const queued = await this.inputDispatcher.enqueueWrite(proc, {
+                requestId: input.requestId,
+                token: input.token,
+                data: rawBytes,
+                key,
+                payloadHash,
+            });
+            this.commitReservation(key, "write", queued);
+            return queued;
         }
         finally {
             // 成功路径已在 commit 中移除预占；此处仅对异常路径释放并唤醒等待方
@@ -867,9 +718,7 @@ export class ProcessManager {
                 this.commitReservation(key, "control", cached);
                 return cached;
             }
-            // 入队前校验授权与控制状态
-            this.checkOperationAuth(proc, input.token);
-            // 校验能力支持
+            // 校验能力支持（能力归属管理器，在调度器入队前完成）
             if (input.action.type === "input-eof" && !proc.info.capabilities.inputEOF) {
                 throw new ProcessError(UNSUPPORTED_CAPABILITY, "Driver does not support input-eof action");
             }
@@ -881,23 +730,14 @@ export class ProcessManager {
                 (!proc.info.capabilities.resize || proc.info.io.mode !== "pty")) {
                 throw new ProcessError(UNSUPPORTED_CAPABILITY, "Driver does not support resize or IO mode is not pty");
             }
-            const receipt = {
-                requestId: input.requestId,
-                state: "queued",
-            };
-            await this.metadataStore.recordRequest(key, receipt, payloadHash);
-            proc.inputQueue.push({
-                type: "control",
+            // 输入调度器完成授权校验、落盘与入队
+            const queued = await this.inputDispatcher.enqueueControl(proc, {
                 requestId: input.requestId,
                 token: input.token,
                 action: input.action,
-                receipt,
                 key,
                 payloadHash,
-                cancelEpoch: proc.cancelEpoch,
             });
-            queueMicrotask(() => void this.dispatchNext(proc));
-            const queued = { ...receipt };
             this.commitReservation(key, "control", queued);
             return queued;
         }
@@ -932,7 +772,7 @@ export class ProcessManager {
         const proc = await this.getOrLoadProcess(owner, id);
         if (proc.outputUnavailable) {
             const requestedPos = parseCursor(input.cursor, proc.info.hostEpoch, id);
-            const tombstone = proc.outputTombstone ?? this.evictedOutputTombstones.get(id);
+            const tombstone = proc.outputTombstone ?? this.terminalOutputCache.getTombstone(id);
             if (tombstone) {
                 const tailPos = parseCursor(tombstone.tailCursor, proc.info.hostEpoch, id);
                 const cmp = compareCursorPos(requestedPos, tailPos);
@@ -1002,11 +842,7 @@ export class ProcessManager {
             return { ...proc.info };
         }
         // 撤销控制权与定时器
-        if (proc.ttlTimer) {
-            clearTimeout(proc.ttlTimer);
-            proc.ttlTimer = undefined;
-        }
-        proc.currentGrant = undefined;
+        this.controlArbiter.disposeProcess(proc);
         if (proc.idleTimer) {
             clearTimeout(proc.idleTimer);
             proc.idleTimer = undefined;
@@ -1019,21 +855,13 @@ export class ProcessManager {
             clearTimeout(proc.drainTimer);
             proc.drainTimer = undefined;
         }
-        // 递增取消纪元：接管输入队列，使挂起中的 dispatch 放弃过期结算
-        proc.cancelEpoch = (proc.cancelEpoch ?? 0) + 1;
-        // 取消待 dispatch 输入
-        for (const op of proc.inputQueue) {
-            op.receipt.state = "failed";
-            op.receipt.errorCode = PROCESS_CANCELLED;
-            await this.persistReceipt(op.key, op.receipt, op.payloadHash);
-        }
-        proc.inputQueue = [];
-        proc.pendingInputBytes = 0;
-        // 拒绝排队等待者
-        while (proc.acquireWaiters.length > 0) {
-            const waiter = proc.acquireWaiters.shift();
-            waiter.reject(new ProcessError(CONTROL_REVOKED, "Process was stopped"));
-        }
+        // 调度器同步原子接管输入队列：纪元递增、标记失败、登记落盘、清空与字节归零
+        this.inputDispatcher.takeoverQueue(proc, PROCESS_CANCELLED);
+        // 终态拒绝全部排队等待者
+        this.controlArbiter.revokeAllWaiters(proc, {
+            code: CONTROL_REVOKED,
+            message: "Process was stopped",
+        });
         proc.info.endReason = proc.info.endReason ?? "requested";
         proc.info.state = "stopping";
         proc.info.control = "closed";
@@ -1078,21 +906,13 @@ export class ProcessManager {
             proc.ttlTimer = undefined;
         }
         proc.currentGrant = undefined;
-        // 递增取消纪元：接管输入队列，使挂起中的 dispatch 放弃过期结算
-        proc.cancelEpoch = (proc.cancelEpoch ?? 0) + 1;
-        // 取消队列中所有待 dispatch 操作
-        for (const op of proc.inputQueue) {
-            op.receipt.state = "failed";
-            op.receipt.errorCode = CONTROL_REVOKED;
-            await this.persistReceipt(op.key, op.receipt, op.payloadHash);
-        }
-        proc.inputQueue = [];
-        proc.pendingInputBytes = 0;
-        // 拒绝排队等待者
-        while (proc.acquireWaiters.length > 0) {
-            const waiter = proc.acquireWaiters.shift();
-            waiter.reject(new ProcessError(PROCESS_QUARANTINED, reason || "Process entered quarantined state"));
-        }
+        // 调度器同步原子接管输入队列：纪元递增、标记失败、登记落盘、清空与字节归零
+        this.inputDispatcher.takeoverQueue(proc, CONTROL_REVOKED);
+        // 终态拒绝全部排队等待者
+        this.controlArbiter.revokeAllWaiters(proc, {
+            code: PROCESS_QUARANTINED,
+            message: reason || "Process entered quarantined state",
+        });
         await this.persistState(processId, {
             control: "quarantined",
             controlState: "quarantined",
@@ -1100,340 +920,13 @@ export class ProcessManager {
     }
     /**
      * 一次性运行外部命令，收集有限输出并支持协作式取消与超时回收。
+     * 实现委托给独立持有的一次性 run 执行器，不触碰受管进程注册表。
      */
     async run(owner, input, call) {
         checkOwnerAuthorized(owner, owner);
         await this.ensureInitialized();
         this.assertNotShutdown();
-        const ioMode = input.spec.io?.mode ?? "pipe";
-        if (ioMode !== "pipe") {
-            throw new ProcessError(UNSUPPORTED_CAPABILITY, "Run requires IO mode to be 'pipe'");
-        }
-        const effectiveSpec = {
-            ...input.spec,
-            io: {
-                ...input.spec.io,
-                mode: "pipe",
-            },
-        };
-        const runProcessId = `run-${randomUUID()}`;
-        const chunks = [];
-        let totalBytes = 0;
-        let truncated = false;
-        let timedOut = false;
-        let cancelled = false;
-        let resolveExit;
-        let rejectError;
-        const exitPromise = new Promise((resolve, reject) => {
-            resolveExit = resolve;
-            rejectError = reject;
-        });
-        let driverHandle;
-        const callbacks = {
-            onOutput: (stream, data) => {
-                if (truncated)
-                    return;
-                if (stream !== "stdout" && stream !== "stderr")
-                    return;
-                const remaining = input.maxOutputBytes - totalBytes;
-                if (remaining <= 0) {
-                    truncated = true;
-                    if (driverHandle) {
-                        void driverHandle.terminate(1000);
-                    }
-                    return;
-                }
-                if (data.byteLength > remaining) {
-                    const slice = data.subarray(0, remaining);
-                    chunks.push({
-                        stream,
-                        data: encodeBytes(slice),
-                    });
-                    totalBytes += slice.byteLength;
-                    truncated = true;
-                    if (driverHandle) {
-                        void driverHandle.terminate(1000);
-                    }
-                }
-                else {
-                    chunks.push({
-                        stream,
-                        data: encodeBytes(data),
-                    });
-                    totalBytes += data.byteLength;
-                }
-            },
-            onExit: (exit) => {
-                resolveExit(exit);
-            },
-            onError: (err) => {
-                rejectError(err);
-            },
-        };
-        // 对齐 start 防御顺序：派生前检查取消信号，已中止直接抛出取消错误不再派生进程
-        if (call?.signal?.aborted) {
-            throw call.signal.reason instanceof ProcessError
-                ? call.signal.reason
-                : new ProcessError(PROCESS_CANCELLED, "Process run was cancelled");
-        }
-        driverHandle = await this.driver.spawn(runProcessId, effectiveSpec, callbacks);
-        let timeoutTimer;
-        if (input.timeoutMs > 0) {
-            timeoutTimer = setTimeout(() => {
-                timedOut = true;
-                if (driverHandle) {
-                    void driverHandle.terminate(1000);
-                }
-            }, input.timeoutMs);
-            if (typeof timeoutTimer?.unref === "function") {
-                timeoutTimer.unref();
-            }
-        }
-        let onAbort;
-        if (call?.signal) {
-            if (call.signal.aborted) {
-                if (timeoutTimer)
-                    clearTimeout(timeoutTimer);
-                if (driverHandle)
-                    void driverHandle.terminate(1000);
-                throw call.signal.reason ?? new ProcessError(PROCESS_CANCELLED, "Process run was cancelled");
-            }
-            onAbort = () => {
-                cancelled = true;
-                if (timeoutTimer)
-                    clearTimeout(timeoutTimer);
-                if (driverHandle)
-                    void driverHandle.terminate(1000);
-            };
-            call.signal.addEventListener("abort", onAbort, { once: true });
-        }
-        try {
-            const exit = await exitPromise;
-            if (timeoutTimer)
-                clearTimeout(timeoutTimer);
-            if (call?.signal && onAbort) {
-                call.signal.removeEventListener("abort", onAbort);
-            }
-            if (timedOut) {
-                throw new ProcessError(PROCESS_TIMEOUT, `Process exceeded timeout of ${input.timeoutMs}ms`);
-            }
-            if (cancelled || call?.signal?.aborted) {
-                throw call?.signal?.reason ?? new ProcessError(PROCESS_CANCELLED, "Process run was cancelled");
-            }
-            return {
-                exit,
-                chunks,
-                truncated,
-            };
-        }
-        catch (err) {
-            if (timeoutTimer)
-                clearTimeout(timeoutTimer);
-            if (call?.signal && onAbort) {
-                call.signal.removeEventListener("abort", onAbort);
-            }
-            if (timedOut) {
-                throw new ProcessError(PROCESS_TIMEOUT, `Process exceeded timeout of ${input.timeoutMs}ms`);
-            }
-            if (cancelled || call?.signal?.aborted) {
-                throw call?.signal?.reason ?? new ProcessError(PROCESS_CANCELLED, "Process run was cancelled");
-            }
-            throw err;
-        }
-    }
-    /**
-     * 授予指定受管进程控制令牌。
-     */
-    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.persistState(proc.info.id, {
-            control: "held",
-            controlState: "held",
-        });
-        return {
-            token,
-            expiresAt,
-        };
-    }
-    /**
-     * 控制权到期未释放时自动转为隔离状态。
-     */
-    handleGrantTtlExpired(proc) {
-        if (proc.info.control !== "held" || !proc.currentGrant) {
-            return;
-        }
-        void this.quarantineProcess(proc.owner, proc.info.id, proc.currentGrant.token, "Control token TTL expired");
-    }
-    /**
-     * 唤醒排队等待控制权的下一个调用者。
-     */
-    wakeNextAcquireWaiter(proc) {
-        if (proc.acquireWaiters.length === 0) {
-            return;
-        }
-        const next = proc.acquireWaiters.shift();
-        const grant = this.grantControl(proc, next.requestId, next.ttlMs, next.runId);
-        const key = {
-            hostEpoch: this.hostEpoch,
-            scope: proc.scope,
-            processId: proc.info.id,
-            requestId: next.requestId,
-        };
-        const payloadHash = hashRequestPayload({ waitMs: next.waitMs, ttlMs: next.ttlMs });
-        void this.persistReceipt(key, grant, payloadHash);
-        next.resolve(grant);
-    }
-    /**
-     * 串行调度执行输入队列操作。
-     */
-    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.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.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.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.persistReceipt(op.key, op.receipt, op.payloadHash);
-                        proc.inputQueue.shift();
-                        proc.pendingInputBytes -= op.bytes.byteLength;
-                        await this.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);
-                            }
-                        }
-                        // 控制指令返回后校验取消纪元与队首位置：已被接管则放弃过期结算
-                        if (op.cancelEpoch !== proc.cancelEpoch || proc.inputQueue[0] !== op) {
-                            continue;
-                        }
-                        if (op.action.type === "input-eof") {
-                            proc.inputClosed = true;
-                            await this.persistState(proc.info.id, { inputClosed: true });
-                        }
-                        op.receipt.state = "completed";
-                        this.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.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.persistReceipt(op.key, op.receipt, op.payloadHash);
-                proc.inputQueue.shift();
-                if (op.bytes) {
-                    proc.pendingInputBytes -= op.bytes.byteLength;
-                }
-            }
-        }
-        finally {
-            proc.isDispatching = false;
-        }
-    }
-    /**
-     * 操作提交前校验持有者令牌与授权。
-     */
-    checkOperationAuth(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");
-        }
+        return this.runExecutor.execute(input, call);
     }
     /**
      * 启动空闲超时定时器。
@@ -1533,11 +1026,11 @@ export class ProcessManager {
             proc.info.endReason = "natural";
         }
         proc.currentGrant = undefined;
-        // 拒绝排队等待者
-        while (proc.acquireWaiters.length > 0) {
-            const waiter = proc.acquireWaiters.shift();
-            waiter.reject(new ProcessError(CONTROL_REVOKED, "Process has exited"));
-        }
+        // 终态拒绝全部排队等待者（单一入口）
+        this.controlArbiter.revokeAllWaiters(proc, {
+            code: CONTROL_REVOKED,
+            message: "Process has exited",
+        });
         void this.persistState(proc.info.id, {
             state: "exited",
             control: "closed",
@@ -1602,10 +1095,11 @@ export class ProcessManager {
         proc.info.endReason = "natural";
         proc.outputLog.closeOutput("natural");
         proc.info.outputClosed = true;
-        while (proc.acquireWaiters.length > 0) {
-            const waiter = proc.acquireWaiters.shift();
-            waiter.reject(new ProcessError(CONTROL_REVOKED, `Process error: ${err.message}`));
-        }
+        // 终态拒绝全部排队等待者（单一入口）
+        this.controlArbiter.revokeAllWaiters(proc, {
+            code: CONTROL_REVOKED,
+            message: `Process error: ${err.message}`,
+        });
         void this.persistState(proc.info.id, {
             state: "failed",
             control: "closed",
@@ -1646,8 +1140,8 @@ export class ProcessManager {
             throw new ProcessError(PROCESS_LOST, `Process '${processId}' belonged to a previous host epoch '${record.hostEpoch}' and has been marked lost; current epoch is '${this.hostEpoch}'`, { processId, hostEpoch: record.hostEpoch, currentHostEpoch: this.hostEpoch });
         }
         const info = toSdkProcessInfo(record);
-        const retainedLog = this.getRetainedOutputLog(processId);
-        const tombstone = this.evictedOutputTombstones.get(processId);
+        const retainedLog = this.terminalOutputCache.get(processId);
+        const tombstone = this.terminalOutputCache.getTombstone(processId);
         const isTerminalLoaded = info.state === "exited" || info.state === "failed" || info.state === "lost";
         const isOutputUnavailable = !retainedLog && (Boolean(tombstone) || (isTerminalLoaded && Boolean(record.outputClosed)));
         const outputLog = retainedLog ??
@@ -1686,84 +1180,11 @@ export class ProcessManager {
         this.processes.set(processId, loaded);
         return loaded;
     }
-    /**
-     * 记录已淘汰输出日志的墓碑信息（保留最近 2048 条，防止内存无限积压）。
-     */
-    recordTombstone(processId, tombstone) {
-        if (this.evictedOutputTombstones.size >= 2048) {
-            const oldestKey = this.evictedOutputTombstones.keys().next().value;
-            if (oldestKey) {
-                this.evictedOutputTombstones.delete(oldestKey);
-            }
-        }
-        this.evictedOutputTombstones.set(processId, tombstone);
-    }
-    /**
-     * 清理已过期的终态输出日志条目。
-     */
-    cleanExpiredTerminalLogs() {
-        const now = Date.now();
-        for (const [id, entry] of this.evictedOutputLogs.entries()) {
-            if (now - entry.evictedAt > this.terminalLogRetentionMs) {
-                this.recordTombstone(id, {
-                    tailCursor: entry.log.tailCursor,
-                    earliestCursor: entry.log.earliestCursor,
-                    evictedAt: now,
-                });
-                this.evictedOutputLogs.delete(id);
-            }
-        }
-    }
     /**
      * 统计终态保留日志当前在内存中实际占用的输出缓冲字节总数。
      */
     countRetainedOutputBufferBytes() {
-        this.cleanExpiredTerminalLogs();
-        let bytes = 0;
-        for (const entry of this.evictedOutputLogs.values()) {
-            bytes += entry.log.currentBytes;
-        }
-        return bytes;
-    }
-    /**
-     * 将终态输出日志存入保留缓存，并根据宿主配额执行 LRU 与 TTL 淘汰。
-     */
-    retainTerminalOutputLog(processId, log) {
-        this.cleanExpiredTerminalLogs();
-        // 若新加入条目会导致总输出配额超限或数量超限，按 LRU 顺序淘汰最旧条目
-        while ((this.countRetainedOutputBufferBytes() + log.currentBytes > this.quotas.maxOutputBufferBytesPerHost ||
-            this.evictedOutputLogs.size >= 512) &&
-            this.evictedOutputLogs.size > 0) {
-            const oldestKey = this.evictedOutputLogs.keys().next().value;
-            if (!oldestKey)
-                break;
-            const oldestEntry = this.evictedOutputLogs.get(oldestKey);
-            if (oldestEntry) {
-                this.recordTombstone(oldestKey, {
-                    tailCursor: oldestEntry.log.tailCursor,
-                    earliestCursor: oldestEntry.log.earliestCursor,
-                    evictedAt: Date.now(),
-                });
-            }
-            this.evictedOutputLogs.delete(oldestKey);
-        }
-        this.evictedOutputLogs.set(processId, {
-            log,
-            evictedAt: Date.now(),
-        });
-    }
-    /**
-     * 获取终态保留日志（附带过期清理与 LRU 触达更新）。
-     */
-    getRetainedOutputLog(processId) {
-        this.cleanExpiredTerminalLogs();
-        const entry = this.evictedOutputLogs.get(processId);
-        if (!entry)
-            return undefined;
-        // 触达刷新 LRU 顺序
-        this.evictedOutputLogs.delete(processId);
-        this.evictedOutputLogs.set(processId, entry);
-        return entry.log;
+        return this.terminalOutputCache.retainedBytes();
     }
     /**
      * 终态驱逐与驱动释放：进程到达终态且输出已关闭后移除内存记录，
@@ -1780,7 +1201,7 @@ export class ProcessManager {
         }
         this.processes.delete(proc.info.id);
         // 保留输出日志支撑后续游标读取（内存输出无法从持久层恢复）
-        this.retainTerminalOutputLog(proc.info.id, proc.outputLog);
+        this.terminalOutputCache.retain(proc.info.id, proc.outputLog);
         if (proc.handle && typeof this.driver.dispose === "function") {
             try {
                 const disposed = this.driver.dispose(proc.handle);
@@ -1832,23 +1253,14 @@ export class ProcessManager {
             });
         }
         // 终态保留输出日志实际占用字节数纳入宿主预算
-        totalBuffer += this.countRetainedOutputBufferBytes();
+        const retainedBefore = this.countRetainedOutputBufferBytes();
+        totalBuffer += retainedBefore;
         // 若新进程申请的缓冲使总预算超限，优先淘汰已有的终态保留日志（LRU 策略）
-        while (totalBuffer + perProcBuf > this.quotas.maxOutputBufferBytesPerHost &&
-            this.evictedOutputLogs.size > 0) {
-            const oldestKey = this.evictedOutputLogs.keys().next().value;
-            if (!oldestKey)
-                break;
-            const oldest = this.evictedOutputLogs.get(oldestKey);
-            if (oldest) {
-                this.recordTombstone(oldestKey, {
-                    tailCursor: oldest.log.tailCursor,
-                    earliestCursor: oldest.log.earliestCursor,
-                    evictedAt: Date.now(),
-                });
-                totalBuffer -= oldest.log.currentBytes;
-            }
-            this.evictedOutputLogs.delete(oldestKey);
+        // 淘汰门槛为宿主预算扣除活跃进程已占字节与新申请字节，淘汰释放的字节数同步回扣宿主预算
+        if (totalBuffer + perProcBuf > this.quotas.maxOutputBufferBytesPerHost) {
+            const activeBufferBytes = totalBuffer - retainedBefore;
+            const evictedBytes = this.terminalOutputCache.evictLRUUntil(this.quotas.maxOutputBufferBytesPerHost - perProcBuf - activeBufferBytes);
+            totalBuffer -= evictedBytes;
         }
         if (totalBuffer + perProcBuf > this.quotas.maxOutputBufferBytesPerHost) {
             throw new ProcessError(QUOTA_EXCEEDED, "Host output buffer quota exceeded", {