@xioflow/kernel 0.1.4 → 0.2.0

package/dist/supervisor/supervisor.js

@@ -1,7 +1,68 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
-import { UnsupportedCapabilityError, } from '../types.js';
+import { UnsupportedCapabilityError, OperationNotActiveError, DuplicateOperationError, } from '../types.js';
+/**
+ * 规范化计算完整输入的 SHA-256 指纹 (ARCHITECTURE §2 / P0-12)
+ * 覆盖 execPath, args, cwd, 键排序的 envWhiteList, inheritEnv, sha256(stdin), 排序后的 requiredResources, timeoutMs, resourceBudget.
+ */
+export function computeInputFingerprint(options) {
+    const cmd = options.command;
+    let stdinHash = null;
+    if (cmd.stdin !== undefined && cmd.stdin !== null) {
+        stdinHash = crypto.createHash('sha256').update(cmd.stdin).digest('hex');
+    }
+    let envSorted = null;
+    if (cmd.envWhiteList) {
+        const keys = Object.keys(cmd.envWhiteList).sort();
+        envSorted = keys.map((k) => [k, cmd.envWhiteList[k]]);
+    }
+    const canonical = {
+        args: cmd.args || [],
+        cwd: cmd.cwd || '',
+        envWhiteList: envSorted,
+        execPath: cmd.execPath || '',
+        inheritEnv: cmd.inheritEnv ?? null,
+        requiredResources: [...(options.requiredResources || [])].sort(),
+        resourceBudget: options.resourceBudget
+            ? {
+                enforcement: options.resourceBudget.enforcement ?? null,
+                maxCpuTimeMs: options.resourceBudget.maxCpuTimeMs ?? null,
+                maxMemoryBytes: options.resourceBudget.maxMemoryBytes ?? null,
+                maxOutputBytes: options.resourceBudget.maxOutputBytes ?? null,
+                maxPids: options.resourceBudget.maxPids ?? null,
+            }
+            : null,
+        stdinHash,
+        timeoutMs: options.timeoutMs ?? null,
+    };
+    const canonicalJson = JSON.stringify(canonical);
+    return crypto.createHash('sha256').update(canonicalJson).digest('hex');
+}
+function trimToValidUtf8(buf) {
+    const len = buf.length;
+    for (let i = 1; i <= Math.min(3, len); i++) {
+        const b = buf[len - i];
+        if ((b & 0xc0) === 0xc0) {
+            const needed = (b & 0xe0) === 0xc0 ? 2 : (b & 0xf0) === 0xe0 ? 3 : (b & 0xf8) === 0xf0 ? 4 : 1;
+            if (i < needed) {
+                return Buffer.from(buf.subarray(0, len - i));
+            }
+            break;
+        }
+        else if ((b & 0x80) === 0) {
+            break;
+        }
+    }
+    return buf;
+}
+function trimStartToValidUtf8(buf) {
+    let start = 0;
+    while (start < buf.length && (buf[start] & 0xc0) === 0x80) {
+        start++;
+    }
+    return Buffer.from(buf.subarray(start));
+}
 export class ProcessSupervisor {
     domain;
     driver;
@@ -9,6 +70,7 @@ export class ProcessSupervisor {
     constructor(domain, driver) {
         this.domain = domain;
         this.driver = driver;
+        this.domain.setDriver?.(driver);
     }
     getDomain() {
         return this.domain;
@@ -23,6 +85,8 @@ export class ProcessSupervisor {
         const startTime = Date.now();
         const maxBytes = options.maxOutputBytes ?? 10 * 1024 * 1024; // 默认 10MB
         const drainTimeoutMs = options.drainTimeoutMs ?? 2000; // 默认 2000ms
+        let stdoutDrainer;
+        let stderrDrainer;
         // 0. [准入期强校验 Pre-admission Capability Check]
         if (options.resourceBudget?.enforcement === 'hard') {
             if (options.resourceBudget.maxMemoryBytes && !this.driver.capabilities.memoryHardLimit) {
@@ -35,156 +99,306 @@ export class ProcessSupervisor {
                 throw new UnsupportedCapabilityError('cpuLimit', this.driver.name, 'hard');
             }
         }
+        // N8 守卫（契约 #40）：显式拒绝已存在或在飞的 opId，在触碰任何内存状态或 DB 租约之前同步拦截
+        if (this.activeOperations.has(options.opId)) {
+            const existing = this.activeOperations.get(options.opId);
+            throw new DuplicateOperationError(options.opId, existing.phase, existing.runId);
+        }
+        const existingRecorded = this.domain.getStore().getOperation(options.opId);
+        if (existingRecorded) {
+            throw new DuplicateOperationError(options.opId, existingRecorded.status, existingRecorded.runId);
+        }
         const op = {
             id: options.opId,
             runId: options.runId,
             kind: 'process',
             name: options.name,
-            inputFingerprint: options.inputFingerprint || `${options.command.execPath}:${options.command.args.join(' ')}`,
+            inputFingerprint: options.inputFingerprint || computeInputFingerprint(options),
             requiredResources: options.requiredResources,
             timeoutMs: options.timeoutMs,
             resourceBudget: options.resourceBudget,
             status: 'pending',
         };
-        // 1. [资源分配与排队等待]
-        await this.domain.allocateResourcesWithWait(options.opId, options.requiredResources, options.waitTimeoutMs ?? 0, options.resourceBudget);
-        // 2. [启动协议步骤 1] 写入 SQLite (status: intent_registered)
-        try {
-            this.domain.getStore().registerOperationIntent(op, this.domain.domainId);
-        }
-        catch (err) {
-            this.domain.releaseResources(options.opId, options.requiredResources);
-            throw err;
-        }
-        let handle;
-        try {
-            // 3. [启动协议步骤 2] 请求平台驱动启动
-            handle = await this.driver.spawn(options.command);
-        }
-        catch (spawnError) {
-            // 启动失败（如可执行文件不存在），不产生假运行状态，直接失败收尾并释放资源
-            const failResult = {
-                kind: 'process',
-                status: 'failed',
-                exitCode: 127,
-                signal: null,
-                stdout: '',
-                stderr: spawnError?.message || String(spawnError),
-                spawnFailure: spawnError?.message || String(spawnError),
-                isTruncated: false,
-                identityVerification: 'not_original_process',
-                durationMs: Date.now() - startTime,
-                completedAt: new Date().toISOString(),
-            };
-            this.domain.getStore().recordOperationResult(options.opId, failResult, true);
-            this.domain.releaseResources(options.opId, options.requiredResources);
-            return failResult;
-        }
-        // 4. [启动协议步骤 3] 登记执行身份，状态推进为 active
-        this.domain.getStore().updateOperationStatus(options.opId, 'active', handle.identity);
         const opState = {
-            handle,
-            command: options.command,
+            opId: options.opId,
+            runId: options.runId,
+            phase: 'waiting_resources',
+            startTime,
             cancelRequested: false,
             timedOut: false,
-            terminationReason: undefined,
-            stopPromise: undefined,
         };
         this.activeOperations.set(options.opId, opState);
-        // 准备 artifacts 溢出转储目录
-        const artifactsDir = options.artifactsDir || path.join(this.domain.domainPath, 'artifacts');
-        if (!fs.existsSync(artifactsDir)) {
+        let timeoutTimer = null;
+        let samplingInterval = null;
+        try {
+            // 1. [资源分配与排队等待]
+            await this.domain.allocateResourcesWithWait(options.opId, options.requiredResources || [], options.waitTimeoutMs ?? 0, options.resourceBudget, () => opState.cancelRequested === true);
+            if (opState.cancelRequested) {
+                return this.handlePreSpawnCancellation(options, opState, startTime);
+            }
+            // 2. [启动协议步骤 1] 写入 SQLite (status: intent_registered)
             try {
-                fs.mkdirSync(artifactsDir, { recursive: true });
+                this.domain.getStore().registerOperationIntent(op, this.domain.domainId);
+                opState.phase = 'intent_registered';
             }
-            catch { }
-        }
-        const stdoutSpillPath = path.join(artifactsDir, `${options.opId}-stdout.log`);
-        const stderrSpillPath = path.join(artifactsDir, `${options.opId}-stderr.log`);
-        // 5. [正常监督、有界排空与流式转储 (Spill to Artifacts)]
-        let totalOutputBytes = 0;
-        const onChunk = (bytes) => {
-            totalOutputBytes += bytes;
-            if (options.resourceBudget?.enforcement === 'soft' &&
-                options.resourceBudget.maxOutputBytes &&
-                totalOutputBytes > options.resourceBudget.maxOutputBytes &&
-                !opState.terminationReason) {
-                opState.terminationReason = 'output_exceeded';
-                this.handleStopPipeline(options.opId, 'output_exceeded', 1000).catch(() => { });
+            catch (err) {
+                this.domain.internalReleaseResources(options.opId, options.requiredResources);
+                throw err;
             }
-        };
-        let streamCallbackError;
-        const forwardChunk = (stream) => (chunk) => {
-            if (!options.onStreamChunk)
-                return;
+            if (opState.cancelRequested) {
+                return this.handlePreSpawnCancellation(options, opState, startTime);
+            }
+            let handle;
+            opState.phase = 'spawning';
             try {
-                options.onStreamChunk(stream, chunk);
+                // 3. [启动协议步骤 2] 请求平台驱动启动
+                handle = await this.driver.spawn(options.command);
+                opState.handle = handle;
+                opState.command = options.command;
             }
-            catch (err) {
-                streamCallbackError ??= err instanceof Error ? err.message : String(err);
+            catch (spawnError) {
+                opState.phase = 'done';
+                opState.stopResolve?.({ stopped: 'confirmed_stopped', scope: 'direct_child', errorDetails: spawnError?.message });
+                opState.stopResolve = undefined;
+                // 启动失败（如可执行文件不存在），不产生假运行状态，直接失败收尾并释放资源
+                const failResult = {
+                    kind: 'process',
+                    status: 'failed',
+                    exitCode: 127,
+                    signal: null,
+                    stdout: '',
+                    stderr: spawnError?.message || String(spawnError),
+                    spawnFailure: spawnError?.message || String(spawnError),
+                    isTruncated: false,
+                    identityVerification: 'not_original_process',
+                    durationMs: Date.now() - startTime,
+                    completedAt: new Date().toISOString(),
+                };
+                return this.finalizeOperation(options.opId, failResult, options.requiredResources, true);
             }
-        };
-        const stdoutDrainer = this.setupStreamDrainer(handle.stdout, maxBytes, stdoutSpillPath, onChunk, forwardChunk('stdout'));
-        const stderrDrainer = this.setupStreamDrainer(handle.stderr, maxBytes, stderrSpillPath, onChunk, forwardChunk('stderr'));
-        let timeoutTimer = null;
-        const timeoutPromise = options.timeoutMs && options.timeoutMs > 0
-            ? new Promise((resolve) => {
-                timeoutTimer = setTimeout(() => resolve('timeout'), options.timeoutMs);
-            })
-            : new Promise(() => { });
-        // Soft / Observe 模式资源采样治理
-        let peakMemoryBytes = 0;
-        let peakCpuTimeMs = 0;
-        let samplingInterval = null;
-        if (this.driver.sampleMetrics &&
-            options.resourceBudget &&
-            (options.resourceBudget.enforcement === 'soft' || options.resourceBudget.enforcement === 'observe')) {
-            samplingInterval = setInterval(async () => {
+            // 4. [启动协议步骤 3] 登记执行身份，状态推进为 active
+            try {
+                this.domain.getStore().updateOperationStatus(options.opId, 'active', handle.identity);
+                opState.phase = 'active';
+                handle.releaseGate?.();
+            }
+            catch (statusError) {
+                handle.destroyGate?.();
+                // N4: spawn 成功但登记 active 失败，防止产生孤儿进程
+                opState.phase = 'stopping';
+                const stopRes = await this.driver.terminate(handle.identity, 2000);
+                // 有界等待退出与关闭流，防止管道悬挂
+                await Promise.race([
+                    (handle.onRootExit ?? handle.onExit).catch(() => { }),
+                    new Promise((resolve) => setTimeout(resolve, 500)),
+                ]);
                 try {
-                    const metrics = await this.driver.sampleMetrics(handle.identity);
-                    peakMemoryBytes = Math.max(peakMemoryBytes, metrics.rssBytes);
-                    peakCpuTimeMs = Math.max(peakCpuTimeMs, metrics.cpuTimeMs);
-                    if (options.resourceBudget?.enforcement === 'soft') {
-                        if (options.resourceBudget.maxMemoryBytes && metrics.rssBytes > options.resourceBudget.maxMemoryBytes) {
-                            opState.terminationReason = 'memory_exceeded';
-                            if (samplingInterval)
-                                clearInterval(samplingInterval);
-                            await this.handleStopPipeline(options.opId, 'memory_exceeded', 1000);
-                        }
-                        else if (options.resourceBudget.maxCpuTimeMs && metrics.cpuTimeMs > options.resourceBudget.maxCpuTimeMs) {
-                            opState.terminationReason = 'cpu_exceeded';
-                            if (samplingInterval)
-                                clearInterval(samplingInterval);
-                            await this.handleStopPipeline(options.opId, 'cpu_exceeded', 1000);
-                        }
-                        else if (options.resourceBudget.maxPids && metrics.pidsCount > options.resourceBudget.maxPids) {
-                            opState.terminationReason = 'pids_exceeded';
-                            if (samplingInterval)
-                                clearInterval(samplingInterval);
-                            await this.handleStopPipeline(options.opId, 'pids_exceeded', 1000);
-                        }
-                    }
+                    handle.stdout.destroy?.();
+                    handle.stderr.destroy?.();
                 }
                 catch { }
-            }, 100);
-        }
-        try {
-            // 等待根进程退出或超时触发；有 onRootExit 时不等待持有管道的后代
+                opState.phase = 'done';
+                if (opState.stopResolve) {
+                    const resolveFn = opState.stopResolve;
+                    opState.stopResolve = undefined;
+                    resolveFn(stopRes);
+                }
+                if (stopRes.stopped === 'confirmed_stopped') {
+                    const failResult = {
+                        kind: 'process',
+                        status: 'failed',
+                        exitCode: null,
+                        signal: null,
+                        stdout: '',
+                        stderr: `Failed to register active status: ${statusError?.message || String(statusError)}`,
+                        spawnFailure: statusError?.message || String(statusError),
+                        isTruncated: false,
+                        identityVerification: 'not_original_process',
+                        durationMs: Date.now() - startTime,
+                        completedAt: new Date().toISOString(),
+                    };
+                    this.finalizeOperation(options.opId, failResult, options.requiredResources, true);
+                }
+                else {
+                    const indetResult = {
+                        kind: 'indeterminate',
+                        status: 'indeterminate',
+                        reason: `Failed to register active status: ${statusError?.message || String(statusError)}, and process ${handle.identity.pid} could not be confirmed stopped: ${stopRes.errorDetails || 'residual processes still alive'}`,
+                        recoveryGuidance: 'Residual PID detected. Inspect system processes manually before releasing resources.',
+                        durationMs: Date.now() - startTime,
+                        completedAt: new Date().toISOString(),
+                    };
+                    this.finalizeOperation(options.opId, indetResult, options.requiredResources, false);
+                }
+                throw statusError;
+            }
+            // 准备 artifacts 溢出转储目录
+            const artifactsDir = options.artifactsDir || path.join(this.domain.domainPath, 'artifacts');
+            let artifactsDirError = undefined;
+            if (!fs.existsSync(artifactsDir)) {
+                try {
+                    fs.mkdirSync(artifactsDir, { recursive: true });
+                }
+                catch (dirErr) {
+                    artifactsDirError = dirErr.message || String(dirErr);
+                }
+            }
+            const stdoutSpillPath = path.join(artifactsDir, `${options.opId}-stdout.log`);
+            const stderrSpillPath = path.join(artifactsDir, `${options.opId}-stderr.log`);
+            // 5. [正常监督、有界排空与流式转储 (Spill to Artifacts)]
+            let totalOutputBytes = 0;
+            const onChunk = (bytes) => {
+                totalOutputBytes += bytes;
+                if (options.resourceBudget?.enforcement === 'soft' &&
+                    options.resourceBudget.maxOutputBytes &&
+                    totalOutputBytes > options.resourceBudget.maxOutputBytes &&
+                    !opState.terminationReason) {
+                    opState.terminationReason = 'output_exceeded';
+                    this.handleStopPipeline(options.opId, 'output_exceeded', 1000).catch(() => { });
+                }
+            };
+            let streamCallbackError;
+            const forwardChunk = (stream) => (chunk) => {
+                if (!options.onStreamChunk)
+                    return;
+                try {
+                    options.onStreamChunk(stream, chunk);
+                }
+                catch (err) {
+                    streamCallbackError ??= err instanceof Error ? err.message : String(err);
+                }
+            };
+            stdoutDrainer = this.setupStreamDrainer(handle.stdout, maxBytes, stdoutSpillPath, onChunk, forwardChunk('stdout'), artifactsDirError);
+            stderrDrainer = this.setupStreamDrainer(handle.stderr, maxBytes, stderrSpillPath, onChunk, forwardChunk('stderr'), artifactsDirError);
+            // 检查在 spawn 途中是否已被请求取消：若已请求取消，立即触发停止流水线向底层发送终止信号
+            if (opState.cancelRequested) {
+                this.handleStopPipeline(options.opId, 'user_cancelled', opState.cancelGraceMs ?? 2000).catch(() => { });
+            }
+            const timeoutPromise = options.timeoutMs && options.timeoutMs > 0
+                ? new Promise((resolve) => {
+                    timeoutTimer = setTimeout(() => resolve('timeout'), options.timeoutMs);
+                })
+                : new Promise(() => { });
+            // Soft / Observe 模式资源采样治理
+            let peakMemoryBytes = 0;
+            let peakCpuTimeMs = 0;
+            if (this.driver.sampleMetrics &&
+                options.resourceBudget &&
+                (options.resourceBudget.enforcement === 'soft' || options.resourceBudget.enforcement === 'observe')) {
+                samplingInterval = setInterval(async () => {
+                    try {
+                        const metrics = await this.driver.sampleMetrics(handle.identity);
+                        peakMemoryBytes = Math.max(peakMemoryBytes, metrics.rssBytes);
+                        peakCpuTimeMs = Math.max(peakCpuTimeMs, metrics.cpuTimeMs);
+                        if (options.resourceBudget?.enforcement === 'soft') {
+                            if (options.resourceBudget.maxMemoryBytes && metrics.rssBytes > options.resourceBudget.maxMemoryBytes) {
+                                opState.terminationReason = 'memory_exceeded';
+                                if (samplingInterval)
+                                    clearInterval(samplingInterval);
+                                await this.handleStopPipeline(options.opId, 'memory_exceeded', 1000);
+                            }
+                            else if (options.resourceBudget.maxCpuTimeMs && metrics.cpuTimeMs > options.resourceBudget.maxCpuTimeMs) {
+                                opState.terminationReason = 'cpu_exceeded';
+                                if (samplingInterval)
+                                    clearInterval(samplingInterval);
+                                await this.handleStopPipeline(options.opId, 'cpu_exceeded', 1000);
+                            }
+                            else if (options.resourceBudget.maxPids && metrics.pidsCount > options.resourceBudget.maxPids) {
+                                opState.terminationReason = 'pids_exceeded';
+                                if (samplingInterval)
+                                    clearInterval(samplingInterval);
+                                await this.handleStopPipeline(options.opId, 'pids_exceeded', 1000);
+                            }
+                        }
+                    }
+                    catch { }
+                }, 100);
+            }
+            let notifyStop;
+            const stopTriggerPromise = new Promise((resolve) => {
+                notifyStop = resolve;
+            });
+            const previousResolve = opState.stopResolve;
+            opState.stopResolve = (res) => {
+                previousResolve?.(res);
+                notifyStop?.(res);
+            };
+            // 等待根进程退出、超时触发、或外部停止完成
             const rootExitPromise = handle.onRootExit ?? handle.onExit;
+            const stopCandidate = opState.stopPromise ? opState.stopPromise : stopTriggerPromise;
             const exitOrTimeout = await Promise.race([
-                rootExitPromise.then((res) => ({ type: 'exit', res })),
-                timeoutPromise.then((type) => ({ type, res: null })),
+                rootExitPromise.then((res) => ({ type: 'exit', res, stopRes: null })),
+                timeoutPromise.then((type) => ({ type, res: null, stopRes: null })),
+                stopCandidate.then((stopRes) => ({ type: 'stop', res: null, stopRes })),
             ]);
             if (timeoutTimer)
                 clearTimeout(timeoutTimer);
             if (samplingInterval)
                 clearInterval(samplingInterval);
             let exitResult;
-            if (exitOrTimeout.type === 'timeout') {
+            if (exitOrTimeout.type === 'stop') {
+                const stopRes = exitOrTimeout.stopRes;
+                if (stopRes.stopped !== 'confirmed_stopped') {
+                    if (handle.rawProcess && typeof handle.rawProcess.kill === 'function') {
+                        try {
+                            handle.rawProcess.kill('SIGKILL');
+                        }
+                        catch { }
+                    }
+                    try {
+                        handle.stdout.destroy?.();
+                        handle.stderr.destroy?.();
+                    }
+                    catch { }
+                    const stored = this.domain.getStore().getOperation(options.opId);
+                    if (stored && stored.status === 'done') {
+                        return (stored.result ?? null);
+                    }
+                    const indetResult = {
+                        kind: 'indeterminate',
+                        status: 'indeterminate',
+                        reason: `Process ${handle.identity.pid} was cancelled or stopped but could not be confirmed: ${stopRes.errorDetails || 'residual processes still alive'}`,
+                        recoveryGuidance: 'Residual PID detected. Inspect system processes manually before releasing resources.',
+                        durationMs: Date.now() - startTime,
+                        completedAt: new Date().toISOString(),
+                    };
+                    return this.finalizeOperation(options.opId, indetResult, options.requiredResources, false);
+                }
+                const rootExitWaitMs = 1000;
+                const rootExitOrTimeout = await Promise.race([
+                    rootExitPromise.then((res) => ({ exited: true, res })),
+                    new Promise((resolve) => setTimeout(() => resolve({ exited: false }), rootExitWaitMs)),
+                ]);
+                exitResult = rootExitOrTimeout.exited ? rootExitOrTimeout.res : { exitCode: null, signal: 'SIGKILL' };
+            }
+            else if (exitOrTimeout.type === 'timeout') {
                 opState.timedOut = true;
                 opState.terminationReason = 'timed_out';
-                await this.handleStopPipeline(options.opId, 'timed_out', 1500);
-                exitResult = await handle.onExit;
+                const stopRes = await this.handleStopPipeline(options.opId, 'timed_out', 1500);
+                // 超时路径：根进程已由停止流水线终止，等待根进程退出事实（避免被持有管道的逃逸后代挂死）
+                // 关键防护（问题 4）：给等待根进程退出增加有界上限（1000ms），
+                // 若驱动停止未确认（stopped !== 'confirmed_stopped'）或根进程超出上限仍未退出，转入 indeterminate
+                const rootExitWaitMs = 1000;
+                const rootExitOrTimeout = await Promise.race([
+                    (handle.onRootExit ?? handle.onExit).then((res) => ({ exited: true, res })),
+                    new Promise((resolve) => setTimeout(() => resolve({ exited: false }), rootExitWaitMs)),
+                ]);
+                if (stopRes.stopped !== 'confirmed_stopped' || !rootExitOrTimeout.exited) {
+                    const stored = this.domain.getStore().getOperation(options.opId);
+                    if (stored && stored.status === 'done' && stored.result?.status === 'indeterminate') {
+                        return stored.result;
+                    }
+                    const indetResult = {
+                        kind: 'indeterminate',
+                        status: 'indeterminate',
+                        reason: `Process ${handle.identity.pid} timed out and root process could not be confirmed exited within ${rootExitWaitMs}ms bound: ${stopRes.errorDetails || 'root process still alive'}`,
+                        recoveryGuidance: 'Residual PID detected. Inspect system processes manually before releasing resources.',
+                        durationMs: Date.now() - startTime,
+                        completedAt: new Date().toISOString(),
+                    };
+                    return this.finalizeOperation(options.opId, indetResult, options.requiredResources, false);
+                }
+                exitResult = rootExitOrTimeout.res;
             }
             else {
                 exitResult = exitOrTimeout.res;
@@ -201,7 +415,7 @@ export class ProcessSupervisor {
             let residualProcessesReaped = false;
             if (!drained && exitOrTimeout.type === 'exit') {
                 const reapResult = await this.driver.terminate(handle.identity, 1500);
-                if (!reapResult.stopped) {
+                if (reapResult.stopped !== 'confirmed_stopped') {
                     const indetResult = {
                         kind: 'indeterminate',
                         status: 'indeterminate',
@@ -210,9 +424,7 @@ export class ProcessSupervisor {
                         durationMs: Date.now() - startTime,
                         completedAt: new Date().toISOString(),
                     };
-                    this.domain.getStore().recordOperationResult(options.opId, indetResult, false);
-                    this.domain.getStore().updateRunStatus(options.runId, 'indeterminate', 'crash_detected');
-                    return indetResult;
+                    return this.finalizeOperation(options.opId, indetResult, options.requiredResources, false);
                 }
                 residualProcessesReaped = true;
                 // 被杀死的后代释放管道后，给排空最后一次机会
@@ -229,8 +441,9 @@ export class ProcessSupervisor {
             const stdoutData = stdoutDrainer.getResult();
             const stderrData = stderrDrainer.getResult();
             const isTruncated = stdoutData.isTruncated || stderrData.isTruncated;
-            const outputRef = stdoutData.outputRef || stderrData.outputRef;
-            const outputHash = stdoutData.outputHash || stderrData.outputHash;
+            const spillError = stdoutData.spillError || stderrData.spillError || artifactsDirError;
+            const outputRef = (!spillError && (stdoutData.outputRef || stderrData.outputRef)) || undefined;
+            const outputHash = (!spillError && (stdoutData.outputHash || stderrData.outputHash)) || undefined;
             // 校验进程身份
             const idVerify = await this.driver.verifyIdentity(handle.identity);
             const isResourceOrTimeoutStopped = opState.timedOut ||
@@ -259,14 +472,17 @@ export class ProcessSupervisor {
                 isTruncated,
                 stdoutTruncated: stdoutData.isTruncated,
                 stderrTruncated: stderrData.isTruncated,
-                stdoutRef: stdoutData.outputRef,
-                stderrRef: stderrData.outputRef,
+                stdoutRef: !stdoutData.spillError ? stdoutData.outputRef : undefined,
+                stderrRef: !stderrData.spillError ? stderrData.outputRef : undefined,
                 stdoutBytes: stdoutData.bytesSeen,
                 stderrBytes: stderrData.bytesSeen,
-                stdoutHash: stdoutData.outputHash,
-                stderrHash: stderrData.outputHash,
+                stdoutHash: !stdoutData.spillError ? stdoutData.outputHash : undefined,
+                stderrHash: !stderrData.spillError ? stderrData.outputHash : undefined,
                 ...(residualProcessesReaped ? { residualProcessesReaped: true } : {}),
                 ...(streamCallbackError ? { streamCallbackError } : {}),
+                ...(spillError ? { spillError } : {}),
+                ...(stdoutData.spillError ? { stdoutSpillError: stdoutData.spillError } : {}),
+                ...(stderrData.spillError ? { stderrSpillError: stderrData.spillError } : {}),
                 outputRef,
                 outputHash,
                 terminationReason,
@@ -277,33 +493,43 @@ export class ProcessSupervisor {
                 completedAt: new Date().toISOString(),
             };
             if (opState.stopPromise) {
-                await opState.stopPromise;
-            }
-            const existingOp = this.domain.getStore().getOperation(options.opId);
-            if (existingOp && existingOp.status === 'done') {
-                const storedResult = existingOp.result;
-                if (storedResult?.status === 'indeterminate') {
-                    // 驱动无法确认停止：保留隔离事实与资源锁，绝不覆盖
-                    return existingOp.result;
-                }
-                // 内部停止流水线（超时 / 资源超限）会先写一份粗糙终态；这里用本次采集到的
-                // 真实退出码、输出与耗时覆盖它，避免把已捕获的输出证据丢掉。
-                this.domain.getStore().recordOperationResult(options.opId, result, true);
-                return result;
-            }
-            // 6. [事务提交结果与释放资源]
-            this.domain.getStore().recordOperationResult(options.opId, result, true);
-            this.domain.releaseResources(options.opId, options.requiredResources);
-            if (terminationReason && terminationReason !== 'completed') {
-                this.domain.getStore().updateRunStatus(options.runId, finalStatus === 'cancelled' ? 'cancelled' : 'failed', terminationReason);
-            }
-            return result;
+                const stopRes = await opState.stopPromise;
+                if (stopRes.stopped !== 'confirmed_stopped') {
+                    const stored = this.domain.getStore().getOperation(options.opId);
+                    if (stored && stored.status === 'done') {
+                        return (stored.result ?? null);
+                    }
+                    const indetResult = {
+                        kind: 'indeterminate',
+                        status: 'indeterminate',
+                        reason: `Process ${handle.identity.pid} was cancelled or stopped but could not be confirmed: ${stopRes.errorDetails || 'residual processes still alive'}`,
+                        recoveryGuidance: 'Residual PID detected. Inspect system processes manually before releasing resources.',
+                        durationMs: Date.now() - startTime,
+                        completedAt: new Date().toISOString(),
+                    };
+                    return this.finalizeOperation(options.opId, indetResult, options.requiredResources, false);
+                }
+            }
+            // 6. [事务提交结果与释放资源 - Single Writer]
+            // 统一由 finalizeOperation 写入事实与处理资源
+            return this.finalizeOperation(options.opId, result, options.requiredResources, true, artifactsDir);
         }
         finally {
+            stdoutDrainer?.forceFinalize();
+            stderrDrainer?.forceFinalize();
             if (timeoutTimer)
                 clearTimeout(timeoutTimer);
             if (samplingInterval)
                 clearInterval(samplingInterval);
+            if (opState.stopResolve) {
+                const resolveFn = opState.stopResolve;
+                opState.stopResolve = undefined;
+                resolveFn({
+                    stopped: 'confirmed_stopped',
+                    scope: 'direct_child',
+                    errorDetails: opState.phase === 'done' ? undefined : 'Operation terminated before process activation',
+                });
+            }
             this.activeOperations.delete(options.opId);
         }
     }
@@ -311,52 +537,48 @@ export class ProcessSupervisor {
      * 停止确认流水线 (Stopping Pipeline)
      */
     async cancelOperation(opId, graceMs = 2000) {
-        return this.handleStopPipeline(opId, 'user_cancelled', graceMs);
+        const active = this.ensureActiveOperation(opId);
+        active.cancelRequested = true;
+        if (active.cancelGraceMs === undefined) {
+            active.cancelGraceMs = graceMs;
+        }
+        active.terminationReason = 'user_cancelled';
+        // 若操作仍在等待队列中排队，立刻唤醒
+        this.domain.cancelWait(opId);
+        if (active.phase === 'active' || active.phase === 'stopping') {
+            return this.handleStopPipeline(opId, 'user_cancelled', graceMs);
+        }
+        // 操作仍在等资源、intent_registered 或 spawn 途中，返回已有的或新建的 stopPromise
+        if (!active.stopPromise) {
+            active.stopPromise = new Promise((resolve) => {
+                active.stopResolve = resolve;
+            });
+        }
+        return active.stopPromise;
     }
     async handleStopPipeline(opId, reason, graceMs) {
-        const active = this.activeOperations.get(opId);
-        if (!active) {
-            return { stopped: true, scope: 'direct_child' };
-        }
-        if (active.stopPromise) {
+        const active = this.ensureActiveOperation(opId);
+        if (active.phase === 'stopping' && active.stopPromise) {
             return active.stopPromise;
         }
-        active.stopPromise = (async () => {
-            if (this.domain.isClosed()) {
-                return { stopped: true, scope: 'direct_child' };
-            }
-            if (reason === 'user_cancelled') {
-                active.cancelRequested = true;
+        active.phase = 'stopping';
+        if (reason === 'user_cancelled') {
+            active.cancelRequested = true;
+        }
+        active.terminationReason = reason;
+        const existingResolve = active.stopResolve;
+        const runPipeline = (async () => {
+            if (!active.handle) {
+                const res = { stopped: 'confirmed_stopped', scope: 'direct_child' };
+                existingResolve?.(res);
+                return res;
             }
-            active.terminationReason = reason;
             // 1. 进入 stopping 中间态（保持排他资源锁定，阻断新操作）
             this.domain.getStore().updateOperationStatus(opId, 'stopping');
             // 2. 调用驱动停止流水线 (SIGINT -> grace -> SIGTERM -> SIGKILL)
             const stopResult = await this.driver.terminate(active.handle.identity, graceMs);
-            if (stopResult.stopped) {
-                // 3a. 驱动确认停止 -> 记录终态并安全释放资源
-                const op = this.domain.getStore().getOperation(opId);
-                if (op && op.status !== 'done') {
-                    const cancelResult = {
-                        kind: 'process',
-                        status: reason === 'user_cancelled' ? 'cancelled' : 'failed',
-                        exitCode: null,
-                        signal: 'SIGKILL',
-                        stdout: '',
-                        stderr: `Operation stopped via stopping pipeline (${reason})`,
-                        isTruncated: false,
-                        terminationReason: reason,
-                        identityVerification: 'not_original_process',
-                        durationMs: 0,
-                        completedAt: new Date().toISOString(),
-                    };
-                    this.domain.getStore().recordOperationResult(opId, cancelResult, true);
-                    this.domain.releaseResources(opId, op.requiredResources);
-                    this.domain.getStore().updateRunStatus(op.runId, reason === 'user_cancelled' ? 'cancelled' : 'failed', reason);
-                }
-            }
-            else {
-                // 3b. 驱动无法确认完全停止 -> 转入 indeterminate，绝对保留隔离屏障与锁！
+            // 3. 驱动无法确认停止 -> 立即转入 indeterminate，绝对保留隔离屏障与锁！
+            if (stopResult.stopped !== 'confirmed_stopped') {
                 const op = this.domain.getStore().getOperation(opId);
                 if (op && op.status !== 'done') {
                     const indetResult = {
@@ -364,32 +586,145 @@ export class ProcessSupervisor {
                         status: 'indeterminate',
                         reason: `Process ${active.handle.identity.pid} could not be confirmed stopped: ${stopResult.errorDetails}`,
                         recoveryGuidance: 'Residual PID detected. Inspect system processes manually before releasing resources.',
-                        durationMs: 0,
+                        durationMs: Date.now() - active.startTime,
                         completedAt: new Date().toISOString(),
                     };
-                    // 传递 releaseResources = false，绝对不释放锁
-                    this.domain.getStore().recordOperationResult(opId, indetResult, false);
-                    this.domain.getStore().updateRunStatus(op.runId, 'indeterminate', 'crash_detected');
+                    this.finalizeOperation(opId, indetResult, undefined, false);
                 }
             }
+            existingResolve?.(stopResult);
             return stopResult;
         })();
-        return active.stopPromise;
+        active.stopPromise = runPipeline;
+        return runPipeline;
+    }
+    ensureActiveOperation(opId) {
+        if (this.domain.isClosed()) {
+            throw new OperationNotActiveError(opId, 'domain_closed');
+        }
+        const active = this.activeOperations.get(opId);
+        if (!active || active.phase === 'done') {
+            const stored = this.domain.getStore().getOperation(opId);
+            if (!stored) {
+                throw new OperationNotActiveError(opId, 'not_found');
+            }
+            if (stored.status === 'done') {
+                throw new OperationNotActiveError(opId, 'already_completed');
+            }
+            throw new OperationNotActiveError(opId, 'not_found', `Operation "${opId}" is not active (current status: ${stored.status}).`);
+        }
+        return active;
+    }
+    handlePreSpawnCancellation(options, opState, startTime) {
+        opState.phase = 'done';
+        const stopRes = { stopped: 'confirmed_stopped', scope: 'direct_child' };
+        opState.stopResolve?.(stopRes);
+        opState.stopResolve = undefined;
+        const cancelResult = {
+            kind: 'process',
+            status: 'cancelled',
+            exitCode: null,
+            signal: null,
+            stdout: '',
+            stderr: '',
+            isTruncated: false,
+            terminationReason: 'user_cancelled',
+            evidence: 'unobserved',
+            identityVerification: 'not_original_process',
+            durationMs: Date.now() - startTime,
+            completedAt: new Date().toISOString(),
+        };
+        const stored = this.domain.getStore().getOperation(options.opId);
+        if (!stored) {
+            // 此时操作是在 waiting_resources 阶段就被取消，尚未获取资源租约，亦未正常注册意图。
+            // 为保证 store 中有该操作记录以便写入 cancelled 结果，直接记录预意图取消操作，
+            // 绝不向 resource_leases 写入虚假租约，亦不产生虚假的 OPERATION_INTENT_REGISTERED 事件。
+            const op = {
+                id: options.opId,
+                runId: options.runId,
+                kind: 'process',
+                name: options.name,
+                inputFingerprint: options.inputFingerprint || computeInputFingerprint(options),
+                requiredResources: options.requiredResources || [],
+                status: 'done',
+            };
+            this.domain.getStore().recordPreIntentCancelledOperation(op, this.domain.domainId, cancelResult);
+            this.domain.internalReleaseResources(options.opId, options.requiredResources);
+            return cancelResult;
+        }
+        return this.finalizeOperation(options.opId, cancelResult, options.requiredResources, true);
+    }
+    pruneArtifacts(filter) {
+        return this.domain.pruneArtifacts(filter);
+    }
+    finalizeOperation(opId, result, requiredResources, releaseResourceLock = true, artifactsDir) {
+        const existing = this.domain.getStore().getOperation(opId);
+        if (existing && existing.status === 'done') {
+            throw new Error(`Cannot finalize operation "${opId}": operation is already finalized with status "${existing.status}"`);
+        }
+        if (result.kind === 'process') {
+            const procRes = result;
+            const targetDir = artifactsDir || path.join(this.domain.domainPath, 'artifacts');
+            const stdoutSpillPath = path.join(targetDir, `${opId}-stdout.log`);
+            const stderrSpillPath = path.join(targetDir, `${opId}-stderr.log`);
+            if (!procRes.stdoutRef && fs.existsSync(stdoutSpillPath)) {
+                try {
+                    fs.unlinkSync(stdoutSpillPath);
+                }
+                catch (unlinkErr) {
+                    procRes.spillError = procRes.spillError || unlinkErr.message || String(unlinkErr);
+                }
+            }
+            if (!procRes.stderrRef && fs.existsSync(stderrSpillPath)) {
+                try {
+                    fs.unlinkSync(stderrSpillPath);
+                }
+                catch (unlinkErr) {
+                    procRes.spillError = procRes.spillError || unlinkErr.message || String(unlinkErr);
+                }
+            }
+        }
+        if (result.status === 'indeterminate') {
+            this.domain.getStore().recordOperationResult(opId, result, false);
+            const op = this.domain.getStore().getOperation(opId);
+            if (op) {
+                const termReason = result.terminationReason;
+                this.domain.getStore().updateRunStatus(op.runId, 'indeterminate', termReason);
+            }
+        }
+        else {
+            this.domain.getStore().recordOperationResult(opId, result, true);
+            if (releaseResourceLock) {
+                this.domain.internalReleaseResources(opId, requiredResources);
+            }
+        }
+        return result;
     }
-    setupStreamDrainer(stream, maxBytes, spillFilePath, onChunk, onData) {
-        const chunks = [];
-        let currentBytes = 0;
+    setupStreamDrainer(stream, maxBytes, spillFilePath, onChunk, onData, spillInitError) {
+        const overhead = maxBytes >= 80 ? Math.min(64, Math.floor(maxBytes / 4)) : 0;
+        const effectiveMax = maxBytes - overhead;
+        const headMaxBytes = overhead > 0 ? Math.floor(effectiveMax * 0.75) : maxBytes;
+        const tailMaxBytes = overhead > 0 ? Math.max(0, effectiveMax - headMaxBytes) : 0;
+        const headChunks = [];
+        let headBytes = 0;
         let bytesSeen = 0;
         let isTruncated = false;
         let spillFd = null;
+        let spillError = spillInitError;
         const hash = crypto.createHash('sha256');
         let isFinalized = false;
         let outputHash = undefined;
-        if (spillFilePath) {
+        const tailRing = tailMaxBytes > 0 ? Buffer.alloc(tailMaxBytes) : null;
+        let tailHead = 0;
+        let tailCount = 0;
+        if (spillFilePath && !spillError) {
             try {
                 spillFd = fs.openSync(spillFilePath, 'w');
             }
-            catch { }
+            catch (openErr) {
+                spillError = openErr.message || String(openErr);
+                spillFd = null;
+            }
         }
         const doFinalize = () => {
             if (isFinalized)
@@ -400,13 +735,20 @@ export class ProcessSupervisor {
                     fs.fsyncSync(spillFd);
                     fs.closeSync(spillFd);
                 }
-                catch { }
+                catch (syncErr) {
+                    spillError = spillError || syncErr.message || String(syncErr);
+                }
                 spillFd = null;
             }
-            try {
-                outputHash = hash.digest('hex');
+            if (!spillError) {
+                try {
+                    outputHash = hash.digest('hex');
+                }
+                catch { }
+            }
+            else {
+                outputHash = undefined;
             }
-            catch { }
         };
         const finishPromise = new Promise((resolve) => {
             const finalize = () => {
@@ -414,6 +756,10 @@ export class ProcessSupervisor {
                 resolve();
             };
             stream.on('data', (chunk) => {
+                if (isFinalized) {
+                    // finalize 之后，流继续读走数据避免堵塞或 SIGPIPE，但跳过 hash、落盘和转发
+                    return;
+                }
                 const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
                 bytesSeen += buf.length;
                 if (onChunk) {
@@ -422,32 +768,66 @@ export class ProcessSupervisor {
                     }
                     catch { }
                 }
-                hash.update(buf);
-                // 持续落盘转储全部流
+                // 持续落盘转储全部流与写盘同链哈希 (P0-9)
                 if (spillFd !== null) {
                     try {
                         fs.writeSync(spillFd, buf);
+                        hash.update(buf);
+                    }
+                    catch (writeErr) {
+                        spillError = spillError || writeErr.message || String(writeErr);
+                        try {
+                            fs.closeSync(spillFd);
+                        }
+                        catch { }
+                        spillFd = null;
+                    }
+                }
+                else if (!spillFilePath && !spillError) {
+                    try {
+                        hash.update(buf);
                     }
                     catch { }
                 }
                 if (onData) {
                     onData(buf);
                 }
-                // 内存有界保留
-                if (currentBytes + buf.length <= maxBytes) {
-                    chunks.push(buf);
-                    currentBytes += buf.length;
-                }
-                else {
-                    if (!isTruncated) {
-                        const remaining = maxBytes - currentBytes;
+                // Head 内存有界保留
+                if (headBytes < headMaxBytes) {
+                    if (headBytes + buf.length <= headMaxBytes) {
+                        headChunks.push(buf);
+                        headBytes += buf.length;
+                    }
+                    else {
+                        const remaining = headMaxBytes - headBytes;
                         if (remaining > 0) {
-                            chunks.push(buf.subarray(0, remaining));
-                            currentBytes += remaining;
+                            headChunks.push(buf.subarray(0, remaining));
+                            headBytes += remaining;
                         }
                         isTruncated = true;
                     }
                 }
+                else {
+                    isTruncated = true;
+                }
+                if (bytesSeen > maxBytes) {
+                    isTruncated = true;
+                }
+                // Tail 环形缓冲保留
+                if (tailRing !== null && tailMaxBytes > 0) {
+                    if (buf.length >= tailMaxBytes) {
+                        buf.copy(tailRing, 0, buf.length - tailMaxBytes);
+                        tailHead = 0;
+                        tailCount = tailMaxBytes;
+                    }
+                    else {
+                        for (let i = 0; i < buf.length; i++) {
+                            tailRing[tailHead] = buf[i];
+                            tailHead = (tailHead + 1) % tailMaxBytes;
+                        }
+                        tailCount = Math.min(tailMaxBytes, tailCount + buf.length);
+                    }
+                }
             });
             stream.on('end', finalize);
             stream.on('close', finalize);
@@ -456,12 +836,37 @@ export class ProcessSupervisor {
         return {
             getResult: () => {
                 doFinalize();
+                let content;
+                if (bytesSeen <= maxBytes) {
+                    content = Buffer.concat(headChunks).toString('utf8');
+                }
+                else {
+                    const rawHead = trimToValidUtf8(Buffer.concat(headChunks));
+                    let cleanTail = Buffer.alloc(0);
+                    if (tailRing !== null && tailCount > 0) {
+                        const rawTail = Buffer.alloc(tailCount);
+                        if (tailCount < tailMaxBytes) {
+                            tailRing.copy(rawTail, 0, 0, tailCount);
+                        }
+                        else {
+                            const part1 = tailRing.subarray(tailHead, tailMaxBytes);
+                            const part2 = tailRing.subarray(0, tailHead);
+                            part1.copy(rawTail, 0);
+                            part2.copy(rawTail, part1.length);
+                        }
+                        cleanTail = trimStartToValidUtf8(rawTail);
+                    }
+                    const truncatedBytes = Math.max(0, bytesSeen - rawHead.length - cleanTail.length);
+                    const marker = `\n[... truncated ${truncatedBytes} bytes ...]\n`;
+                    content = rawHead.toString('utf8') + marker + cleanTail.toString('utf8');
+                }
                 return {
-                    content: Buffer.concat(chunks).toString('utf8'),
+                    content,
                     isTruncated,
-                    outputRef: isTruncated && spillFilePath ? spillFilePath : undefined,
-                    outputHash,
+                    outputRef: isTruncated && spillFilePath && !spillError ? spillFilePath : undefined,
+                    outputHash: !spillError ? outputHash : undefined,
                     bytesSeen,
+                    spillError,
                 };
             },
             finishPromise,