@evomap/evolver-core 2.0.0-beta.19 → 2.0.0-beta.22

package/dist/util/index.d.ts

@@ -1,3 +1,4 @@
-export * from './fileLock.js';
+export { acquireLock, attachLockGuardianToProcess, clearLockGuardianForProcess, inspectFileLockOwnerProcess, LockReleaseError, LockTimeoutError, MAX_LOCK_OWNER_BYTES, releaseLock, retainLockGuardianForProcess, readFileLockProcessStartIdentity, sameFileLockProcessStartIdentity, parseFileLockProcessStartIdentity, syncSleep, transferLockOwnershipToProcess, UnsafeLockPathError, } from './fileLock.js';
+export type { AcquireLockOptions, AttachLockGuardianResult, ClearLockGuardianResult, FileLockOwnerRecord, FileLockOwnerProcessStatus, FileLockProcessStartIdentity, ReleaseLockReason, ReleaseLockResult, RetainLockGuardianResult, TransferLockOwnershipReason, TransferLockOwnershipResult, UnsafeLockPathReason, } from './fileLock.js';
 export * from './fetchPort.js';
 export * from './version.js';

package/dist/util/index.js

@@ -1,3 +1,3 @@
-export * from './fileLock.js';
+export { acquireLock, attachLockGuardianToProcess, clearLockGuardianForProcess, inspectFileLockOwnerProcess, LockReleaseError, LockTimeoutError, MAX_LOCK_OWNER_BYTES, releaseLock, retainLockGuardianForProcess, readFileLockProcessStartIdentity, sameFileLockProcessStartIdentity, parseFileLockProcessStartIdentity, syncSleep, transferLockOwnershipToProcess, UnsafeLockPathError, } from './fileLock.js';
 export * from './fetchPort.js';
 export * from './version.js';

package/dist/verify/index.d.ts

@@ -1,4 +1,5 @@
-export * from './validation.js';
+export { BLOCKED_NODE_FLAGS, SHELL_METACHARS, isAllowed, isNodeExecutable, isValidationCommandAllowed, nodeFlagViolation, normalizeExecutableName, runValidation, summarizeStdout, validationScriptPath, } from './validation.js';
+export type { CommandRunner, RunOutput, ValidationCommand, ValidationPlan, ValidationResult, } from './validation.js';
 export * from './rollback.js';
 export * from './sandboxRunner.js';
 export * from './sandboxedValidation.js';

package/dist/verify/index.js

@@ -1,4 +1,4 @@
-export * from './validation.js';
+export { BLOCKED_NODE_FLAGS, SHELL_METACHARS, isAllowed, isNodeExecutable, isValidationCommandAllowed, nodeFlagViolation, normalizeExecutableName, runValidation, summarizeStdout, validationScriptPath, } from './validation.js';
 export * from './rollback.js';
 export * from './sandboxRunner.js';
 export * from './sandboxedValidation.js';

package/dist/verify/sandboxRunner.d.ts

