@actiondock/core 2.20.0 → 2.21.0

package/dist/errors.d.ts

@@ -71,6 +71,10 @@ export declare const CAPABILITY_UNAVAILABLE = "CAPABILITY_UNAVAILABLE";
 export declare const STATE_KEY_NOT_FOUND = "STATE_KEY_NOT_FOUND";
 /** SQLite 数据库忙或锁定 */
 export declare const STORAGE_BUSY = "STORAGE_BUSY";
+/** 所需生产依赖未就绪且当前环境不允许或不满足自动首装条件 */
+export declare const DEPENDENCIES_NOT_READY = "DEPENDENCIES_NOT_READY";
+/** 自动依赖安装进程启动失败、超时或非零退出 */
+export declare const DEPENDENCY_INSTALL_FAILED = "DEPENDENCY_INSTALL_FAILED";
 /** 工程事务锁被其他活跃进程持有 */
 export declare const PROJECT_BUSY = "PROJECT_BUSY";
 /** 工程存在未恢复的崩溃事务，需要执行恢复流程 */
@@ -300,6 +304,12 @@ export declare const PROJECT_CONFIG_NOT_FOUND = "PROJECT_CONFIG_NOT_FOUND";
 export declare const MANIFEST_LOAD_FAILED = "MANIFEST_LOAD_FAILED";
 /** 配置项数据值不符合声明的模式规范 */
 export declare const CONFIG_VALUE_INVALID = "CONFIG_VALUE_INVALID";
+/** 配置加密密钥缺失、无效或与存储域身份不符等加密配置错误 */
+export declare const CONFIG_ENCRYPTION_ERROR = "CONFIG_ENCRYPTION_ERROR";
+/** 配置密文解密失败（信封格式非法、版本未知、密钥身份不符或认证校验失败） */
+export declare const CONFIG_DECRYPT_FAILED = "CONFIG_DECRYPT_FAILED";
+/** 配置加密与解密错误按结构化错误码识别，跨模块副本也不得吞没或覆盖。 */
+export declare function isConfigEncryptionError(error: unknown): boolean;
 /** 动作标识符不符合命名规范 */
 export declare const INVALID_ACTION_ID = "INVALID_ACTION_ID";
 /** 规程标识符不符合命名规范 */
