@xioflow/kernel 0.1.4 → 0.2.0

package/dist/driver/node-driver.js

@@ -1,44 +1,106 @@
-import { spawn, execFileSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { readBootId, readStartTime, getGroupMembers } from './process-facts.js';
+import { ProcessSampler } from './sampler.js';
+function resolveExecutable(bin, envPath) {
+    if (bin.includes(path.sep)) {
+        try {
+            fs.accessSync(bin, fs.constants.X_OK);
+            return bin;
+        }
+        catch {
+            return null;
+        }
+    }
+    const dirs = (envPath || process.env.PATH || '').split(path.delimiter);
+    for (const dir of dirs) {
+        if (!dir)
+            continue;
+        const full = path.join(dir, bin);
+        try {
+            fs.accessSync(full, fs.constants.X_OK);
+            return full;
+        }
+        catch { }
+    }
+    return null;
+}
 export class NodePlatformDriver {
     name = 'node-default';
+    cachedBootId = readBootId();
+    sampler = ProcessSampler.getInstance();
+    async readBootId() {
+        return this.cachedBootId;
+    }
+    async getGroupEvidence(pgid) {
+        return getGroupMembers(pgid);
+    }
     capabilities = {
         // Windows 无进程组语义：process.kill(-pid) 会失败并退化为只杀直接子进程，
         // 所以必须如实声明不支持，让准入期拒绝 hard 请求而不是静默降级。
         processGroupKill: process.platform !== 'win32',
         accurateStartTime: true,
+        startTimeSource: process.platform === 'linux' ? 'procfs' : process.platform === 'darwin' ? 'ps_lstart' : 'none',
         memoryHardLimit: false, // macOS/Node.js 默认不支持进程树 cgroup 内存硬限
         pidsLimit: false,
         cpuLimit: false,
         // 后代枚举依赖 ps(1)：Windows 上无法枚举，不能谎报 full。
         descendantEnumeration: process.platform === 'win32' ? 'none' : 'full',
+        // 门管道受控启动：POSIX 平台下通过 /bin/sh 与 stdio[3] 实现
+        gatedSpawn: process.platform !== 'win32',
     };
     // 内存中追踪当前驱动启动的所有活跃进程
     activeHandles = new Map();
     // 持续累积后代 PID 集合：leaderPid -> Set<descendantPid>
     cumulativeDescendantsMap = new Map();
-    // 活跃进程树监控定时器：leaderPid -> Timeout
-    descendantPollers = new Map();
+    pollerTimer = null;
     async spawn(command) {
         const stdinPayload = command.stdin === undefined
             ? undefined
             : typeof command.stdin === 'string'
                 ? Buffer.from(command.stdin, 'utf8')
                 : Buffer.from(command.stdin);
+        const childEnv = command.envWhiteList
+            ? { ...command.envWhiteList }
+            : command.inheritEnv === false
+                ? {}
+                : process.env;
+        const useGatedSpawn = Boolean(this.capabilities.gatedSpawn);
+        // 门管道模式下，先验证二进制是否存在与可执行（P0-3 / 契约 #1 保证）
+        if (useGatedSpawn) {
+            const resolved = resolveExecutable(command.execPath, childEnv.PATH);
+            if (!resolved) {
+                const err = new Error(`spawn ${command.execPath} ENOENT`);
+                err.code = 'ENOENT';
+                err.syscall = `spawn ${command.execPath}`;
+                err.path = command.execPath;
+                return Promise.reject(err);
+            }
+        }
         return new Promise((resolve, reject) => {
             let child;
+            let gatePipe = null;
+            let gateReleased = false;
             try {
-                // envWhiteList 是精确语义：给了什么就是什么，不静默补 PATH。
-                const childEnv = command.envWhiteList
-                    ? { ...command.envWhiteList }
-                    : command.inheritEnv === false
-                        ? {}
-                        : process.env;
-                child = spawn(command.execPath, command.args, {
-                    cwd: command.cwd,
-                    env: childEnv,
-                    detached: true,
-                    stdio: [stdinPayload === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'],
-                });
+                if (useGatedSpawn) {
+                    const springboard = 'IFS= read -r _ <&3 || exit 125; exec 3<&-; exec "$0" "$@";';
+                    child = spawn('/bin/sh', ['-c', springboard, command.execPath, ...command.args], {
+                        cwd: command.cwd,
+                        env: childEnv,
+                        detached: true,
+                        stdio: [stdinPayload === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe', 'pipe'],
+                    });
+                    gatePipe = child.stdio[3];
+                }
+                else {
+                    child = spawn(command.execPath, command.args, {
+                        cwd: command.cwd,
+                        env: childEnv,
+                        detached: true,
+                        stdio: [stdinPayload === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'],
+                    });
+                }
             }
             catch (err) {
                 return reject(err);
@@ -49,41 +111,28 @@ export class NodePlatformDriver {
                     reject(err);
                 }
             });
-            child.on('spawn', () => {
+            child.on('spawn', async () => {
                 hasSpawned = true;
                 const pid = child.pid;
                 const startTimeMonotonic = Number(process.hrtime.bigint() / 1000n);
+                const bootId = await this.cachedBootId;
                 const identity = {
                     pid,
                     pgid: pid,
                     startTimeMonotonic,
                     spawnTime: new Date().toISOString(),
                     commandFingerprint: `${command.execPath}:${command.args.join(' ')}`,
+                    bootId: bootId ?? undefined,
                 };
                 const cumSet = new Set();
                 this.cumulativeDescendantsMap.set(pid, cumSet);
-                const scanDescendants = () => {
-                    const currentCum = this.cumulativeDescendantsMap.get(pid);
-                    if (!currentCum)
-                        return;
-                    const tree = this.getProcessTree(pid);
-                    for (const d of tree.allDescendants) {
-                        currentCum.add(d);
-                    }
-                };
-                scanDescendants();
-                const poller = setInterval(scanDescendants, 30);
-                if (poller.unref)
-                    poller.unref();
-                this.descendantPollers.set(pid, poller);
+                this.ensureSharedPoller();
                 const exitPromise = new Promise((exitResolve) => {
                     const cleanup = () => {
-                        const p = this.descendantPollers.get(pid);
-                        if (p) {
-                            clearInterval(p);
-                            this.descendantPollers.delete(pid);
-                        }
                         this.activeHandles.delete(pid);
+                        if (this.activeHandles.size === 0) {
+                            this.stopSharedPoller();
+                        }
                     };
                     child.on('close', (exitCode, signal) => {
                         cleanup();
@@ -107,6 +156,25 @@ export class NodePlatformDriver {
                     child.on('error', () => settle(1, null));
                     child.on('close', (exitCode, signal) => settle(exitCode, signal));
                 });
+                const releaseGate = () => {
+                    if (!gateReleased && gatePipe && !gatePipe.destroyed) {
+                        gateReleased = true;
+                        try {
+                            gatePipe.write('GO\n');
+                            gatePipe.end();
+                        }
+                        catch { }
+                    }
+                };
+                const destroyGate = () => {
+                    if (!gateReleased && gatePipe && !gatePipe.destroyed) {
+                        gateReleased = true;
+                        try {
+                            gatePipe.destroy();
+                        }
+                        catch { }
+                    }
+                };
                 const handle = {
                     identity,
                     stdout: child.stdout,
@@ -114,6 +182,8 @@ export class NodePlatformDriver {
                     onRootExit: rootExitPromise,
                     onExit: exitPromise,
                     rawProcess: child,
+                    releaseGate: useGatedSpawn ? releaseGate : undefined,
+                    destroyGate: useGatedSpawn ? destroyGate : undefined,
                 };
                 this.activeHandles.set(pid, { handle, child, startTime: startTimeMonotonic });
                 // 一次性 stdin：写入后关闭。子进程不读就退出的 EPIPE 不是启动失败，由退出码体现。
@@ -125,12 +195,45 @@ export class NodePlatformDriver {
             });
         });
     }
+    ensureSharedPoller() {
+        if (this.pollerTimer)
+            return;
+        this.pollerTimer = setInterval(async () => {
+            if (this.cumulativeDescendantsMap.size === 0) {
+                this.stopSharedPoller();
+                return;
+            }
+            try {
+                const snapshot = await this.sampler.getSnapshot(30);
+                for (const [leaderPid, cumSet] of this.cumulativeDescendantsMap.entries()) {
+                    const tree = await this.sampler.getProcessTree(leaderPid, snapshot, Array.from(cumSet));
+                    for (const d of tree.allDescendants) {
+                        cumSet.add(d);
+                    }
+                }
+            }
+            catch { }
+        }, 35);
+        if (this.pollerTimer.unref)
+            this.pollerTimer.unref();
+    }
+    stopSharedPoller() {
+        if (this.pollerTimer) {
+            clearInterval(this.pollerTimer);
+            this.pollerTimer = null;
+        }
+    }
     async verifyIdentity(identity) {
-        // 1. 检查操作系统中该 PID 是否存活
-        if (!this.isPidAlive(identity.pid)) {
+        // 1. 检查操作系统中该 PID 是否存活或为僵尸
+        if (!this.isPidAlive(identity.pid) || (await this.sampler.isZombie(identity.pid))) {
             return 'not_original_process';
         }
-        // 2. 核对内存中本驱动登记的启动记录
+        // 2. bootId 核对：宿主若已重启，绝不盲目信任 PID (P0-1)
+        const currentBootId = await this.readBootId();
+        if (identity.bootId && currentBootId && identity.bootId !== currentBootId) {
+            return 'cannot_determine';
+        }
+        // 3. 核对内存中本驱动登记的启动记录
         const tracked = this.activeHandles.get(identity.pid);
         if (tracked) {
             if (identity.startTimeMonotonic &&
@@ -140,21 +243,33 @@ export class NodePlatformDriver {
             }
             return 'cannot_determine';
         }
-        // 3. 跨崩溃/重启进程恢复：查 OS 进程命令行指纹验证真实身份
+        // 4. 跨崩溃/重启进程恢复：查 OS 进程创建时间与命令行指纹 (P0-1)
+        const snapshot = await this.sampler.getSnapshot(100);
+        const proc = snapshot.get(identity.pid);
+        // 进程在进程表中已不存在，或处于僵尸态（<defunct> / Z），直接判定为死亡
+        if (!proc || proc.state === 'Z' || proc.command.includes('<defunct>')) {
+            return 'not_original_process';
+        }
+        // 若命令行指纹不匹配，直接否定为 not_original_process
         if (identity.commandFingerprint) {
-            try {
-                const cmdLine = execFileSync('ps', ['-p', String(identity.pid), '-o', 'command='], {
-                    encoding: 'utf8',
-                    stdio: ['ignore', 'pipe', 'ignore'],
-                }).trim();
-                const baseExec = identity.commandFingerprint.split(':')[0];
-                if (cmdLine && cmdLine.includes(baseExec)) {
+            const baseExec = identity.commandFingerprint.split(':')[0];
+            if (!proc.command.includes(baseExec)) {
+                return 'not_original_process';
+            }
+        }
+        // 若登记了 spawnTime，核对 OS 实际启动时间
+        const actualStartTimeMs = await readStartTime(identity.pid);
+        if (identity.spawnTime && actualStartTimeMs !== null) {
+            const expectedTimeMs = new Date(identity.spawnTime).getTime();
+            if (!isNaN(expectedTimeMs)) {
+                // macOS ps lstart 为 1 秒精度，允许 3 秒宽限
+                if (Math.abs(actualStartTimeMs - expectedTimeMs) > 3000) {
+                    return 'not_original_process';
+                }
+                if (proc && identity.commandFingerprint && proc.command.includes(identity.commandFingerprint.split(':')[0])) {
                     return 'is_original_process';
                 }
             }
-            catch {
-                return 'cannot_determine';
-            }
         }
         return 'cannot_determine';
     }
@@ -162,18 +277,25 @@ export class NodePlatformDriver {
         const pid = identity.pid;
         const cumSet = this.cumulativeDescendantsMap.get(pid);
         // 1. 终止前先枚举后代进程树，捕获所有组内进程与逃逸进程
-        const initialTree = this.getProcessTree(pid);
+        this.sampler.clearCache();
+        const initialTree = await this.sampler.getProcessTree(pid, undefined, cumSet ? Array.from(cumSet) : undefined);
+        if (cumSet) {
+            for (const d of initialTree.allDescendants) {
+                cumSet.add(d);
+            }
+        }
         const allTrackedPids = new Set([pid, ...initialTree.allDescendants]);
         if (cumSet) {
             for (const cp of cumSet) {
                 allTrackedPids.add(cp);
             }
         }
-        // 若原主进程已死且无任何后代存活，直接收尾
+        // 若原主进程已死且无任何进程组或后代存活，直接收尾
+        const isGroupAlive = await this.sampler.isGroupAlive(pid);
         const aliveBeforeSignals = Array.from(allTrackedPids).filter((p) => p !== pid && this.isPidAlive(p));
-        if (!this.isPidAlive(pid) && aliveBeforeSignals.length === 0) {
+        if (!this.isPidAlive(pid) && !isGroupAlive && aliveBeforeSignals.length === 0) {
             this.cumulativeDescendantsMap.delete(pid);
-            return { stopped: true, scope: 'direct_child' };
+            return { stopped: 'confirmed_stopped', scope: 'direct_child' };
         }
         // 第一阶段：SIGINT 中断信号至整组
         this.sendSignalToGroup(pid, 'SIGINT');
@@ -189,7 +311,8 @@ export class NodePlatformDriver {
             exited = await this.waitForGroupAndPids(pid, initialTree.inGroupDescendants, 1000);
         }
         // 组空后再次扫描后代，核查是否有任何残留进程或 setsid 逃逸孤儿
-        const postTree = this.getProcessTree(pid);
+        this.sampler.clearCache();
+        const postTree = await this.sampler.getProcessTree(pid, undefined, cumSet ? Array.from(cumSet) : undefined);
         for (const p of postTree.allDescendants) {
             allTrackedPids.add(p);
         }
@@ -201,151 +324,63 @@ export class NodePlatformDriver {
         // 探活所有曾属于该进程树的后代
         const aliveResiduals = Array.from(allTrackedPids).filter((p) => this.isPidAlive(p));
         if (aliveResiduals.length > 0) {
-            // 存在逃逸或残留孤儿，如实标记 stopped: false 与 residualPids
+            // 存在逃逸或残留孤儿，如实标记 cannot_determine 与 residualPids
             return {
-                stopped: false,
+                stopped: 'cannot_determine',
                 scope: 'unknown',
                 residualPids: aliveResiduals,
                 errorDetails: `Residual or escaped processes still alive after termination: ${aliveResiduals.join(', ')}`,
             };
         }
         this.cumulativeDescendantsMap.delete(pid);
-        return { stopped: true, scope: 'process_group' };
+        return { stopped: 'confirmed_stopped', scope: 'process_group' };
     }
-    async sampleMetrics(identity) {
-        try {
-            const tree = this.getProcessTree(identity.pid);
-            const targetPids = [identity.pid, ...tree.allDescendants].filter((p) => this.isPidAlive(p));
-            if (targetPids.length === 0) {
-                return { rssBytes: 0, pidsCount: 0, cpuTimeMs: 0 };
-            }
-            const out = execFileSync('ps', ['-p', targetPids.join(','), '-o', 'pid=,rss=,time='], {
-                encoding: 'utf8',
-                stdio: ['ignore', 'pipe', 'ignore'],
-            });
-            let totalRssKb = 0;
-            let totalCpuMs = 0;
-            let count = 0;
-            const lines = out.split('\n');
-            for (const line of lines) {
-                const trimmed = line.trim();
-                if (!trimmed)
-                    continue;
-                const parts = trimmed.split(/\s+/);
-                if (parts.length >= 3) {
-                    const rssKb = parseInt(parts[1], 10) || 0;
-                    const timeStr = parts[2];
-                    totalRssKb += rssKb;
-                    totalCpuMs += this.parseCpuTimeToMs(timeStr);
-                    count++;
-                }
-            }
+    async terminateGroup(pgid, graceMs = 2000) {
+        if (!this.capabilities.processGroupKill) {
             return {
-                rssBytes: totalRssKb * 1024,
-                pidsCount: count || targetPids.length,
-                cpuTimeMs: totalCpuMs,
+                stopped: 'not_stopped',
+                scope: 'unknown',
+                errorDetails: 'process groups are not supported on this platform',
             };
         }
-        catch {
-            return { rssBytes: 0, pidsCount: 0, cpuTimeMs: 0 };
-        }
-    }
-    getProcessTree(leaderPid) {
-        const allProcs = this.getAllProcesses();
-        const procsByPid = new Map();
-        const childrenMap = new Map();
-        for (const p of allProcs) {
-            procsByPid.set(p.pid, p);
-            const list = childrenMap.get(p.ppid);
-            if (list) {
-                list.push(p);
-            }
-            else {
-                childrenMap.set(p.ppid, [p]);
-            }
-        }
-        const allDescendants = [];
-        const inGroupDescendants = [];
-        const escapedDescendants = [];
-        const cumSet = this.cumulativeDescendantsMap.get(leaderPid);
-        const historicalDescendants = cumSet ? Array.from(cumSet) : [];
-        // 初始队列包括 leaderPid 以及所有已知历史后代（防止中间父进程提前退出导致孙进程 PPID 变为 1 发生断链漏报）
-        const queue = [leaderPid];
-        const visited = new Set([leaderPid]);
-        for (const hPid of historicalDescendants) {
-            if (!visited.has(hPid)) {
-                visited.add(hPid);
-                queue.push(hPid);
-                const pInfo = procsByPid.get(hPid);
-                if (pInfo) {
-                    allDescendants.push(hPid);
-                    if (pInfo.pgid === leaderPid) {
-                        inGroupDescendants.push(hPid);
-                    }
-                    else {
-                        escapedDescendants.push(hPid);
-                    }
-                }
-            }
-        }
-        while (queue.length > 0) {
-            const currentPid = queue.shift();
-            const children = childrenMap.get(currentPid) || [];
-            for (const child of children) {
-                if (!visited.has(child.pid)) {
-                    visited.add(child.pid);
-                    allDescendants.push(child.pid);
-                    if (child.pgid === leaderPid) {
-                        inGroupDescendants.push(child.pid);
-                    }
-                    else {
-                        escapedDescendants.push(child.pid);
-                    }
-                    queue.push(child.pid);
-                }
-            }
+        if (!(await this.sampler.isGroupAlive(pgid))) {
+            return { stopped: 'confirmed_stopped', scope: 'process_group' };
         }
-        // 扫描可能已由于中间父进程退出导致 PPID 变为 1、但仍同属于 leader 进程组的残留进程
-        for (const p of allProcs) {
-            if (p.pgid === leaderPid && !visited.has(p.pid)) {
-                visited.add(p.pid);
-                allDescendants.push(p.pid);
-                inGroupDescendants.push(p.pid);
+        this.sendSignalToGroup(pgid, 'SIGKILL');
+        const start = Date.now();
+        while (Date.now() - start < graceMs) {
+            this.sampler.clearCache();
+            if (!(await this.sampler.isGroupAlive(pgid))) {
+                this.cumulativeDescendantsMap.delete(pgid);
+                return { stopped: 'confirmed_stopped', scope: 'process_group' };
             }
+            await new Promise((r) => setTimeout(r, 25));
         }
-        if (cumSet) {
-            for (const d of allDescendants) {
-                cumSet.add(d);
-            }
+        const snapshot = await this.sampler.getSnapshot(10);
+        const survivors = [];
+        for (const entry of snapshot.values()) {
+            if (entry.state === 'Z')
+                continue;
+            if (entry.pgid === pgid)
+                survivors.push(entry.pid);
         }
-        return { allDescendants, inGroupDescendants, escapedDescendants };
+        return {
+            stopped: survivors.length === 0 ? 'confirmed_stopped' : 'cannot_determine',
+            scope: 'process_group',
+            residualPids: survivors.length > 0 ? survivors : undefined,
+        };
     }
-    getAllProcesses() {
+    async sampleMetrics(identity) {
         try {
-            const output = execFileSync('ps', ['-A', '-o', 'pid=,ppid=,pgid=,command='], {
-                encoding: 'utf8',
-                stdio: ['ignore', 'pipe', 'ignore'],
-            });
-            const lines = output.split('\n');
-            const procs = [];
-            for (const line of lines) {
-                const trimmed = line.trim();
-                if (!trimmed)
-                    continue;
-                const match = trimmed.match(/^(\d+)\s+(\d+)\s+(\d+)\s+(.*)$/);
-                if (match) {
-                    procs.push({
-                        pid: parseInt(match[1], 10),
-                        ppid: parseInt(match[2], 10),
-                        pgid: parseInt(match[3], 10),
-                        command: match[4],
-                    });
-                }
+            const tree = await this.sampler.getProcessTree(identity.pid);
+            const targetPids = [identity.pid, ...tree.allDescendants].filter((p) => this.isPidAlive(p));
+            if (targetPids.length === 0) {
+                return { rssBytes: 0, pidsCount: 0, cpuTimeMs: 0 };
             }
-            return procs;
+            return this.sampler.sampleMetrics(targetPids);
         }
         catch {
-            return [];
+            return { rssBytes: 0, pidsCount: 0, cpuTimeMs: 0 };
         }
     }
     isPidAlive(pid) {
@@ -357,30 +392,24 @@ export class NodePlatformDriver {
             return err.code === 'EPERM';
         }
     }
-    isGroupAlive(pgid) {
-        try {
-            process.kill(-pgid, 0);
-            return true;
-        }
-        catch (err) {
-            return err.code === 'EPERM';
-        }
-    }
     sendSignalToGroup(pid, signal) {
         try {
             process.kill(-pid, signal);
         }
-        catch {
-            try {
-                process.kill(pid, signal);
+        catch (err) {
+            if (err && err.code === 'ESRCH') {
+                // ESRCH 表示该进程组已不存在或已完全清空，如实返回
+                return;
             }
-            catch { }
+            // 其他错误（如 EPERM）如实上抛，禁止退回向单 PID 发信号（N5 / 契约 #42）
+            throw err;
         }
     }
     async waitForGroupAndPids(pid, inGroupPids, timeoutMs) {
         const start = Date.now();
         while (Date.now() - start < timeoutMs) {
-            const grpAlive = this.isGroupAlive(pid);
+            this.sampler.clearCache();
+            const grpAlive = await this.sampler.isGroupAlive(pid);
             const procAlive = this.isPidAlive(pid);
             const inGrpAlive = inGroupPids.some((p) => this.isPidAlive(p));
             if (!grpAlive && !procAlive && !inGrpAlive) {
@@ -388,41 +417,11 @@ export class NodePlatformDriver {
             }
             await new Promise((r) => setTimeout(r, 50));
         }
-        const stillGrp = this.isGroupAlive(pid);
+        this.sampler.clearCache();
+        const stillGrp = await this.sampler.isGroupAlive(pid);
         const stillProc = this.isPidAlive(pid);
         const stillInGrp = inGroupPids.some((p) => this.isPidAlive(p));
         return !stillGrp && !stillProc && !stillInGrp;
     }
-    parseCpuTimeToMs(timeStr) {
-        try {
-            let days = 0;
-            let rest = timeStr;
-            if (rest.includes('-')) {
-                const daySplit = rest.split('-');
-                days = parseInt(daySplit[0], 10) || 0;
-                rest = daySplit[1];
-            }
-            const parts = rest.split(':');
-            let hours = 0;
-            let minutes = 0;
-            let seconds = 0;
-            if (parts.length === 3) {
-                hours = parseInt(parts[0], 10) || 0;
-                minutes = parseInt(parts[1], 10) || 0;
-                seconds = parseFloat(parts[2]) || 0;
-            }
-            else if (parts.length === 2) {
-                minutes = parseInt(parts[0], 10) || 0;
-                seconds = parseFloat(parts[1]) || 0;
-            }
-            else if (parts.length === 1) {
-                seconds = parseFloat(parts[0]) || 0;
-            }
-            return Math.round(days * 86400000 + hours * 3600000 + minutes * 60000 + seconds * 1000);
-        }
-        catch {
-            return 0;
-        }
-    }
 }
 //# sourceMappingURL=node-driver.js.map