@@ -31,6 +31,8 @@ export interface SandboxOptions {
     unshareCheck?: () => boolean;
     /** Injected cgroup allocator (test seam). */
     resourceGroupFactory?: () => SandboxResourceGroup | null;
+    /** Cooperative cancellation for the current validation command. */
+    signal?: AbortSignal;
 }
 export interface SandboxResourceGroup {
     procsFile: string;

package/dist/verify/sandboxRunner.js

@@ -8,10 +8,12 @@ import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, rmdirSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { isAbsolute, join, relative, resolve, sep } from 'node:path';
-import { isNodeExecutable, nodeFlagViolation, SHELL_METACHARS } from './validation.js';
+import { classifyNodeValidationInvocation, isNodeExecutable, nodeFlagViolation, SHELL_METACHARS, tokenizeValidationCommand, } from './validation.js';
 const DEFAULT_TIMEOUT_MS = 60_000;
 const MAX_TIMEOUT_MS = 120_000;
 const MAX_OUTPUT_CHARS = 4000;
+const PROCESS_TREE_KILL_TIMEOUT_MS = 5_000;
+const PROCESS_TREE_EXIT_WAIT_MS = 5_000;
 const CGROUP_ROOT = '/sys/fs/cgroup';
 const TRUSTED_SYSTEM_PATH = '/usr/sbin:/usr/bin:/sbin:/bin';
 const SYSTEM_SH = '/bin/sh';
@@ -212,7 +214,9 @@ export function unshareNetAvailable() {
     return unshareCache;
 }
 function parse(cmd) {
-    const tokens = cmd.trim().split(/\s+/).filter(Boolean);
+    const tokens = tokenizeValidationCommand(cmd);
+    if (!tokens)
+        return null;
     return { executable: tokens[0] ?? '', args: tokens.slice(1) };
 }
 function scrubEnv(allow) {
@@ -224,6 +228,72 @@ function scrubEnv(allow) {
     }
     return out;
 }
+/**
+ * 终止完整的验证进程树，而不只是启动器。POSIX 启动器会独立成组，
+ * 可以安全地按进程组寻址；Windows 没有可移植的 Node API，因此使用受信任的
+ * System32 taskkill，并在该工具不可用时保留直接子进程兜底。
+ */
+function terminateProcessTree(child) {
+    const pid = child.pid;
+    if (pid === undefined)
+        return;
+    if (process.platform === 'win32') {
+        const systemRoot = process.env.SystemRoot ?? process.env.WINDIR;
+        const taskkill = systemRoot && isAbsolute(systemRoot)
+            ? join(systemRoot, 'System32', 'taskkill.exe')
+            : undefined;
+        if (taskkill && existsSync(taskkill)) {
+            try {
+                const result = spawnSync(taskkill, ['/PID', String(pid), '/T', '/F'], {
+                    shell: false,
+                    windowsHide: true,
+                    stdio: 'ignore',
+                    timeout: PROCESS_TREE_KILL_TIMEOUT_MS,
+                });
+                if (result.status === 0)
+                    return;
+            }
+            catch {
+                // 回退到下面的直接子进程终止；命令结果仍保持 fail-closed。
+            }
+        }
+        try {
+            child.kill('SIGKILL');
+        }
+        catch { /* 尽力终止；最终失败状态仍由 close/error 决定 */ }
+        return;
+    }
+    // 负 PID 指向 detached 进程组；若子进程未能成为组长，下面的直接终止仍是兜底。
+    try {
+        process.kill(-pid, 'SIGKILL');
+    }
+    catch { /* 进程组不存在或已退出 */ }
+    try {
+        if (!child.killed)
+            child.kill('SIGKILL');
+    }
+    catch { /* 尽力终止 */ }
+}
+function processTreeExists(pid) {
+    try {
+        process.kill(process.platform === 'win32' ? pid : -pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM 说明进程仍存在但当前用户暂时没有查询权限；不能把它当成已退出，
+        // 否则取消结果可能在后代仍运行时提前返回。
+        return error?.code === 'EPERM';
+    }
+}
+/** 取消后短暂等待，确保后代进程不会在 runner 返回成功解析后继续存活。 */
+async function waitForProcessTreeExit(pid) {
+    if (pid === undefined)
+        return;
+    const deadline = Date.now() + PROCESS_TREE_EXIT_WAIT_MS;
+    while (Date.now() < deadline && processTreeExists(pid)) {
+        await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+}
 /**
  * Build a hardened CommandRunner. The executable allowlist is the ValidationPlan's job (runValidation);
  * this only hardens how an allowed command runs.
@@ -231,16 +301,46 @@ function scrubEnv(allow) {
 export function makeSandboxRunner(opts = {}) {
     const timeout = Math.min(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS);
     const envAllow = opts.envAllowKeys ?? DEFAULT_ENV_ALLOW;
-    return (cmd) => new Promise((resolve) => {
-        const deny = (msg, code = 126) => resolve({ exitCode: code, stdout: `[sandbox] ${msg}` });
-        const { executable, args } = parse(cmd);
+    return (cmd, signal) => new Promise((resolve) => {
+        const activeSignal = signal ?? opts.signal;
+        let settled = false;
+        let aborted = false;
+        let timedOut = false;
+        let terminationStarted = false;
+        let timeoutTimer;
+        let removeAbortListener = () => { };
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            removeAbortListener();
+            resolve(result);
+        };
+        const deny = (msg, code = 126) => finish({ exitCode: code, stdout: `[sandbox] ${msg}` });
+        if (activeSignal?.aborted)
+            return deny('cancelled', 130);
+        const parsed = parse(cmd);
+        if (!parsed)
+            return deny('invalid command syntax', 1);
+        const { executable, args } = parsed;
         if (!executable)
             return deny('empty command', 1);
+        if (isNodeExecutable(executable) && (args.length === 0 || (args.length === 1 && args[0] === '--'))) {
+            return deny('rejected: node script is required');
+        }
         if (SHELL_METACHARS.test(cmd))
             return deny('rejected: shell metacharacter (no shell is provided; split compound commands)');
         const badFlag = nodeFlagViolation(executable, args);
         if (badFlag)
             return deny(`rejected: blocked node flag ${badFlag}`);
+        if (isNodeExecutable(executable)) {
+            const invocation = classifyNodeValidationInvocation(executable, args);
+            if (invocation.kind === 'invalid') {
+                return invocation.option
+                    ? deny(`rejected: unsupported node option ${invocation.option}`)
+                    : deny('rejected: node script is required');
+            }
+        }
         // Isolation (#26): fail-safe — if we can't actually create the namespaces, refuse rather than run un-isolated.
         if ((opts.noNetwork || opts.hideHomeSecrets || opts.readOnlyFilesystem) && !(opts.unshareCheck ?? unshareNetAvailable)()) {
             return deny('rejected: requested namespace isolation is unavailable');
@@ -264,6 +364,9 @@ export function makeSandboxRunner(opts = {}) {
             if (cleaned)
                 return;
             cleaned = true;
+            if (timeoutTimer !== undefined)
+                clearTimeout(timeoutTimer);
+            removeAbortListener();
             resourceGroup?.cleanup();
             if (ownTemp) {
                 try {
@@ -295,21 +398,62 @@ export function makeSandboxRunner(opts = {}) {
                 shell: false,
                 cwd,
                 env,
-                timeout,
-                killSignal: 'SIGKILL',
+                // POSIX 依靠 detached 进程组执行整树终止；Windows 的 taskkill 直接沿父子树追踪，保持启动器附着可
+                // 避免兜底终止时产生孤儿进程。
+                detached: process.platform !== 'win32',
+                windowsHide: true,
                 stdio: [opts.readOnlyFilesystem ? 'pipe' : 'ignore', 'pipe', 'pipe'],
             });
+            let childClosed = false;
             let out = '';
             const cap = (d) => { if (out.length < MAX_OUTPUT_CHARS)
                 out += String(d); };
             child.stdout?.on('data', cap);
             child.stderr?.on('data', cap);
-            child.on('error', (err) => { cleanup(); resolve({ exitCode: 127, stdout: `[sandbox] spawn error: ${err.message}` }); });
-            child.on('close', (code, signal) => { cleanup(); resolve({ exitCode: code ?? (signal ? 137 : 1), stdout: out.slice(0, MAX_OUTPUT_CHARS) }); });
+            const complete = async (result) => {
+                if (terminationStarted)
+                    await waitForProcessTreeExit(child.pid);
+                cleanup();
+                finish(result);
+            };
+            // 先注册生命周期处理器，再暴露 AbortSignal 监听器，堵住快速命令退出后 runner 尚未观察 close
+            // 事件、调用方却已经 abort 的竞态窗口。
+            child.on('error', (err) => {
+                childClosed = true;
+                void complete({ exitCode: aborted ? 130 : timedOut ? 137 : 127, stdout: `[sandbox] spawn error: ${err.message}` });
+            });
+            child.on('close', (code, childSignal) => {
+                childClosed = true;
+                void complete({
+                    exitCode: aborted ? 130 : timedOut ? 137 : code ?? (childSignal ? 137 : 1),
+                    stdout: out.slice(0, MAX_OUTPUT_CHARS),
+                });
+            });
+            const terminate = (reason) => {
+                // close 事件等待继承的 stdio 句柄时，exitCode 可能已经设置。必须持续启用整树终止直到观察到
+                // close，否则快速退出的启动器可能留下仍在运行的后代进程。
+                if (terminationStarted || childClosed)
+                    return;
+                terminationStarted = true;
+                aborted = reason === 'abort';
+                timedOut = reason === 'timeout';
+                resourceGroup?.cleanup();
+                terminateProcessTree(child);
+            };
+            const onAbort = () => terminate('abort');
+            if (activeSignal) {
+                removeAbortListener = () => activeSignal.removeEventListener('abort', onAbort);
+                if (activeSignal.aborted)
+                    onAbort();
+                else
+                    activeSignal.addEventListener('abort', onAbort, { once: true });
+            }
+            timeoutTimer = timeout > 0 ? setTimeout(() => terminate('timeout'), timeout) : undefined;
+            timeoutTimer?.unref?.();
         }
         catch (e) {
             cleanup();
-            resolve({ exitCode: 127, stdout: `[sandbox] spawn failed: ${e instanceof Error ? e.message : 'err'}` });
+            finish({ exitCode: 127, stdout: `[sandbox] spawn failed: ${e instanceof Error ? e.message : 'err'}` });
         }
     });
 }

package/dist/verify/sandboxedValidation.d.ts

@@ -1,16 +1,19 @@
 import { type SandboxResourceGroup } from './sandboxRunner.js';
 import { type ValidationResult } from './validation.js';
+export type SandboxedValidationSkipReason = 'missing_script' | 'script_outside_root' | 'script_symlink' | 'script_unresolvable';
 export interface SandboxedValidationSkippedCommand {
     cmd: string;
     script: string;
-    reason: 'missing_script';
+    reason: SandboxedValidationSkipReason;
 }
 export interface SandboxedValidationResult {
     passed: boolean;
+    /** 是否因宿主取消而终止；取消永远不是成功验证。 */
+    cancelled?: boolean;
     /** Convenience score for cycle outcomes: 0.95 pass / 0.2 fail (matches the prior inline hook). */
     score: number;
     results: ValidationResult[];
-    /** Declared repo-relative validation scripts that were absent from this checkout. */
+    /** Validation commands not executed because their script was missing or failed the path safety gate. */
     skipped: SandboxedValidationSkippedCommand[];
     /**
      * Whether OS-namespace isolation (no-network + hidden home secrets) was applied. TRUE only where unprivileged
@@ -25,6 +28,8 @@ export declare function readOnlyIsolationAvailable(): boolean;
 export interface SandboxedValidationOptions {
     /** Per-command timeout (ms), forwarded to the sandbox runner. */
     timeoutMs?: number;
+    /** Cooperative cancellation forwarded to the validation process. */
+    signal?: AbortSignal;
     /** Test seam: override the unprivileged-namespace availability probe. */
     unshareCheck?: () => boolean;
     /** Refuse before spawning when network/home namespace isolation is unavailable. */

package/dist/verify/sandboxedValidation.js

@@ -4,10 +4,10 @@
 // namespaces exist — no network + hidden home secrets, so a validation command cannot phone home / exfiltrate to
 // game the pass/fail. This is the "verifier outside the repo, untrusted caller" half the safety model relies on.
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, realpathSync, rmSync } from 'node:fs';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { isolationCommand, makeSandboxRunner, sandboxResourceLimitsAvailable, unshareNetAvailable, } from './sandboxRunner.js';
-import { runValidation, validationScriptPath } from './validation.js';
+import { runValidation, tokenizeValidationCommand, validationScriptPath, } from './validation.js';
 let readOnlyIsolationAvailableCache;
 let readOnlyFilesystemIsolationAvailableCache;
 export function readOnlyFilesystemIsolationAvailable() {
@@ -69,6 +69,53 @@ function validationReadOnlyRoot(cwd) {
         current = parent;
     }
 }
+function skippedCommand(cmd, script, reason) {
+    return { cmd, script, reason };
+}
+/**
+ * Validate the script target before it reaches the runner. The runner's mount namespace is read-only, not a chroot,
+ * so lexical containment alone is insufficient: a path inside the checkout may resolve through a symlink outside it.
+ * Symlink script entries are rejected outright, and the canonical target is checked immediately before execution.
+ */
+function classifyValidationScript(cmd, script, validationCwd, readOnlyRoot) {
+    if (isAbsolute(script)) {
+        return { ok: false, skipped: skippedCommand(cmd, script, 'script_outside_root') };
+    }
+    let candidate;
+    try {
+        candidate = resolve(validationCwd, script);
+    }
+    catch {
+        return { ok: false, skipped: skippedCommand(cmd, script, 'script_unresolvable') };
+    }
+    if (!pathIsWithin(readOnlyRoot, candidate)) {
+        return { ok: false, skipped: skippedCommand(cmd, script, 'script_outside_root') };
+    }
+    let metadata;
+    try {
+        metadata = lstatSync(candidate);
+    }
+    catch {
+        return { ok: false, skipped: skippedCommand(cmd, script, 'missing_script') };
+    }
+    if (metadata.isSymbolicLink()) {
+        return { ok: false, skipped: skippedCommand(cmd, script, 'script_symlink') };
+    }
+    if (!metadata.isFile()) {
+        return { ok: false, skipped: skippedCommand(cmd, script, 'script_unresolvable') };
+    }
+    let canonicalScript;
+    try {
+        canonicalScript = realpathSync(candidate);
+    }
+    catch {
+        return { ok: false, skipped: skippedCommand(cmd, script, 'script_unresolvable') };
+    }
+    if (!pathIsWithin(readOnlyRoot, canonicalScript)) {
+        return { ok: false, skipped: skippedCommand(cmd, script, 'script_outside_root') };
+    }
+    return { ok: true };
+}
 /**
  * Run validation commands in the hardened sandbox. Isolation (no-network + hidden home secrets) is requested only
  * when unprivileged namespaces are available; elsewhere (Windows/macOS) it degrades to the non-namespace hardening
@@ -77,45 +124,56 @@ function validationReadOnlyRoot(cwd) {
  * preserving prior behavior; note this differs from runValidation's own "no commands = not verified" stance.
  */
 export async function runSandboxedValidation(cmds, cwd, opts = {}) {
+    if (opts.signal?.aborted)
+        return { passed: false, cancelled: true, score: 0.2, results: [], skipped: [], isolated: false };
     const isolationCheck = opts.unshareCheck ?? (opts.requireIsolation ? readOnlyIsolationAvailable : unshareNetAvailable);
     const isolated = isolationCheck();
     if (opts.requireIsolation && !isolated) {
-        return { passed: false, score: 0.2, results: [], skipped: [], isolated: false };
+        return { passed: false, cancelled: opts.signal?.aborted === true, score: 0.2, results: [], skipped: [], isolated: false };
     }
     let validationCwd = resolve(cwd);
     let readOnlyRoot = opts.readOnlyRoot ? resolve(opts.readOnlyRoot) : validationReadOnlyRoot(validationCwd);
-    if (opts.requireIsolation && isolated) {
-        try {
-            validationCwd = realpathSync(validationCwd);
-            readOnlyRoot = realpathSync(readOnlyRoot);
-        }
-        catch {
-            return { passed: false, score: 0.2, results: [], skipped: [], isolated };
-        }
-        if (dirname(readOnlyRoot) === readOnlyRoot || !pathIsWithin(readOnlyRoot, validationCwd)) {
-            return { passed: false, score: 0.2, results: [], skipped: [], isolated };
-        }
+    // Canonicalize the validation root in every mode. Namespace isolation is an additional boundary, not a substitute
+    // for refusing an absolute, escaping, or symlinked script path; this also keeps the Windows/macOS path fail closed.
+    try {
+        validationCwd = realpathSync(validationCwd);
+        readOnlyRoot = realpathSync(readOnlyRoot);
+    }
+    catch {
+        return { passed: false, cancelled: opts.signal?.aborted === true, score: 0.2, results: [], skipped: [], isolated };
+    }
+    if (dirname(readOnlyRoot) === readOnlyRoot || !pathIsWithin(readOnlyRoot, validationCwd)) {
+        return { passed: false, cancelled: opts.signal?.aborted === true, score: 0.2, results: [], skipped: [], isolated };
     }
     // ONLY a truly empty command set is a vacuous pass (nothing to verify). A non-empty set with blank entries is a
     // malformed plan, NOT a pass: blanks are kept (trimmed to '') so they fall outside the allowlist and fail, rather
     // than being silently dropped into a pass (Bugbot).
     if (cmds.length === 0)
-        return { passed: true, score: 0.95, results: [], skipped: [], isolated };
+        return { passed: true, cancelled: false, score: 0.95, results: [], skipped: [], isolated };
     const list = cmds.map((c) => String(c ?? '').trim());
-    // Validation plans may reference repo-relative scripts that do not exist in this checkout; skip only those.
+    // Validation plans may reference repo-relative scripts that do not exist in this checkout; skip those, but never
+    // execute a script that is absolute, escapes the root, resolves through a symlink, or is not a regular file.
     const skipped = [];
     const runnable = [];
     for (const cmd of list) {
         const script = validationScriptPath(cmd);
-        if (script && !isAbsolute(script) && !existsSync(resolve(validationCwd, script))) {
-            skipped.push({ cmd, script, reason: 'missing_script' });
-            console.warn(`[Validation] Skipping validation command (script not in repoRoot): ${script}`);
-            continue;
+        if (script) {
+            const classification = classifyValidationScript(cmd, script, validationCwd, readOnlyRoot);
+            if (!classification.ok) {
+                skipped.push(classification.skipped);
+                if (classification.skipped.reason === 'missing_script') {
+                    console.warn(`[Validation] Skipping validation command (script not in repoRoot): ${script}`);
+                }
+                else {
+                    console.warn(`[Validation] Rejecting validation command (${classification.skipped.reason}): ${script}`);
+                }
+                continue;
+            }
         }
         runnable.push(cmd);
     }
     if (runnable.length === 0)
-        return { passed: false, score: 0.2, results: [], skipped, isolated };
+        return { passed: false, cancelled: opts.signal?.aborted === true, score: 0.2, results: [], skipped, isolated };
     const scratch = isolated && opts.requireIsolation
         ? mkdtempSync('/var/tmp/evolver-validation-')
         : undefined;
@@ -129,21 +187,41 @@ export async function runSandboxedValidation(cmds, cwd, opts = {}) {
         readOnlyRoot,
         ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
         ...(opts.resourceGroupFactory ? { resourceGroupFactory: opts.resourceGroupFactory } : {}),
+        ...(opts.signal ? { signal: opts.signal } : {}),
         unshareCheck: () => isolated,
     });
-    const allowlist = [...new Set(runnable.map((c) => c.split(/\s+/)[0] ?? '').filter(Boolean))];
+    // Re-check each script immediately before its spawn. The initial pass supplies precise skipped reasons, while
+    // this second gate closes the degraded-mode window where an earlier validator could replace a later path.
+    const guardedRunner = async (cmd, signal) => {
+        const script = validationScriptPath(cmd);
+        if (script) {
+            const classification = classifyValidationScript(cmd, script, validationCwd, readOnlyRoot);
+            if (!classification.ok) {
+                return {
+                    exitCode: 126,
+                    stdout: `[sandbox] rejected: ${classification.skipped.reason}: ${script}`,
+                };
+            }
+        }
+        return runner(cmd, signal);
+    };
+    const allowlist = [...new Set(runnable
+            .map((c) => tokenizeValidationCommand(c)?.[0] ?? '')
+            .filter(Boolean))];
     let results;
     let passed;
+    let cancelled;
     try {
-        ({ results, passed } = await runValidation({ commands: runnable.map((cmd) => ({ cmd })), allowlist }, runner));
+        ({ results, passed, cancelled } = await runValidation({ commands: runnable.map((cmd) => ({ cmd })), allowlist }, guardedRunner, opts.signal));
     }
     finally {
         if (scratch)
             rmSync(scratch, { recursive: true, force: true });
     }
-    const complete = skipped.length === 0;
+    const complete = skipped.length === 0 && !cancelled;
     return {
         passed: passed && complete,
+        cancelled,
         score: passed && complete ? 0.95 : 0.2,
         results,
         skipped,

package/dist/verify/validation.d.ts

@@ -19,15 +19,35 @@ export interface RunOutput {
     exitCode: number;
     stdout: string;
 }
-export type CommandRunner = (cmd: string) => Promise<RunOutput> | RunOutput;
+export type CommandRunner = (cmd: string, signal?: AbortSignal) => Promise<RunOutput> | RunOutput;
 export declare const SHELL_METACHARS: RegExp;
+/**
+ * Parse one validation command without invoking a shell. Quotes group whitespace and backslash only escapes
+ * whitespace, quotes, or another backslash; no variable expansion or command substitution is performed.
+ * A null result means the command has an unterminated quote and must be rejected.
+ */
+export declare function tokenizeValidationCommand(command: string): string[] | null;
 export declare const BLOCKED_NODE_FLAGS: Set<string>;
 export declare function normalizeExecutableName(executable: string): string;
 export declare function isNodeExecutable(executable: string): boolean;
 export declare function nodeFlagViolation(executable: string, args: readonly string[]): string | null;
+export type NodeValidationInvocation = {
+    kind: 'script';
+    script: string;
+} | {
+    kind: 'safe_no_script';
+} | {
+    kind: 'invalid';
+    option?: string;
+};
+/**
+ * 将 Node 命令限制为明确的脚本位置，防止带参数的选项吞掉下一个 token 后绕过脚本路径检查。
+ * 验证只需要普通脚本、语法检查，以及兼容旧 Gene 的 version/help 身份检查；其他前置选项默认拒绝。
+ */
+export declare function classifyNodeValidationInvocation(executable: string, args: readonly string[]): NodeValidationInvocation;
 /** 命令首 token(可执行名)是否在项目声明的 allowlist 内. */
 export declare function isAllowed(cmd: string, allowlist: readonly string[]): boolean;
-/** Extract the local script targeted by `node <script> ...`, or null for non-script node commands. */
+/** Extract the unambiguous script targeted by `node <script> ...`, or null for non-script/unsupported commands. */
 export declare function validationScriptPath(cmd: string): string | null;
 /** stdout 摘要 = 首行 + 末行(去 canary.js 隐形约定: 不找魔法字符串, 只留可读摘要). */
 export declare function summarizeStdout(stdout: string): string;
@@ -35,9 +55,10 @@ export declare function summarizeStdout(stdout: string): string;
  * 跑校验(M4A-4). 判价值 = **exit code + stdout 摘要**, 不依赖 canary.js 魔法字符串(批注#22).
  * 不在 allowlist 的命令 auto-deny(不执行, allowed=false), 守无人值守安全.
  */
-export declare function runValidation(plan: ValidationPlan, run: CommandRunner): Promise<{
+export declare function runValidation(plan: ValidationPlan, run: CommandRunner, signal?: AbortSignal): Promise<{
     results: ValidationResult[];
     passed: boolean;
+    cancelled: boolean;
 }>;
 /**
  * 检查验证命令是否安全可作为 Gene.validation 条目使用（忠实移植 v1 policyCheck.isValidationCommandAllowed）。