@actiondock/core 2.20.0 → 2.21.0

package/dist/project/loader.js

@@ -1,10 +1,10 @@
-import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { NodeModuleLoader, unwrapDefaultExport } from "../platform/module-loader.js";
 import { ActionDockError, ACTION_LOAD_FAILED, describeActionLoadFailure, INVALID_ACTION_ID, INVALID_JSON, INVALID_PACKAGE_ID, INVALID_PLAYBOOK_ID, MANIFEST_LOAD_FAILED, PLAYBOOK_NOT_FOUND, PROJECT_CONFIG_NOT_FOUND, } from "../errors.js";
 import { loadManifest, ACTION_ID_REGEX, PLAYBOOK_ID_REGEX } from "./manifest.js";
 import { assertValidConfigDeclarations } from "./config-declarations.js";
+import { runPackageManager } from "./package-manager.js";
 /**
  * 从指定目录开始向上逐级递归查找包含 `actiondock.json` 的项目根目录。
  *
@@ -85,36 +85,21 @@ export const ALLOWED_INSTALLERS = new Set(["npm", "bun"]);
 /**
  * 异步探测包管理器可用性（通过执行 --version 并检查退出码）。
  *
- * 异步化取舍说明：
- * - 替换同步阻塞子进程调用，避免阻塞 Node.js 事件循环；
- * - Windows 兼容性保留：npm 在 Windows 上是 .cmd 批处理脚本，在 shell 开启下执行以避免直接调用报错；
- * - 探测命令限制于白名单内部候选，杜绝外部输入注入风险。
+ * 运维规范：
+ * - 复用统一包管理器启动解析与驱动底座，以 shell: false 执行；
+ * - 短超时限制，避免探测阻滞事件循环；
+ * - 仅在未明确指定包管理器时进行回退探测，选择后的执行失败不盲目换工具。
  */