@@ -350,7 +360,7 @@ export declare function resolveExecutionHint(targetRef: string, error?: {
 /**
  * 集中定义的标准结构化错误码联合类型。
  */
-export type ErrorCode = typeof PACKAGE_NOT_FOUND | typeof ACTION_PACKAGE_VERSION_CONFLICT | typeof ACTION_NOT_FOUND | typeof ACTION_LOAD_FAILED | typeof ACTION_FAILED | typeof ACTION_TIMEOUT | typeof ACTION_CANCELLED | typeof INPUT_VALIDATION_FAILED | typeof OUTPUT_VALIDATION_FAILED | typeof INPUT_NOT_JSON | typeof OUTPUT_NOT_JSON | typeof ACTION_SUBRUN_LIMIT | typeof ACTION_CALL_CYCLE | typeof UNDECLARED_ACTION_DEPENDENCY | typeof INVALID_ACTION_REF | typeof IDEMPOTENCY_CONFLICT | typeof EXECUTION_FAILED | typeof UNHANDLED_EXECUTION_ERROR | typeof RUN_REPOSITORY_UNAVAILABLE | typeof RUN_PERSISTENCE_FAILED | typeof STANDALONE_ASYNC_UNSUPPORTED | typeof INVOCATION_UNSUPPORTED | typeof HOST_PROCESS_EXITED | typeof EXECUTION_ABORTED | typeof TIMEOUT | typeof SERVICE_CLOSED | typeof NETWORK_ERROR | typeof INSECURE_TRANSPORT | typeof REMOTE_REQUEST_FAILED | typeof REMOTE_STREAM_UNAVAILABLE | typeof CAPABILITY_UNAVAILABLE | typeof STATE_KEY_NOT_FOUND | typeof STORAGE_BUSY | typeof PROJECT_BUSY | typeof PROJECT_RECOVERY_REQUIRED | typeof EVENT_BACKPRESSURE_LIMIT | typeof EVENT_CURSOR_EXPIRED | typeof PROCESS_OUTPUT_LIMIT | typeof PROCESS_SPAWN_ERROR | typeof PROCESS_CANCELLED | typeof PROCESS_TIMEOUT | typeof UNAUTHORIZED | typeof NOT_FOUND | typeof SERVER_ERROR | typeof BAD_REQUEST | typeof PACKAGE_FORBIDDEN | typeof ACTION_FORBIDDEN | typeof PLAYBOOK_NOT_FOUND | typeof REQUEST_TOO_LARGE | typeof ACTION_START_FAILED | typeof ACTION_EXECUTION_ERROR | typeof ACTIONS_LIST_ERROR | typeof PLAYBOOKS_LIST_ERROR | typeof RUNS_LIST_ERROR | typeof RUNS_CLEAR_ERROR | typeof INFO_ERROR | typeof PACKAGES_INFO_ERROR | typeof DOCTOR_ERROR | typeof RUN_INTERRUPTED | typeof CONFIG_ENV_ERROR | typeof CONFIG_LIST_ERROR | typeof CONFIG_SET_ERROR | typeof CONFIG_DELETE_ERROR | typeof STATE_LIST_ERROR | typeof STATE_CLEAR_ERROR | typeof STATE_KEY_ERROR | typeof DATA_DIR_IN_USE | typeof DATA_DIR_RECOVERY_REQUIRED | typeof UNSUPPORTED_STORAGE_SCHEMA | typeof STORED_ERROR_DECODE_FAILED | typeof PROCESS_FAILED | typeof GENERATED_TYPES_OUTDATED | typeof PROTOCOL_UNSUPPORTED | typeof SERVICE_RESULT_UNKNOWN | typeof MCP_TOOL_NAME_COLLISION | typeof ACCESS_DENIED | typeof UNSUPPORTED_CAPABILITY | typeof CONTROL_BUSY | typeof CONTROL_EXPIRED | typeof CONTROL_REVOKED | typeof PROCESS_QUARANTINED | typeof PROCESS_LOST | typeof REQUEST_CONFLICT | typeof INPUT_OUTCOME_UNKNOWN | typeof OUTPUT_GAP | typeof OUTPUT_UNAVAILABLE | typeof INVALID_CURSOR | typeof QUEUE_FULL | typeof QUOTA_EXCEEDED | typeof INPUT_CLOSED | typeof INVALID_FLAT_ARGUMENT | typeof INVALID_JSON | typeof INVALID_JSON_LITERAL | typeof INPUT_PATH_CONFLICT | typeof FLAT_INPUT_LIMIT_EXCEEDED | typeof INPUT_LIMIT_EXCEEDED | typeof INPUT_POLICY_VIOLATION | typeof INPUT_CONFLICT | typeof INPUT_FILE_NOT_FOUND | typeof INPUT_FILE_READ_FAILED | typeof INVALID_ARGUMENT | typeof PACKAGE_NOT_ALLOWED | typeof INVALID_PACKAGE_ID | typeof PATH_TRAVERSAL | typeof AMBIGUOUS_STATE_KEY | typeof RUN_NOT_FOUND | typeof RUN_ALREADY_FINISHED | typeof IPC_ERROR | typeof SERVICE_ERROR | typeof PROFILE_NOT_FOUND | typeof LOCKFILE_READ_FAILED | typeof LOCKFILE_CORRUPTED | typeof LOCKFILE_INVALID | typeof UNSUPPORTED_LOCKFILE_VERSION | typeof MANIFEST_READ_FAILED | typeof MANIFEST_CORRUPTED | typeof MANIFEST_INVALID | typeof UNSUPPORTED_MANIFEST_SCHEMA | typeof MANIFEST_NOT_FOUND | typeof MANIFEST_DIGEST_MISMATCH | typeof REGISTRY_CORRUPTED | typeof ASYNC_TRANSACTION_UNSUPPORTED | typeof STORAGE_CLOSED | typeof PACKAGE_ID_CONFLICT | typeof INVALID_PATH | typeof STORAGE_INIT_FAILED | typeof INVALID_STATE | typeof PROCESS_NOT_FOUND | typeof MODULE_RESOLVE_FAILED | typeof EXECUTION_CONCURRENCY_LIMIT | typeof PROJECT_CONFIG_NOT_FOUND | typeof MANIFEST_LOAD_FAILED | typeof CONFIG_VALUE_INVALID | typeof INVALID_ACTION_ID | typeof INVALID_PLAYBOOK_ID | typeof PROJECT_ROOT_NOT_FOUND;
+export type ErrorCode = typeof PACKAGE_NOT_FOUND | typeof ACTION_PACKAGE_VERSION_CONFLICT | typeof ACTION_NOT_FOUND | typeof ACTION_LOAD_FAILED | typeof ACTION_FAILED | typeof ACTION_TIMEOUT | typeof ACTION_CANCELLED | typeof INPUT_VALIDATION_FAILED | typeof OUTPUT_VALIDATION_FAILED | typeof INPUT_NOT_JSON | typeof OUTPUT_NOT_JSON | typeof ACTION_SUBRUN_LIMIT | typeof ACTION_CALL_CYCLE | typeof UNDECLARED_ACTION_DEPENDENCY | typeof INVALID_ACTION_REF | typeof IDEMPOTENCY_CONFLICT | typeof EXECUTION_FAILED | typeof UNHANDLED_EXECUTION_ERROR | typeof RUN_REPOSITORY_UNAVAILABLE | typeof RUN_PERSISTENCE_FAILED | typeof STANDALONE_ASYNC_UNSUPPORTED | typeof INVOCATION_UNSUPPORTED | typeof HOST_PROCESS_EXITED | typeof EXECUTION_ABORTED | typeof TIMEOUT | typeof SERVICE_CLOSED | typeof NETWORK_ERROR | typeof INSECURE_TRANSPORT | typeof REMOTE_REQUEST_FAILED | typeof REMOTE_STREAM_UNAVAILABLE | typeof CAPABILITY_UNAVAILABLE | typeof STATE_KEY_NOT_FOUND | typeof STORAGE_BUSY | typeof DEPENDENCIES_NOT_READY | typeof DEPENDENCY_INSTALL_FAILED | typeof PROJECT_BUSY | typeof PROJECT_RECOVERY_REQUIRED | typeof EVENT_BACKPRESSURE_LIMIT | typeof EVENT_CURSOR_EXPIRED | typeof PROCESS_OUTPUT_LIMIT | typeof PROCESS_SPAWN_ERROR | typeof PROCESS_CANCELLED | typeof PROCESS_TIMEOUT | typeof UNAUTHORIZED | typeof NOT_FOUND | typeof SERVER_ERROR | typeof BAD_REQUEST | typeof PACKAGE_FORBIDDEN | typeof ACTION_FORBIDDEN | typeof PLAYBOOK_NOT_FOUND | typeof REQUEST_TOO_LARGE | typeof ACTION_START_FAILED | typeof ACTION_EXECUTION_ERROR | typeof ACTIONS_LIST_ERROR | typeof PLAYBOOKS_LIST_ERROR | typeof RUNS_LIST_ERROR | typeof RUNS_CLEAR_ERROR | typeof INFO_ERROR | typeof PACKAGES_INFO_ERROR | typeof DOCTOR_ERROR | typeof RUN_INTERRUPTED | typeof CONFIG_ENV_ERROR | typeof CONFIG_LIST_ERROR | typeof CONFIG_SET_ERROR | typeof CONFIG_DELETE_ERROR | typeof STATE_LIST_ERROR | typeof STATE_CLEAR_ERROR | typeof STATE_KEY_ERROR | typeof DATA_DIR_IN_USE | typeof DATA_DIR_RECOVERY_REQUIRED | typeof UNSUPPORTED_STORAGE_SCHEMA | typeof STORED_ERROR_DECODE_FAILED | typeof PROCESS_FAILED | typeof GENERATED_TYPES_OUTDATED | typeof PROTOCOL_UNSUPPORTED | typeof SERVICE_RESULT_UNKNOWN | typeof MCP_TOOL_NAME_COLLISION | typeof ACCESS_DENIED | typeof UNSUPPORTED_CAPABILITY | typeof CONTROL_BUSY | typeof CONTROL_EXPIRED | typeof CONTROL_REVOKED | typeof PROCESS_QUARANTINED | typeof PROCESS_LOST | typeof REQUEST_CONFLICT | typeof INPUT_OUTCOME_UNKNOWN | typeof OUTPUT_GAP | typeof OUTPUT_UNAVAILABLE | typeof INVALID_CURSOR | typeof QUEUE_FULL | typeof QUOTA_EXCEEDED | typeof INPUT_CLOSED | typeof INVALID_FLAT_ARGUMENT | typeof INVALID_JSON | typeof INVALID_JSON_LITERAL | typeof INPUT_PATH_CONFLICT | typeof FLAT_INPUT_LIMIT_EXCEEDED | typeof INPUT_LIMIT_EXCEEDED | typeof INPUT_POLICY_VIOLATION | typeof INPUT_CONFLICT | typeof INPUT_FILE_NOT_FOUND | typeof INPUT_FILE_READ_FAILED | typeof INVALID_ARGUMENT | typeof PACKAGE_NOT_ALLOWED | typeof INVALID_PACKAGE_ID | typeof PATH_TRAVERSAL | typeof AMBIGUOUS_STATE_KEY | typeof RUN_NOT_FOUND | typeof RUN_ALREADY_FINISHED | typeof IPC_ERROR | typeof SERVICE_ERROR | typeof PROFILE_NOT_FOUND | typeof LOCKFILE_READ_FAILED | typeof LOCKFILE_CORRUPTED | typeof LOCKFILE_INVALID | typeof UNSUPPORTED_LOCKFILE_VERSION | typeof MANIFEST_READ_FAILED | typeof MANIFEST_CORRUPTED | typeof MANIFEST_INVALID | typeof UNSUPPORTED_MANIFEST_SCHEMA | typeof MANIFEST_NOT_FOUND | typeof MANIFEST_DIGEST_MISMATCH | typeof REGISTRY_CORRUPTED | typeof ASYNC_TRANSACTION_UNSUPPORTED | typeof STORAGE_CLOSED | typeof PACKAGE_ID_CONFLICT | typeof INVALID_PATH | typeof STORAGE_INIT_FAILED | typeof INVALID_STATE | typeof PROCESS_NOT_FOUND | typeof MODULE_RESOLVE_FAILED | typeof EXECUTION_CONCURRENCY_LIMIT | typeof PROJECT_CONFIG_NOT_FOUND | typeof MANIFEST_LOAD_FAILED | typeof CONFIG_VALUE_INVALID | typeof CONFIG_ENCRYPTION_ERROR | typeof CONFIG_DECRYPT_FAILED | typeof INVALID_ACTION_ID | typeof INVALID_PLAYBOOK_ID | typeof PROJECT_ROOT_NOT_FOUND;
 /** 全仓统一错误码类型别名 */
 export type ActionDockErrorCode = ErrorCode;
 /**

package/dist/errors.js

@@ -71,6 +71,10 @@ export const CAPABILITY_UNAVAILABLE = "CAPABILITY_UNAVAILABLE";
 export const STATE_KEY_NOT_FOUND = "STATE_KEY_NOT_FOUND";
 /** SQLite 数据库忙或锁定 */
 export const STORAGE_BUSY = "STORAGE_BUSY";
+/** 所需生产依赖未就绪且当前环境不允许或不满足自动首装条件 */
+export const DEPENDENCIES_NOT_READY = "DEPENDENCIES_NOT_READY";
+/** 自动依赖安装进程启动失败、超时或非零退出 */
+export const DEPENDENCY_INSTALL_FAILED = "DEPENDENCY_INSTALL_FAILED";
 /** 工程事务锁被其他活跃进程持有 */
 export const PROJECT_BUSY = "PROJECT_BUSY";
 /** 工程存在未恢复的崩溃事务，需要执行恢复流程 */
@@ -301,6 +305,19 @@ export const PROJECT_CONFIG_NOT_FOUND = "PROJECT_CONFIG_NOT_FOUND";
 export const MANIFEST_LOAD_FAILED = "MANIFEST_LOAD_FAILED";
 /** 配置项数据值不符合声明的模式规范 */
 export const CONFIG_VALUE_INVALID = "CONFIG_VALUE_INVALID";
+/** 配置加密密钥缺失、无效或与存储域身份不符等加密配置错误 */
+export const CONFIG_ENCRYPTION_ERROR = "CONFIG_ENCRYPTION_ERROR";
+/** 配置密文解密失败（信封格式非法、版本未知、密钥身份不符或认证校验失败） */
+export const CONFIG_DECRYPT_FAILED = "CONFIG_DECRYPT_FAILED";
+const CONFIG_ENCRYPTION_ERROR_CODES = new Set([
+    CONFIG_ENCRYPTION_ERROR,
+    CONFIG_DECRYPT_FAILED,
+]);
+/** 配置加密与解密错误按结构化错误码识别，跨模块副本也不得吞没或覆盖。 */
+export function isConfigEncryptionError(error) {
+    const code = error?.code;
+    return typeof code === "string" && CONFIG_ENCRYPTION_ERROR_CODES.has(code);
+}
 /** 动作标识符不符合命名规范 */
 export const INVALID_ACTION_ID = "INVALID_ACTION_ID";
 /** 规程标识符不符合命名规范 */
@@ -374,6 +391,12 @@ export function resolveExecutionHint(targetRef, error) {
     if (error.code === ACTION_TIMEOUT) {
         return "Tip: Increase timeout via '--timeout <duration>', or run in background via '--async' and track with 'ad runs show <runId>'.";
     }
+    if (error.code === DEPENDENCIES_NOT_READY) {
+        return error.hint || error.details?.hint || "Tip: Install missing dependencies using 'npm install' or 'bun install'.";
+    }
+    if (error.code === DEPENDENCY_INSTALL_FAILED) {
+        return error.hint || error.details?.hint || "Tip: Check error output above and try running the package manager manually.";
+    }
     if (error.hint && typeof error.hint === "string") {
         return error.hint;
     }

package/dist/execution/service.js

@@ -289,7 +289,18 @@ export class DefaultExecutionService {
                 }
             }
             if (typeof context.timeoutMs === "number" && context.timeoutMs > 0) {
-                finalizer.startTimeout(controller, context.timeoutMs);
+                if (context.deadline !== undefined) {
+                    const remainingMs = Math.max(0, context.deadline - Date.now());
+                    if (remainingMs <= 0) {
+                        controller.abort(new ActionDockError(ACTION_TIMEOUT, `Action exceeded timeout of ${context.initialTimeoutMs ?? context.timeoutMs}ms`, { timeoutMs: context.initialTimeoutMs ?? context.timeoutMs }));
+                    }
+                    else {
+                        finalizer.startTimeout(controller, remainingMs, context.initialTimeoutMs ?? context.timeoutMs);
+                    }
+                }
+                else {
+                    finalizer.startTimeout(controller, context.timeoutMs, context.initialTimeoutMs);
+                }
             }
             const effectiveOwner = context.owner ||
                 createDefaultProcessOwner({
@@ -426,6 +437,8 @@ export class DefaultExecutionService {
             package: opts.package || this.identity,
             signal: opts.signal,
             timeoutMs: opts.timeoutMs,
+            initialTimeoutMs: opts.initialTimeoutMs,
+            deadline: opts.deadline,
             maxCallDepth: opts.maxCallDepth,
             config: opts.config || opts.configOverrides,
             tenantId: opts.tenantId || opts.owner?.tenantId,
@@ -483,20 +496,36 @@ export class DefaultExecutionService {
             };
         }
         catch (err) {
-            return this.classifyExecutionError(err, runId, context.timeoutMs, controller, finalizer);
+            return this.classifyExecutionError(err, runId, context, controller, finalizer);
         }
     }
-    classifyExecutionError(err, runId, timeoutMs, controller, finalizer) {
+    classifyExecutionError(err, runId, context, controller, finalizer) {
+        const timeoutBudget = context.initialTimeoutMs ?? context.timeoutMs;
         if (finalizer.isTimeout) {
             const error = {
                 code: ACTION_TIMEOUT,
-                message: `Action exceeded timeout of ${timeoutMs}ms`,
+                message: `Action exceeded timeout of ${timeoutBudget}ms`,
             };
             finalizer.finalize("timed_out", undefined, error);
             return { ok: false, runId, error: finalizer.persistError || error };
         }
         if (controller.signal.aborted) {
             const reason = controller.signal.reason;
+            const reasonCode = reason?.code;
+            const isTimeoutReason = reasonCode === ACTION_TIMEOUT ||
+                (reason?.details && reason.details.code === ACTION_TIMEOUT) ||
+                (reason instanceof Error && reason.message?.includes("exceeded timeout")) ||
+                (typeof reason === "string" && reason.includes("exceeded timeout"));
+            if (isTimeoutReason) {
+                const error = {
+                    code: ACTION_TIMEOUT,
+                    message: (reason instanceof Error && reason.message?.includes("exceeded timeout"))
+                        ? reason.message
+                        : `Action exceeded timeout of ${timeoutBudget}ms`,
+                };
+                finalizer.finalize("timed_out", undefined, error);
+                return { ok: false, runId, error: finalizer.persistError || error };
+            }
             const reasonMsg = reason instanceof Error
                 ? reason.message
                 : typeof reason === "string"
@@ -544,6 +573,8 @@ export class DefaultExecutionService {
             package: this.identity,
             signal: controller.signal,
             timeoutMs: context.timeoutMs,
+            initialTimeoutMs: context.initialTimeoutMs,
+            deadline: context.deadline,
             maxCallDepth: context.maxCallDepth,
             config: context.config,
             tenantId: effectiveOwner.tenantId,
@@ -564,7 +595,7 @@ export class DefaultExecutionService {
         const digestPayload = {
             input,
             config: context.config,
-            timeoutMs: context.timeoutMs,
+            timeoutMs: context.initialTimeoutMs ?? context.timeoutMs,
         };
         const inputDigest = computeDigest(digestPayload);
         const provisionalRunId = crypto.randomUUID();

package/dist/host/host.d.ts

@@ -9,6 +9,7 @@ import type { StateEntry } from "../storage/types.js";
 export declare class DefaultActionDockHost implements ActionDockHost {
     readonly hostSessionId: string;
     readonly options: ActionDockHostOptions;
+    readonly allowInstall?: boolean;
     private runtimes;
     private extraRuntimes;
     private extraRuntimeScopes;
@@ -18,6 +19,10 @@ export declare class DefaultActionDockHost implements ActionDockHost {
     private maxSubRuns;
     private eventSink;
     private isClosed;
+    private readonly prepareLocalPackage?;
+    private readonly closeController;
+    private readonly activePreparations;
+    private closePromise?;
     private dataDirLock?;
     private failedLinkedPackages;
     private failedAutoLoad?;
@@ -113,6 +118,12 @@ export declare class DefaultActionDockHost implements ActionDockHost {
     describePlaybook(id: string): Promise<PlaybookSpec>;
     runAction(ref: ActionRef | string, input: JsonValue, options?: RunOptions): Promise<ExecutionResult>;
     startAction(ref: ActionRef | string, input: JsonValue, options?: RunOptions): Promise<ExecutionTicket>;
+    /**
+     * 私有本地 Action 调度中枢。
+     * 统一处理本地已授权目标的准备（若已注入 prepareLocalPackage 且存在物理包根路径）、
+     * 中断与关闭复核，并分发至目标 Runtime 的 startInvocation。
+     */
+    private dispatchLocalInvocation;
     getRun(runId: string, signal?: AbortSignal): Promise<RunRecord | undefined>;
     listRuns(query?: ListRunsOptions, signal?: AbortSignal): Promise<RunRecord[]>;
     countRuns(query?: ListRunsOptions, signal?: AbortSignal): Promise<number>;

package/dist/host/host.js

@@ -8,7 +8,7 @@ import { hasPendingTransactions, isProjectLockHeld, recoverPendingTransactions }
 import { listLinkedPackages } from "../registry/registry.js";
 import { InMemoryEventSink } from "../runtime/events.js";
 import { snapshotRunOrigin } from "../runtime/run-origin.js";
-import { ActionDockError, ACTION_CANCELLED, ACTION_NOT_FOUND, ACTION_PACKAGE_VERSION_CONFLICT, ACTION_SUBRUN_LIMIT, EXECUTION_FAILED, INVALID_ACTION_REF, PACKAGE_ID_CONFLICT, PACKAGE_NOT_FOUND, PROJECT_BUSY, PROJECT_RECOVERY_REQUIRED, SERVICE_CLOSED, UNDECLARED_ACTION_DEPENDENCY, } from "../errors.js";
+import { ActionDockError, ACTION_CANCELLED, ACTION_NOT_FOUND, ACTION_PACKAGE_VERSION_CONFLICT, ACTION_SUBRUN_LIMIT, ACTION_TIMEOUT, EXECUTION_FAILED, INVALID_ACTION_REF, PACKAGE_ID_CONFLICT, PACKAGE_NOT_FOUND, PROJECT_BUSY, PROJECT_RECOVERY_REQUIRED, SERVICE_CLOSED, UNDECLARED_ACTION_DEPENDENCY, } from "../errors.js";
 import { InvocationPolicy } from "../invocation/policy.js";
 import { loadActionBindings, resolveActionBinding, validateActionBindings, } from "../invocation/bindings.js";
 import { RemoteInvocationExecutor } from "../invocation/remote.js";
@@ -19,7 +19,7 @@ import { DefaultActionCatalog, DefaultPackageGraph, PackageGraphBuilder, resolve
 import { parseActionRef } from "../catalog/resolve-action.js";
 import { buildRuntimeError, collectPackageInfos, describeActionAcrossRuntimes, describeVisiblePlaybook, isRootCallVisible, listVisiblePlaybooks, packageNotFoundMessage, parseRefLoose, resolveProjectRoot, } from "./routing.js";
 import { CAPABILITY_UNAVAILABLE } from "../errors.js";
-import { createGlobalStorage, redactConfigValueAtPaths, redactConfigValueForDeclarations } from "../storage/index.js";
+import { createGlobalStorage, redactConfigValueAtPaths, redactConfigValueForDeclarations, readConfigWithProtection, redactConfigValueWithProtection } from "../storage/index.js";
 import { filterByIntent } from "../utils/intent.js";
 import { assertConcreteConfigKey, isConfigTemplate, resolveConfigDeclaration, validateConfigValue, } from "../project/config-declarations.js";
 function isPackageRuntime(item) {
@@ -60,9 +60,20 @@ function withAbortSignal(op, signal) {
         });
     });
 }
+function isActionTimeoutReason(reason) {
+    if (!reason)
+        return false;
+    const code = reason?.code;
+    if (code === ACTION_TIMEOUT)
+        return true;
+    if (reason?.details?.code === ACTION_TIMEOUT)
+        return true;
+    return false;
+}
 export class DefaultActionDockHost {
     hostSessionId;
     options;
+    allowInstall;
     runtimes = new Map();
     extraRuntimes = new Set();
     extraRuntimeScopes = new Map();
@@ -72,6 +83,10 @@ export class DefaultActionDockHost {
     maxSubRuns;
     eventSink;
     isClosed = false;
+    prepareLocalPackage;
+    closeController = new AbortController();
+    activePreparations = new Set();
+    closePromise;
     dataDirLock;
     failedLinkedPackages = new Map();
     failedAutoLoad;
@@ -109,6 +124,8 @@ export class DefaultActionDockHost {
         }
         this.hostSessionId = randomUUID();
         this.options = options;
+        this.allowInstall = options.allowInstall;
+        this.prepareLocalPackage = options.prepareLocalPackage;
         this.remoteInvoker = new RemoteInvocationExecutor({ logger: options.logger });
         this.maxCallDepth = options.maxCallDepth ?? 16;
         this.maxSubRuns = options.maxSubRuns ?? 64;
@@ -469,7 +486,10 @@ export class DefaultActionDockHost {
             if (!this.recoverOrphans) {
                 throw new ActionDockError(PROJECT_RECOVERY_REQUIRED, `PROJECT_RECOVERY_REQUIRED: Project at '${root}' has pending transactions requiring recovery. Run an owner command (e.g. 'ad add' or 'ad run') to complete recovery before querying.`);
             }
-            await recoverPendingTransactions(root, { frozenInstall: true });
+            if (this.allowInstall === false || process.env.ACTIONDOCK_AUTO_INSTALL === "false") {
+                throw new ActionDockError(PROJECT_RECOVERY_REQUIRED, `PROJECT_RECOVERY_REQUIRED: Project at '${root}' has pending transactions requiring recovery install, but installation is disabled (--no-install or ACTIONDOCK_AUTO_INSTALL=false).`);
+            }
+            await recoverPendingTransactions(root, { frozenInstall: true, allowInstall: this.allowInstall });
         }
         try {
             const config = loadProjectConfig(root);
@@ -735,7 +755,7 @@ export class DefaultActionDockHost {
                     owner: targetOwner,
                     origin: context.origin,
                 };
-                const ticket = await targetRuntime.startInvocation(targetActionId, childInput, subInvocationContext);
+                const ticket = await this.dispatchLocalInvocation(targetRuntime, targetActionId, childInput, subInvocationContext);
                 if (!ticket.result) {
                     throw new ActionDockError(EXECUTION_FAILED, `Execution ticket for run '${ticket.runId}' has no result Promise`);
                 }
@@ -971,8 +991,182 @@ export class DefaultActionDockHost {
             process: this.options.process,
             origin: effectiveOptions.origin,
         });
-        // 调度目标包执行服务
-        return targetRuntime.startInvocation(targetActionId, input, rootContext);
+        // 调度目标包执行服务（经由本地分发中枢统一准备与复核）
+        return this.dispatchLocalInvocation(targetRuntime, targetActionId, input, rootContext);
+    }
+    /**
+     * 私有本地 Action 调度中枢。
+     * 统一处理本地已授权目标的准备（若已注入 prepareLocalPackage 且存在物理包根路径）、
+     * 中断与关闭复核，并分发至目标 Runtime 的 startInvocation。
+     */
+    async dispatchLocalInvocation(targetRuntime, targetActionId, input, context) {
+        if (this.isClosed) {
+            const runId = context.runId;
+            const error = buildRuntimeError(SERVICE_CLOSED, "ActionDockHost is closed: new tasks rejected", { package: targetRuntime.packageId, action: targetActionId, phase: "dispatch" });
+            return {
+                runId,
+                status: "failed",
+                result: Promise.resolve({ ok: false, runId, error }),
+            };
+        }
+        const isRootCall = !context.caller;
+        const initialTimeoutMs = context.initialTimeoutMs ?? (typeof context.timeoutMs === "number" && context.timeoutMs > 0 ? context.timeoutMs : undefined);
+        const deadline = context.deadline ?? (initialTimeoutMs !== undefined ? Date.now() + initialTimeoutMs : undefined);
+        if (context.signal.aborted) {
+            const runId = context.runId;
+            const isTimeout = isActionTimeoutReason(context.signal.reason);
+            const error = buildRuntimeError(isTimeout ? ACTION_TIMEOUT : ACTION_CANCELLED, isTimeout
+                ? `Action exceeded timeout of ${initialTimeoutMs ?? context.timeoutMs}ms`
+                : "Action execution was cancelled before starting", { package: targetRuntime.packageId, action: targetActionId, phase: "dispatch" });
+            return {
+                runId,
+                status: "failed",
+                result: Promise.resolve({ ok: false, runId, error }),
+            };
+        }
+        let timeoutController;
+        let prepTimeoutTimer;
+        if (isRootCall && typeof context.timeoutMs === "number" && context.timeoutMs > 0) {
+            timeoutController = new AbortController();
+            const remaining = deadline ? Math.max(0, deadline - Date.now()) : context.timeoutMs;
+            const timeoutReason = new ActionDockError(ACTION_TIMEOUT, `Action exceeded timeout of ${initialTimeoutMs ?? context.timeoutMs}ms`, { package: targetRuntime.packageId, action: targetActionId, phase: "preparation" });
+            if (remaining <= 0) {
+                timeoutController.abort(timeoutReason);
+            }
+            else {
+                prepTimeoutTimer = setTimeout(() => {
+                    timeoutController?.abort(timeoutReason);
+                }, remaining);
+            }
+        }
+        const signalSources = [context.signal, this.closeController.signal];
+        if (timeoutController) {
+            signalSources.push(timeoutController.signal);
+        }
+        const mergedSignal = AbortSignal.any(signalSources);
+        if (this.prepareLocalPackage && targetRuntime.packageRoot) {
+            const prepPromise = Promise.resolve().then(() => this.prepareLocalPackage({
+                identity: targetRuntime.identity,
+                packageRoot: targetRuntime.packageRoot,
+            }, {
+                signal: mergedSignal,
+                rootRunId: context.rootRunId,
+            }));
+            this.activePreparations.add(prepPromise);
+            try {
+                await prepPromise;
+            }
+            catch (err) {
+                if (prepTimeoutTimer !== undefined) {
+                    clearTimeout(prepTimeoutTimer);
+                    prepTimeoutTimer = undefined;
+                }
+                const errCode = err?.code;
+                const isClosed = this.closeController.signal.aborted;
+                const isExternalCancelled = context.signal.aborted;
+                const isTimeout = timeoutController?.signal.aborted ||
+                    isActionTimeoutReason(context.signal.reason) ||
+                    errCode === ACTION_TIMEOUT ||
+                    (err?.details && err.details.code === ACTION_TIMEOUT);
+                let code;
+                let message = err?.message || "Package preparation failed";
+                if (isTimeout) {
+                    code = ACTION_TIMEOUT;
+                    message = (err?.message && err.message.includes("exceeded timeout"))
+                        ? err.message
+                        : `Action exceeded timeout of ${initialTimeoutMs ?? context.timeoutMs}ms`;
+                }
+                else if (err instanceof ActionDockError) {
+                    code = err.code;
+                }
+                else if (isClosed) {
+                    code = SERVICE_CLOSED;
+                    message = "ActionDockHost is closed: new tasks rejected";
+                }
+                else if (isExternalCancelled) {
+                    code = ACTION_CANCELLED;
+                    message = "Action execution was cancelled";
+                }
+                else if (err?.code && typeof err.code === "string") {
+                    code = err.code;
+                }
+                else {
+                    code = EXECUTION_FAILED;
+                }
+                const hint = err?.details?.hint ?? err?.hint;
+                const details = {
+                    ...(err?.details || {}),
+                    package: targetRuntime.packageId,
+                    action: targetActionId,
+                    phase: "preparation",
+                    ...(hint ? { hint } : {}),
+                };
+                const runId = context.runId;
+                const error = buildRuntimeError(code, message, details);
+                return {
+                    runId,
+                    status: "failed",
+                    result: Promise.resolve({ ok: false, runId, error }),
+                };
+            }
+            finally {
+                this.activePreparations.delete(prepPromise);
+            }
+        }
+        if (prepTimeoutTimer !== undefined) {
+            clearTimeout(prepTimeoutTimer);
+            prepTimeoutTimer = undefined;
+        }
+        // 准备后再次复核取消与 Host 关闭状态
+        if (this.isClosed || this.closeController.signal.aborted) {
+            const runId = context.runId;
+            const error = buildRuntimeError(SERVICE_CLOSED, "ActionDockHost is closed: new tasks rejected", { package: targetRuntime.packageId, action: targetActionId, phase: "post-preparation" });
+            return {
+                runId,
+                status: "failed",
+                result: Promise.resolve({ ok: false, runId, error }),
+            };
+        }
+        if (context.signal.aborted) {
+            const runId = context.runId;
+            const isTimeout = isActionTimeoutReason(context.signal.reason);
+            const error = buildRuntimeError(isTimeout ? ACTION_TIMEOUT : ACTION_CANCELLED, isTimeout
+                ? `Action exceeded timeout of ${initialTimeoutMs ?? context.timeoutMs}ms`
+                : "Action execution was cancelled after preparation", { package: targetRuntime.packageId, action: targetActionId, phase: "post-preparation" });
+            return {
+                runId,
+                status: "failed",
+                result: Promise.resolve({ ok: false, runId, error }),
+            };
+        }
+        const remainingBudget = deadline !== undefined
+            ? Math.max(0, deadline - Date.now())
+            : context.timeoutMs;
+        if (deadline !== undefined && typeof remainingBudget === "number" && remainingBudget <= 0) {
+            const runId = context.runId;
+            const error = buildRuntimeError(ACTION_TIMEOUT, `Action exceeded timeout of ${initialTimeoutMs ?? context.timeoutMs}ms`, { package: targetRuntime.packageId, action: targetActionId, phase: "post-preparation" });
+            return {
+                runId,
+                status: "failed",
+                result: Promise.resolve({ ok: false, runId, error }),
+            };
+        }
+        const effectiveContext = {
+            ...context,
+            signal: mergedSignal,
+            initialTimeoutMs,
+            deadline,
+            timeoutMs: remainingBudget,
+        };
+        const ticket = await targetRuntime.startInvocation(targetActionId, input, effectiveContext);
+        if (ticket.result) {
+            ticket.result.finally(() => {
+                if (prepTimeoutTimer !== undefined) {
+                    clearTimeout(prepTimeoutTimer);
+                }
+            });
+        }
+        return ticket;
     }
     async getRun(runId, signal) {
         await this.ensureInitialized();
@@ -1342,16 +1536,23 @@ export class DefaultActionDockHost {
             }) ||
                 Array.from(this.runtimes.values()).some((rt) => Boolean(rt.inMemory || rt.options?.inMemory));
             const inMemory = Boolean(this.options.inMemory || hasInMemoryPackage);
+            // 旧版本全局库迁移的声明并集：取首次打开时已加载包的声明字典；
+            // 后续 registerRuntime 带来的新声明属当前版本正常写入，不重跑历史迁移
+            const configDeclarations = this.listRuntimes()
+                .map((runtime) => runtime.projectConfig?.config)
+                .filter((config) => Boolean(config && Object.keys(config).length > 0));
             this.globalStorage =
                 this.options.platform?.storage?.createGlobalStorage?.({
                     dataDir: this.options.dataDir,
                     customHome: this.options.customHome,
                     ...(inMemory ? { inMemory: true } : {}),
+                    configDeclarations,
                 }) ??
                     createGlobalStorage({
                         dataDir: this.options.dataDir,
                         customHome: this.options.customHome,
                         inMemory,
+                        configDeclarations,
                     });
         }
         return this.globalStorage;
@@ -1399,10 +1600,11 @@ export class DefaultActionDockHost {
         assertConcreteConfigKey(key);
         if (packageId === "global") {
             const globalStorage = this.getGlobalStorage();
-            const val = globalStorage.getConfig(key);
-            const configured = val !== undefined;
+            // 原子快照配对读取值与历史保护声明，消除并发删除造成的值与规则错配
+            const snapshot = readConfigWithProtection(globalStorage, key);
+            const configured = snapshot !== undefined;
             const items = this.findAllDeclaredConfigItems(key);
-            const redacted = redactConfigValueForDeclarations(val, items);
+            const redacted = redactConfigValueWithProtection(snapshot?.value, items, snapshot?.protection);
             return {
                 key,
                 configured,
@@ -1422,7 +1624,9 @@ export class DefaultActionDockHost {
             for (const item of items) {
                 validateConfigValue(key, value, item);
             }
-            await this.getGlobalStorage().setConfig(key, value);
+            // 传递全部已加载包各自解析出的有效声明并集（各包内具体键优先于模板），
+            // 由存储统一判定整键加密并合并历史保护
+            await this.getGlobalStorage().setConfig(key, value, items.length > 0 ? { declarations: items } : undefined);
             return;
         }
         await this.requireRuntime(packageId).setConfig(key, value);
@@ -1441,12 +1645,18 @@ export class DefaultActionDockHost {
             const globalStorage = this.getGlobalStorage();
             const all = globalStorage.listConfig();
             const views = [];
-            for (const [key, val] of Object.entries(all)) {
+            for (const key of Object.keys(all)) {
                 if (isConfigTemplate(key)) {
                     continue;
                 }
+                // 同源原子重读：值与历史保护声明取自同一次读取；
+                // 行在列键之后又被并发删除时跳过该项，不回退旧值
+                const snapshot = readConfigWithProtection(globalStorage, key);
+                if (snapshot === undefined) {
+                    continue;
+                }
                 const items = this.findAllDeclaredConfigItems(key);
-                const redacted = redactConfigValueForDeclarations(val, items);
+                const redacted = redactConfigValueWithProtection(snapshot.value, items, snapshot.protection);
                 views.push({
                     key,
                     configured: true,
@@ -1504,39 +1714,48 @@ export class DefaultActionDockHost {
      * 外部传入借用的 Runtime 实例生命周期完全由调用方负责管理，Host 关闭时仅解绑引用并清理自身内部实例。
      */
     async close(options) {
+        if (this.closePromise)
+            return this.closePromise;
         if (this.isClosed)
             return;
-        this.isClosed = true;
-        const allRuntimes = Array.from(this.runtimes.values());
-        await Promise.all(allRuntimes.map(async (runtime) => {
+        this.closePromise = (async () => {
+            this.isClosed = true;
+            this.closeController.abort(new ActionDockError(SERVICE_CLOSED, "ActionDockHost is closing"));
+            if (this.activePreparations.size > 0) {
+                await Promise.allSettled(Array.from(this.activePreparations));
+            }
+            const allRuntimes = Array.from(this.runtimes.values());
+            await Promise.all(allRuntimes.map(async (runtime) => {
+                try {
+                    await runtime.close(options);
+                }
+                catch {
+                    // 忽略 Runtime 关闭异常，确保全部安全释放
+                }
+            }));
+            const invocationCloseErrors = await this.closeInvocationTargets();
+            this.runtimes.clear();
+            this.actionBindings.clear();
+            this.remoteTargets.clear();
+            await this.remoteInvoker.close();
             try {
-                await runtime.close(options);
+                this.globalStorage?.close();
             }
             catch {
-                // 忽略 Runtime 关闭异常，确保全部安全释放
+                // 忽略全局存储关闭异常
             }
-        }));
-        const invocationCloseErrors = await this.closeInvocationTargets();
-        this.runtimes.clear();
-        this.actionBindings.clear();
-        this.remoteTargets.clear();
-        await this.remoteInvoker.close();
-        try {
-            this.globalStorage?.close();
-        }
-        catch {
-            // 忽略全局存储关闭异常
-        }
-        this.globalStorage = undefined;
-        try {
-            this.dataDirLock?.release();
-        }
-        catch {
-            // 忽略目录排他锁释放异常
-        }
-        this.dataDirLock = undefined;
-        if (invocationCloseErrors.length)
-            throw new AggregateError(invocationCloseErrors, "Invocation target cleanup failed");
+            this.globalStorage = undefined;
+            try {
+                this.dataDirLock?.release();
+            }
+            catch {
+                // 忽略目录排他锁释放异常
+            }
+            this.dataDirLock = undefined;
+            if (invocationCloseErrors.length)
+                throw new AggregateError(invocationCloseErrors, "Invocation target cleanup failed");
+        })();
+        return this.closePromise;
     }
 }
 /**

package/dist/host/types.d.ts

@@ -1,7 +1,7 @@
 import type { ActionRef, ExecutionEvent, ExecutionResult, JsonValue, Logger, ProcessAPI, RunRecord } from "@actiondock/sdk";
 import type { PackageInfo, PackageRuntime, PackageRuntimeOptions, ActionSpec, ActionSummary, ListActionsOptions, PlaybookSpec, PlaybookSummary } from "../package/types.js";
 import type { CancelResult, ExecutionTicket } from "../execution/types.js";
-import type { RunOptions } from "../invocation/types.js";
+import type { LocalPackagePreparer, RunOptions } from "../invocation/types.js";
 import type { Clock } from "../storage/clock.js";
 import type { EventSink } from "../runtime/events.js";
 import type { RuntimePlatform } from "../platform/types.js";
@@ -60,6 +60,13 @@ export interface ActionDockHostOptions {
     eventSink?: EventSink;
     /** 是否开启配置与状态管理端口（默认 true） */
     enableManagement?: boolean;
+    /**
+     * 是否允许执行依赖自动安装（主要控制启动与事务恢复中的依赖安装；
+     * 本地包运行期准备由 prepareLocalPackage 注入器根据自身配置决定，Host 不约束外部注入函数副作用）。
+     */
+    allowInstall?: boolean;
+    /** 本地包准备协调器回调，在 Action 执行前准备本地包环境 */
+    prepareLocalPackage?: LocalPackagePreparer;
 }
 /**
  * ActionDock 多包宿主容器领域契约。
@@ -69,6 +76,8 @@ export interface ActionDockHostOptions {
 export interface ActionDockHost extends ActionDockService {
     /** 宿主容器初始化配置项（只读） */
     readonly options?: ActionDockHostOptions;
+    /** 是否允许依赖安装（主要控制启动与事务恢复） */
+    readonly allowInstall?: boolean;
     /** 统一事件订阅端口（兼作原生订阅函数与事件服务端口） */
     readonly events: HostEventsPort;
     /** 获取所有已注册包的元数据信息列表 */