-function probePackageManager(command) {
-    return new Promise((resolve) => {
-        try {
-            const proc = spawn(command, ["--version"], {
-                stdio: "pipe",
-                shell: process.platform === "win32",
-            });
-            let settled = false;
-            proc.on("error", () => {
-                if (!settled) {
-                    settled = true;
-                    resolve(false);
-                }
-            });
-            proc.on("close", (code) => {
-                if (!settled) {
-                    settled = true;
-                    resolve(code === 0);
-                }
-            });
-        }
-        catch {
-            resolve(false);
-        }
-    });
+async function probePackageManager(command) {
+    try {
+        const result = await runPackageManager(command, ["--version"], {
+            timeoutMs: 3000,
+        });
+        return result.status === 0;
+    }
+    catch {
+        return false;
+    }
 }
 /**
  * 探测宿主系统中可用的包管理工具。

package/dist/project/package-manager.d.ts

@@ -0,0 +1,40 @@
+import { type CommandExecutionResult, type ExecuteCommandOptions } from "../process/command-executor.js";
+export type { CommandExecutionResult };
+export interface ResolvePackageManagerOptions {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    platform?: NodeJS.Platform;
+    execPath?: string;
+}
+export interface PackageManagerInvocation {
+    executable: string;
+    args: string[];
+}
+export interface RunPackageManagerOptions extends ExecuteCommandOptions {
+    platform?: NodeJS.Platform;
+    execPath?: string;
+}
+/**
+ * 解析包管理器在目标平台上的确定性启动规范。
+ *
+ * 核心设计契约：
+ * - 保持参数边界与数组结构（保留 argv 边界，路径中的空格、引号、&、% 与 ! 原样保留）；
+ * - shell: false 语义，杜绝命令注入与 Node.js DEP0190 警告；
+ * - POSIX 平台保留正常 PATH 命令执行，兼容已有 fake npm 脚本；
+ * - Windows 平台查找遵循 PATH 目录顺序及 PATHEXT 后缀顺序（默认 .COM;.EXE;.BAT;.CMD）；
+ * - PATH 所选工具为唯一事实源，显式传入 env 必须被尊重，绝不从 process.env 漏回其它 PATH；
+ * - Windows 平台原生程序（.exe, .com）直接保留该可执行文件与原数组 args，无需绕过原生版本管理器；
+ * - Windows 平台 Bun 仅支持原生程序，遇到 cmd/bat 包装脚本明确报错，无工具时严禁退回名称；
+ * - Windows 平台 npm.cmd/bat：优先其真实目录布局定位标准 npm-cli.js，由 execPath (Node) 无 shell 启动；
+ * - 仅支持标准可定位 CLI 布局，非标准 wrapper 显式报错，无有效 PATH 工具显式报错。
+ */
+export declare function resolvePackageManagerInvocation(manager: "npm" | "bun", args: readonly string[], options?: ResolvePackageManagerOptions): PackageManagerInvocation;
+/**
+ * 统一执行包管理器命令。
+ *
+ * 运维规范：
+ * - 结合 resolvePackageManagerInvocation 完成无 shell 真实命令定位；
+ * - 通过统一 ProcessDriver 底座执行命令，保留取消、超时、输出流监听与进程树收敛；
+ * - 内部可信工具执行保持标准非阻塞异步。
+ */
+export declare function runPackageManager(manager: "npm" | "bun", args: readonly string[], options?: RunPackageManagerOptions): Promise<CommandExecutionResult>;

package/dist/project/package-manager.js

@@ -0,0 +1,224 @@
+import { realpathSync, statSync } from "node:fs";
+import { basename, dirname, extname, isAbsolute, join, resolve } from "node:path";
+import { ActionDockError, DEPENDENCY_INSTALL_FAILED, } from "../errors.js";
+import { executeCommand, } from "../process/command-executor.js";
+function isFile(filePath) {
+    try {
+        return statSync(filePath).isFile();
+    }
+    catch (error) {
+        if (error?.code === "ENOENT" || error?.code === "ENOTDIR") {
+            return false;
+        }
+        throw new ActionDockError(DEPENDENCY_INSTALL_FAILED, `Failed to inspect file at '${filePath}': ${error?.message ?? String(error)}`, { stage: "resolve", path: filePath, cause: error });
+    }
+}
+/**
+ * 规范化 Windows 环境变量字典。
+ *
+ * 核心契约：
+ * - 保持与 Node.js Windows child_process 相同的字典序排序与大小写去重语义；
+ * - 先由字典序首位键决定该大小写分组的最终获胜键；
+ * - 若获胜键的值为 undefined，则该变量视为未设置（同组后续键不可顶替）；
+ * - 仅保留值非 undefined 的有效键值对，杜绝后续执行器剔除 undefined 时残留失效同名键。
+ */
+function normalizeWindowsEnvironment(env) {
+    const keys = [];
+    for (const key in env) {
+        keys.push(key);
+    }
+    keys.sort();
+    const seenUpper = new Set();
+    const normalized = {};
+    for (const key of keys) {
+        const upper = key.toUpperCase();
+        if (seenUpper.has(upper)) {
+            continue;
+        }
+        seenUpper.add(upper);
+        const value = env[key];
+        if (value !== undefined) {
+            normalized[key] = value;
+        }
+    }
+    return normalized;
+}
+function getNormalizedEnvValue(env, targetKey) {
+    const targetUpper = targetKey.toUpperCase();
+    for (const [key, value] of Object.entries(env)) {
+        if (key.toUpperCase() === targetUpper) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function resolvePathExt(rawPathExt) {
+    if (!rawPathExt || rawPathExt.trim() === "") {
+        return [".COM", ".EXE", ".BAT", ".CMD"];
+    }
+    const list = rawPathExt
+        .split(";")
+        .map((e) => e.trim())
+        .filter(Boolean)
+        .map((e) => (e.startsWith(".") ? e : `.${e}`));
+    return list.length > 0 ? list : [".COM", ".EXE", ".BAT", ".CMD"];
+}
+function findMatchingExecutable(dir, manager, ext) {
+    // Windows 文件系统大小写不敏感：优先尝试小写拼写，使返回路径与磁盘上常见的小写文件名一致；
+    // 再回退 PATHEXT 原样与全大写拼写，仅影响返回路径的外现大小写，不改变命中顺序。
+    const lowerCandidate = join(dir, `${manager}${ext.toLowerCase()}`);
+    if (isFile(lowerCandidate)) {
+        return lowerCandidate;
+    }
+    const directCandidate = join(dir, `${manager}${ext}`);
+    if (directCandidate !== lowerCandidate && isFile(directCandidate)) {
+        return directCandidate;
+    }
+    const upperCandidate = join(dir, `${manager}${ext.toUpperCase()}`);
+    if (upperCandidate !== directCandidate &&
+        upperCandidate !== lowerCandidate &&
+        isFile(upperCandidate)) {
+        return upperCandidate;
+    }
+    return null;
+}
+function findNpmCliInDirectory(targetDir) {
+    const candidates = [
+        join(targetDir, "node_modules", "npm", "bin", "npm-cli.js"),
+        join(targetDir, "..", "node_modules", "npm", "bin", "npm-cli.js"),
+        join(targetDir, "..", "lib", "node_modules", "npm", "bin", "npm-cli.js"),
+        join(targetDir, "..", "npm", "bin", "npm-cli.js"),
+        join(targetDir, "npm", "bin", "npm-cli.js"),
+    ];
+    for (const candidate of candidates) {
+        if (isFile(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * 解析包管理器在目标平台上的确定性启动规范。
+ *
+ * 核心设计契约：
+ * - 保持参数边界与数组结构（保留 argv 边界，路径中的空格、引号、&、% 与 ! 原样保留）；
+ * - shell: false 语义，杜绝命令注入与 Node.js DEP0190 警告；
+ * - POSIX 平台保留正常 PATH 命令执行，兼容已有 fake npm 脚本；
+ * - Windows 平台查找遵循 PATH 目录顺序及 PATHEXT 后缀顺序（默认 .COM;.EXE;.BAT;.CMD）；
+ * - PATH 所选工具为唯一事实源，显式传入 env 必须被尊重，绝不从 process.env 漏回其它 PATH；
+ * - Windows 平台原生程序（.exe, .com）直接保留该可执行文件与原数组 args，无需绕过原生版本管理器；
+ * - Windows 平台 Bun 仅支持原生程序，遇到 cmd/bat 包装脚本明确报错，无工具时严禁退回名称；
+ * - Windows 平台 npm.cmd/bat：优先其真实目录布局定位标准 npm-cli.js，由 execPath (Node) 无 shell 启动；
+ * - 仅支持标准可定位 CLI 布局，非标准 wrapper 显式报错，无有效 PATH 工具显式报错。
+ */
+export function resolvePackageManagerInvocation(manager, args, options) {
+    const platform = options?.platform ?? process.platform;
+    const execPath = options?.execPath ?? process.execPath;
+    if (platform !== "win32") {
+        return {
+            executable: manager,
+            args: [...args],
+        };
+    }
+    const envSource = options?.env !== undefined ? options.env : process.env;
+    const effectiveEnv = normalizeWindowsEnvironment(envSource);
+    const rawPath = getNormalizedEnvValue(effectiveEnv, "PATH") ?? "";
+    const rawPathExt = getNormalizedEnvValue(effectiveEnv, "PATHEXT");
+    const pathExtList = resolvePathExt(rawPathExt);
+    const cwd = options?.cwd ?? process.cwd();
+    const pathDirs = [];
+    for (const rawEntry of rawPath.split(";")) {
+        let entry = rawEntry.trim();
+        if (!entry)
+            continue;
+        if (entry.startsWith('"') && entry.endsWith('"') && entry.length >= 2) {
+            entry = entry.slice(1, -1).trim();
+        }
+        if (!entry)
+            continue;
+        pathDirs.push(isAbsolute(entry) ? entry : resolve(cwd, entry));
+    }
+    let selectedPath = null;
+    for (const dir of pathDirs) {
+        for (const ext of pathExtList) {
+            const match = findMatchingExecutable(dir, manager, ext);
+            if (match) {
+                selectedPath = match;
+                break;
+            }
+        }
+        if (selectedPath) {
+            break;
+        }
+    }
+    if (!selectedPath) {
+        throw new ActionDockError(DEPENDENCY_INSTALL_FAILED, `Cannot locate ${manager} on Windows: '${manager}' was not found in PATH (${rawPath || "empty"}).`, { stage: "resolve", manager, path: rawPath });
+    }
+    const selectedExt = extname(selectedPath).toLowerCase();
+    const isNative = selectedExt === ".exe" || selectedExt === ".com";
+    if (isNative) {
+        return {
+            executable: selectedPath,
+            args: [...args],
+        };
+    }
+    if (manager === "bun") {
+        throw new ActionDockError(DEPENDENCY_INSTALL_FAILED, `Unsupported bun wrapper at '${selectedPath}': only native executable (.exe, .com) is supported on Windows. Non-standard wrappers cannot be executed without shell.`, { stage: "resolve", manager: "bun", path: selectedPath });
+    }
+    // Windows npm 非原生分支仅支持 .cmd 与 .bat
+    if (selectedExt !== ".cmd" && selectedExt !== ".bat") {
+        throw new ActionDockError(DEPENDENCY_INSTALL_FAILED, `Unsupported npm wrapper extension '${selectedExt}' at '${selectedPath}': only native binaries (.exe, .com) or standard Windows batch scripts (.cmd, .bat) are supported.`, { stage: "resolve", manager: "npm", path: selectedPath });
+    }
+    // Windows npm .cmd / .bat wrapper 解析
+    let realWrapperPath;
+    try {
+        realWrapperPath = realpathSync(selectedPath);
+    }
+    catch (error) {
+        throw new ActionDockError(DEPENDENCY_INSTALL_FAILED, `Failed to resolve realpath for npm wrapper at '${selectedPath}': ${error?.message ?? String(error)}`, { stage: "resolve", manager: "npm", path: selectedPath, cause: error });
+    }
+    let foundCli = null;
+    if (basename(realWrapperPath).toLowerCase() === "npm-cli.js" && isFile(realWrapperPath)) {
+        foundCli = realWrapperPath;
+    }
+    if (!foundCli) {
+        const realDir = dirname(realWrapperPath);
+        foundCli = findNpmCliInDirectory(realDir);
+    }
+    if (!foundCli) {
+        throw new ActionDockError(DEPENDENCY_INSTALL_FAILED, `Unsupported npm wrapper at '${selectedPath}': cannot locate npm-cli.js in standard installation layout. Non-standard npm wrappers cannot be executed without shell.`, { stage: "resolve", manager: "npm", path: selectedPath });
+    }
+    return {
+        executable: execPath,
+        args: [foundCli, ...args],
+    };
+}
+/**
+ * 统一执行包管理器命令。
+ *
+ * 运维规范：
+ * - 结合 resolvePackageManagerInvocation 完成无 shell 真实命令定位；
+ * - 通过统一 ProcessDriver 底座执行命令，保留取消、超时、输出流监听与进程树收敛；
+ * - 内部可信工具执行保持标准非阻塞异步。
+ */
+export async function runPackageManager(manager, args, options) {
+    const platform = options?.platform ?? process.platform;
+    const normalizedEnv = platform === "win32" && options?.env !== undefined
+        ? normalizeWindowsEnvironment(options.env)
+        : options?.env;
+    const invocation = resolvePackageManagerInvocation(manager, args, {
+        cwd: options?.cwd,
+        env: normalizedEnv,
+        platform: options?.platform,
+        execPath: options?.execPath,
+    });
+    return executeCommand(invocation.executable, invocation.args, {
+        cwd: options?.cwd,
+        env: normalizedEnv,
+        signal: options?.signal,
+        timeoutMs: options?.timeoutMs,
+        maxOutputBytes: options?.maxOutputBytes,
+        onOutput: options?.onOutput,
+        driver: options?.driver,
+    });
+}

package/dist/project/preparation.d.ts

@@ -0,0 +1,8 @@
+import type { LocalPackagePreparer } from "../invocation/types.js";
+import { type EnsureProjectDependenciesOptions } from "./dependencies.js";
+/**
+ * 创建单个宿主使用的本地包准备器。
+ * 包实例独立缓存就绪状态；同一根调用的同一安装目录共享在途任务。
+ * 共享成功后，各包仍须通过自己的依赖检查；失败不重试、不缓存。
+ */
+export declare function createLocalPackagePreparer(options?: Omit<EnsureProjectDependenciesOptions, "signal">): LocalPackagePreparer;

package/dist/project/preparation.js

@@ -0,0 +1,130 @@
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { ActionDockError, ACTION_CANCELLED, DEPENDENCIES_NOT_READY } from "../errors.js";
+import { ensureProjectDependencies, resolveInstallRoot, } from "./dependencies.js";
+function cancellationError(reason) {
+    return new ActionDockError(ACTION_CANCELLED, reason instanceof Error ? reason.message : String(reason ?? "Package preparation was cancelled"), { cause: reason });
+}
+function isCancellation(error) {
+    return (error instanceof ActionDockError && error.code === ACTION_CANCELLED) ||
+        (error instanceof Error && error.name === "AbortError");
+}
+/**
+ * 创建单个宿主使用的本地包准备器。
+ * 包实例独立缓存就绪状态；同一根调用的同一安装目录共享在途任务。
+ * 共享成功后，各包仍须通过自己的依赖检查；失败不重试、不缓存。
+ */
+export function createLocalPackagePreparer(options = {}) {
+    const readyCache = new Set();
+    const canonicalRootCache = new Map();
+    const inFlightTasks = new Map();
+    function getPackageInstanceKey(target) {
+        let canonicalRoot = canonicalRootCache.get(target.packageRoot);
+        if (!canonicalRoot) {
+            const path = resolve(target.packageRoot);
+            try {
+                canonicalRoot = realpathSync(path);
+                canonicalRootCache.set(target.packageRoot, canonicalRoot);
+            }
+            catch (error) {
+                throw new ActionDockError(DEPENDENCIES_NOT_READY, `Cannot resolve project directory '${path}': ${error?.message || String(error)}`, { path, cause: error });
+            }
+        }
+        return JSON.stringify([
+            target.identity.id,
+            target.identity.instanceId,
+            target.identity.generation,
+            canonicalRoot,
+        ]);
+    }
+    async function waitForTask(task, signal) {
+        let released = false;
+        const releaseWaiter = () => {
+            if (!released) {
+                released = true;
+                task.waiters--;
+            }
+            return task.waiters;
+        };
+        const stopIfUnused = async () => {
+            if (releaseWaiter() !== 0 || task.settled)
+                return;
+            task.controller.abort(signal.reason);
+            try {
+                await task.promise;
+            }
+            catch (error) {
+                if (!isCancellation(error))
+                    throw error;
+            }
+        };
+        if (signal.aborted) {
+            await stopIfUnused();
+            throw cancellationError(signal.reason);
+        }
+        let onAbort;
+        const aborted = new Promise((_resolve, reject) => {
+            onAbort = () => {
+                void stopIfUnused().then(() => reject(cancellationError(signal.reason)), reject);
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
+            if (signal.aborted)
+                onAbort();
+        });
+        try {
+            await Promise.race([task.promise, aborted]);
+            if (signal.aborted)
+                throw cancellationError(signal.reason);
+        }
+        finally {
+            releaseWaiter();
+            signal.removeEventListener("abort", onAbort);
+        }
+    }
+    return async function prepareLocalPackage(target, context) {
+        if (context.signal.aborted)
+            throw cancellationError(context.signal.reason);
+        if (!target.packageRoot)
+            return;
+        const instanceKey = getPackageInstanceKey(target);
+        if (readyCache.has(instanceKey))
+            return;
+        const root = resolveInstallRoot(target.packageRoot);
+        if (root.skip || !root.installRoot) {
+            if (context.signal.aborted)
+                throw cancellationError(context.signal.reason);
+            readyCache.add(instanceKey);
+            return;
+        }
+        const flightKey = JSON.stringify([context.rootRunId, root.installRoot]);
+        while (!readyCache.has(instanceKey)) {
+            if (context.signal.aborted)
+                throw cancellationError(context.signal.reason);
+            const existing = inFlightTasks.get(flightKey);
+            if (existing) {
+                existing.waiters++;
+                await waitForTask(existing, context.signal);
+                continue;
+            }
+            const controller = new AbortController();
+            let task;
+            // 先登记任务与等待者，再开始底层检查，兼容同步完成的测试驱动。
+            const promise = Promise.resolve().then(async () => {
+                try {
+                    if (controller.signal.aborted)
+                        throw cancellationError(controller.signal.reason);
+                    await ensureProjectDependencies(target.packageRoot, { ...options, signal: controller.signal });
+                    readyCache.add(instanceKey);
+                }
+                finally {
+                    task.settled = true;
+                    if (inFlightTasks.get(flightKey) === task)
+                        inFlightTasks.delete(flightKey);
+                }
+            });
+            task = { controller, promise, waiters: 1, settled: false };
+            inFlightTasks.set(flightKey, task);
+            await waitForTask(task, context.signal);
+        }
+    };
+}

package/dist/project/transactions.d.ts

@@ -45,7 +45,9 @@ export declare function acquireProjectLock(projectRoot: string, options?: {
 /**
  * 依据恢复后的锁文件异步执行禁用安装脚本的冻结安装，使 node_modules 与声明重新一致。
  */
-export declare function runFrozenInstall(projectRoot: string): Promise<void>;
+export declare function runFrozenInstall(projectRoot: string, options?: {
+    signal?: AbortSignal;
+} | AbortSignal): Promise<void>;
 /**
  * 检查项目是否存在未完成提交的悬空事务。
  */
@@ -60,4 +62,6 @@ export declare function beginTransaction(projectRoot: string, description?: stri
  */
 export declare function recoverPendingTransactions(projectRoot: string, options?: {
     frozenInstall?: boolean;
+    allowInstall?: boolean;
+    signal?: AbortSignal;
 }): Promise<string[]>;

package/dist/project/transactions.js

@@ -1,4 +1,3 @@
-import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, unlinkSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
@@ -7,6 +6,7 @@ import { isProcessAlive } from "../utils/index.js";
 import { ActionDockError, PROJECT_BUSY, PROJECT_RECOVERY_REQUIRED } from "../errors.js";
 import { LOCKFILE_NAME } from "./lockfile.js";
 import { MANIFEST_FILE_NAME } from "./manifest.js";
+import { runPackageManager } from "./package-manager.js";
 export const SNAPSHOT_TRACKED_FILES = [
     "package.json",
     MANIFEST_FILE_NAME,
@@ -76,58 +76,12 @@ export function acquireProjectLock(projectRoot, options = {}) {
         handle.release();
     };
 }
-/**
- * 异步执行子进程并收集退出状态与输出流。
- *
- * 异步化取舍说明：
- * - 避免在事务回滚与恢复链路中执行同步阻塞调用导致事件循环停顿；
- * - Windows 兼容性保留：npm 在 Windows 上是 .cmd 批处理脚本，启用 shell 以防直接调用抛错；
- * - 命令与参数由系统内部锁文件逻辑决定，不接受外部未受控入参。
- */
-function execSubprocessAsync(command, args, options) {
-    return new Promise((resolve, reject) => {
-        try {
-            const proc = spawn(command, args, {
-                cwd: options?.cwd,
-                stdio: "pipe",
-                shell: process.platform === "win32",
-                env: options?.env,
-            });
-            let stdout = "";
-            let stderr = "";
-            if (proc.stdout) {
-                proc.stdout.on("data", (chunk) => {
-                    stdout += chunk.toString();
-                });
-            }
-            if (proc.stderr) {
-                proc.stderr.on("data", (chunk) => {
-                    stderr += chunk.toString();
-                });
-            }
-            let settled = false;
-            proc.on("error", (err) => {
-                if (!settled) {
-                    settled = true;
-                    reject(err);
-                }
-            });
-            proc.on("close", (status) => {
-                if (!settled) {
-                    settled = true;
-                    resolve({ status, stdout, stderr });
-                }
-            });
-        }
-        catch (err) {
-            reject(err);
-        }
-    });
-}
 /**
  * 依据恢复后的锁文件异步执行禁用安装脚本的冻结安装，使 node_modules 与声明重新一致。
  */
-export async function runFrozenInstall(projectRoot) {
+export async function runFrozenInstall(projectRoot, options) {
+    const signal = options instanceof AbortSignal ? options : options?.signal;
+    signal?.throwIfAborted();
     if (process.env.ACTIONDOCK_AUTO_INSTALL === "false") {
         return;
     }
@@ -137,45 +91,41 @@ export async function runFrozenInstall(projectRoot) {
     }
     const hasBunLock = existsSync(join(projectRoot, "bun.lock")) || existsSync(join(projectRoot, "bun.lockb"));
     const hasNpmLock = existsSync(join(projectRoot, "package-lock.json")) || existsSync(join(projectRoot, "npm-shrinkwrap.json"));
-    let cmd = "npm";
+    let pm = "npm";
     let args = ["install", "--ignore-scripts"];
     if (hasBunLock) {
-        cmd = "bun";
+        pm = "bun";
         args = ["install", "--frozen-lockfile", "--ignore-scripts"];
     }
     else if (hasNpmLock) {
-        cmd = "npm";
+        pm = "npm";
         args = ["ci", "--ignore-scripts"];
     }
-    try {
-        const check = await execSubprocessAsync(cmd, ["--version"]);
-        if (check.status !== 0) {
-            cmd = "npm";
-            args = ["install", "--ignore-scripts"];
-        }
-    }
-    catch {
-        cmd = "npm";
-        args = ["install", "--ignore-scripts"];
-    }
+    const env = {
+        ...process.env,
+        npm_config_allow_scripts: "",
+        NPM_CONFIG_ALLOW_SCRIPTS: "",
+        npm_config_ignore_scripts: "true",
+        NPM_CONFIG_IGNORE_SCRIPTS: "true",
+    };
     let proc;
     try {
-        proc = await execSubprocessAsync(cmd, args, {
+        proc = await runPackageManager(pm, args, {
             cwd: projectRoot,
-            env: {
-                ...process.env,
-                npm_config_allow_scripts: "",
-                NPM_CONFIG_ALLOW_SCRIPTS: "",
-            },
+            env,
+            signal,
         });
     }
     catch (err) {
+        if (signal?.aborted || err?.name === "AbortError") {
+            throw err;
+        }
         const errorMsg = err?.message || "Unknown error";
-        throw new ActionDockError(PROJECT_RECOVERY_REQUIRED, `PROJECT_RECOVERY_REQUIRED: Frozen install failed during recovery in ${projectRoot}: ${errorMsg}`);
+        throw new ActionDockError(PROJECT_RECOVERY_REQUIRED, `PROJECT_RECOVERY_REQUIRED: Frozen install failed during recovery in ${projectRoot}: ${errorMsg}`, { stage: "recovery-install", projectRoot, manager: pm, cause: err });
     }
     if (proc.status !== 0) {
-        const errorMsg = proc.stderr || proc.stdout || "Unknown error";
-        throw new ActionDockError(PROJECT_RECOVERY_REQUIRED, `PROJECT_RECOVERY_REQUIRED: Frozen install failed during recovery in ${projectRoot}: ${errorMsg}`);
+        const errorMsg = (proc.stderr || proc.stdout || "Unknown error").trim();
+        throw new ActionDockError(PROJECT_RECOVERY_REQUIRED, `PROJECT_RECOVERY_REQUIRED: Frozen install failed during recovery in ${projectRoot}: ${errorMsg}`, { stage: "recovery-install", projectRoot, manager: pm, status: proc.status, stderr: proc.stderr, stdout: proc.stdout });
     }
 }
 /**
@@ -214,6 +164,9 @@ export function hasPendingTransactions(projectRoot) {
 export async function beginTransaction(projectRoot, description) {
     const releaseLock = acquireProjectLock(projectRoot);
     try {
+        if (hasPendingTransactions(projectRoot)) {
+            throw new ActionDockError(PROJECT_RECOVERY_REQUIRED, `PROJECT_RECOVERY_REQUIRED: Cannot begin transaction in '${projectRoot}': pending transaction exists. Recovery is required.`);
+        }
         const txId = `${Date.now()}-${randomUUID().slice(0, 8)}`;
         const txDir = join(projectRoot, ".actiondock", "transactions", txId);
         const snapshotDir = join(txDir, "snapshot");
@@ -300,6 +253,7 @@ export async function beginTransaction(projectRoot, description) {
  * 依据事务日志恢复所有待恢复的悬空事务快照，并在成功后执行冻结安装。
  */
 export async function recoverPendingTransactions(projectRoot, options) {
+    options?.signal?.throwIfAborted();
     const txBaseDir = join(projectRoot, ".actiondock", "transactions");
     if (!existsSync(txBaseDir)) {
         return [];
@@ -315,6 +269,7 @@ export async function recoverPendingTransactions(projectRoot, options) {
         throw err;
     }
     try {
+        options?.signal?.throwIfAborted();
         const recoveredIds = [];
         const entries = readdirSync(txBaseDir);
         for (const entry of entries) {
@@ -330,6 +285,11 @@ export async function recoverPendingTransactions(projectRoot, options) {
                 continue;
             }
             if (meta.status === "pending") {
+                options?.signal?.throwIfAborted();
+                if (options?.frozenInstall !== false &&
+                    (options?.allowInstall === false || process.env.ACTIONDOCK_AUTO_INSTALL === "false")) {
+                    throw new ActionDockError(PROJECT_RECOVERY_REQUIRED, `PROJECT_RECOVERY_REQUIRED: Project at '${projectRoot}' has pending transactions requiring recovery install, but installation is disabled (--no-install or ACTIONDOCK_AUTO_INSTALL=false).`);
+                }
                 const snapshotDir = join(txDir, "snapshot");
                 for (const rec of meta.files) {
                     const targetPath = join(projectRoot, rec.name);
@@ -346,7 +306,7 @@ export async function recoverPendingTransactions(projectRoot, options) {
                     }
                 }
                 if (options?.frozenInstall !== false) {
-                    await runFrozenInstall(projectRoot);
+                    await runFrozenInstall(projectRoot, { signal: options?.signal });
                 }
                 meta.status = "rolled_back";
                 try {
@@ -362,6 +322,6 @@ export async function recoverPendingTransactions(projectRoot, options) {
         return recoveredIds;
     }
     finally {
-        releaseLock();
+        releaseLock?.();
     }
 }