@actiondock/core 2.5.1 → 2.7.0

package/dist/host/host.js

@@ -1,7 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { DefaultActionDockApp } from "../app/app.js";
-import { ActionResolver } from "../catalog/action-resolver.js";
 import { findProjectRoot, loadProjectConfig } from "../project/loader.js";
 import { ActionPackageResolver } from "../project/resolver.js";
 import { hasPendingTransactions, isProjectLockHeld, recoverPendingTransactions } from "../project/transactions.js";
@@ -9,6 +8,7 @@ import { listLinkedPackages } from "../registry/registry.js";
 import { InMemoryEventSink } from "../runtime/events.js";
 import { ACTION_CALL_CYCLE, ACTION_MAX_DEPTH_EXCEEDED, ACTION_NOT_FOUND, ACTION_PACKAGE_VERSION_CONFLICT, ACTION_SUBRUN_LIMIT, INVALID_ACTION_REF, MAX_SUBRUNS_REACHED, PACKAGE_NOT_FOUND, PROJECT_BUSY, PROJECT_RECOVERY_REQUIRED, UNDECLARED_ACTION_DEPENDENCY, } from "../errors.js";
 import { DataDirLock } from "../storage/data-dir-lock.js";
+import { ambiguousActionMessage, buildRuntimeError, collectPackageInfos, describeActionAcrossApps, describeVisiblePlaybook, isRootCallVisible, listVisiblePlaybooks, packageNotFoundMessage, parseRefLoose, resolveProjectRoot, resolveShortRef, } from "./routing.js";
 function isActionDockApp(item) {
     return (typeof item === "object" &&
         item !== null &&
@@ -17,29 +17,13 @@ function isActionDockApp(item) {
         "runAction" in item &&
         typeof item.runAction === "function");
 }
-/**
- * 判定异常是否为 not-found 语义（包内确实不存在该 Action）。
- *
- * 遍历匹配短标识符时仅跳过此类错误；存储损坏、模块加载失败等内部错误必须向调用方透传，
- * 严禁被吞没后伪装成 ACTION_NOT_FOUND。
- */
-function isActionNotFoundLikeError(err) {
-    if (!err) {
-        return false;
-    }
-    if (err.code === ACTION_NOT_FOUND || err.code === "NOT_FOUND") {
-        return true;
-    }
-    const message = typeof err.message === "string" ? err.message : String(err);
-    return (message.startsWith("ACTION_NOT_FOUND:") ||
-        /Action '[^']*' not found in package/.test(message));
-}
 /**
  * ActionDock 统一多包宿主容器默认实现。
  * 负责聚合与调度多个 ActionDockApp 实例，提供跨包引用路由、依赖声明校验与资源配额控制。
  */
 export class DefaultActionDockHost {
     hostSessionId;
+    options;
     apps = new Map();
     internallyCreatedApps = new Set();
     activeSubRunsPerRoot = new Map();
@@ -51,11 +35,17 @@ export class DefaultActionDockHost {
     isClosed = false;
     dataDirLock;
     failedLinkedPackages = new Map();
+    failedAutoLoad;
+    /** 透传给内部创建 App 的存储收割开关（Host 默认持有者身份，显式可关） */
+    recoverOrphans;
     constructor(options = {}) {
         this.hostSessionId = randomUUID();
+        this.options = options;
         this.maxCallDepth = options.maxCallDepth ?? 16;
         this.maxSubRuns = options.maxSubRuns ?? 64;
         this.eventSink = options.eventSink ?? options.platform?.eventSink ?? new InMemoryEventSink();
+        // Host 默认声明数据目录持有者身份；查询旁观方（CLI 查询命令）显式置 false
+        this.recoverOrphans = options.recoverOrphans !== false;
         // 当指定非内存 dataDir 时获取排他目录锁，防止并发冲突
         if (options.dataDir && !options.inMemory) {
             this.dataDirLock = DataDirLock.acquire(options.dataDir, {
@@ -63,140 +53,15 @@ export class DefaultActionDockHost {
             });
         }
         try {
-            // 注册显式传入的 packages 列表
-            if (options.packages && Array.isArray(options.packages)) {
-                for (const item of options.packages) {
-                    if (isActionDockApp(item)) {
-                        this.registerAppInternal(item, true);
-                    }
-                    else {
-                        const app = new DefaultActionDockApp({
-                            ...item,
-                            hostSessionId: this.hostSessionId,
-                            platform: item.platform ?? options.platform,
-                            inMemory: item.inMemory ?? options.inMemory,
-                            customHome: item.customHome ?? options.customHome,
-                            dataDir: item.dataDir ?? options.dataDir,
-                            clock: item.clock ?? options.clock,
-                            process: item.process ?? options.process,
-                            logger: item.logger ?? options.logger,
-                            eventSink: item.eventSink ?? this.eventSink,
-                            maxCallDepth: item.maxCallDepth ?? this.maxCallDepth,
-                            maxSubRuns: item.maxSubRuns ?? this.maxSubRuns,
-                            packageContextResolver: this.resolvePackageContext.bind(this),
-                        });
-                        this.internallyCreatedApps.add(app);
-                        this.registerAppInternal(app, true);
-                    }
-                }
-            }
-            // 自动加载当前工程（若发现工程根目录且未显式禁用）
+            // 阶段一：注册显式传入的 packages 列表
+            this.registerExplicitPackages(options);
+            // 阶段二：自动加载当前工程（若发现工程根目录且未显式禁用）
             if (options.autoLoadCurrentProject !== false) {
-                let root = options.projectRoot;
-                if (!root) {
-                    const detected = findProjectRoot();
-                    if (detected) {
-                        root = detected;
-                    }
-                }
-                if (root && existsSync(root)) {
-                    if (isProjectLockHeld(root)) {
-                        const err = new Error("PROJECT_BUSY: Project directory is locked by another active process holding project.lock");
-                        err.code = PROJECT_BUSY;
-                        throw err;
-                    }
-                    if (hasPendingTransactions(root)) {
-                        const err = new Error(`PROJECT_RECOVERY_REQUIRED: Project directory '${root}' has pending transactions requiring recovery; use async createActionDockHost() to recover automatically`);
-                        err.code = PROJECT_RECOVERY_REQUIRED;
-                        throw err;
-                    }
-                    try {
-                        const config = loadProjectConfig(root);
-                        this.hostPublicPackageIds.add(config.id);
-                        this.resolver = new ActionPackageResolver({
-                            projectRoot: root,
-                            manifest: config,
-                            allowDevLinks: options.scanLinkedPackages,
-                            customHome: options.customHome,
-                        });
-                        const graph = this.resolver.resolveSync();
-                        this.hostPublicPackageIds.add(graph.rootPackageId);
-                        for (const depId of graph.directDependencyIds) {
-                            this.hostPublicPackageIds.add(depId);
-                        }
-                        for (const pkg of graph.packages.values()) {
-                            if (!this.apps.has(pkg.packageId)) {
-                                const isDirectOrRoot = this.hostPublicPackageIds.has(pkg.packageId);
-                                const app = new DefaultActionDockApp({
-                                    packageRoot: pkg.packageRoot,
-                                    projectConfig: pkg.manifest,
-                                    hostSessionId: this.hostSessionId,
-                                    platform: options.platform,
-                                    inMemory: options.inMemory,
-                                    customHome: options.customHome,
-                                    dataDir: options.dataDir,
-                                    clock: options.clock,
-                                    process: options.process,
-                                    logger: options.logger,
-                                    eventSink: this.eventSink,
-                                    maxCallDepth: this.maxCallDepth,
-                                    maxSubRuns: this.maxSubRuns,
-                                    packageContextResolver: this.resolvePackageContext.bind(this),
-                                });
-                                this.internallyCreatedApps.add(app);
-                                this.registerAppInternal(app, isDirectOrRoot);
-                            }
-                        }
-                    }
-                    catch (err) {
-                        if (err?.code === ACTION_PACKAGE_VERSION_CONFLICT ||
-                            err?.code === PROJECT_RECOVERY_REQUIRED ||
-                            err?.code === PROJECT_BUSY) {
-                            throw err;
-                        }
-                        // 忽略非 ActionDock 工程目录解析异常
-                    }
-                }
+                this.loadCurrentProject(options);
             }
-            // 扫描已软链接的外部包并注册至 Host
+            // 阶段三：扫描已软链接的外部包并注册至 Host
             if (options.scanLinkedPackages) {
-                for (const linked of listLinkedPackages(options.customHome)) {
-                    if (!this.apps.has(linked.id)) {
-                        if (!existsSync(linked.path)) {
-                            const err = `Linked package '${linked.id}' path does not exist on disk: '${linked.path}'`;
-                            this.failedLinkedPackages.set(linked.id, { path: linked.path, error: err });
-                            options.logger?.warn?.(`[Host] ${err}`);
-                            continue;
-                        }
-                        try {
-                            const config = loadProjectConfig(linked.path);
-                            this.hostPublicPackageIds.add(linked.id);
-                            const app = new DefaultActionDockApp({
-                                packageRoot: linked.path,
-                                projectConfig: config,
-                                hostSessionId: this.hostSessionId,
-                                platform: options.platform,
-                                inMemory: options.inMemory,
-                                customHome: options.customHome,
-                                dataDir: options.dataDir,
-                                clock: options.clock,
-                                process: options.process,
-                                logger: options.logger,
-                                eventSink: this.eventSink,
-                                maxCallDepth: this.maxCallDepth,
-                                maxSubRuns: this.maxSubRuns,
-                                packageContextResolver: this.resolvePackageContext.bind(this),
-                            });
-                            this.internallyCreatedApps.add(app);
-                            this.registerAppInternal(app, true);
-                        }
-                        catch (err) {
-                            const errDetail = err?.message || String(err);
-                            this.failedLinkedPackages.set(linked.id, { path: linked.path, error: errDetail });
-                            options.logger?.warn?.(`[Host] Failed to load linked package '${linked.id}' from '${linked.path}': ${errDetail}`);
-                        }
-                    }
-                }
+                this.registerLinkedPackages(options);
             }
         }
         catch (err) {
@@ -224,6 +89,164 @@ export class DefaultActionDockHost {
             throw err;
         }
     }
+    /**
+     * 阶段函数：注册显式传入的 packages 列表（现成 App 实例或 AppOptions 配置）。
+     */
+    registerExplicitPackages(options) {
+        if (!options.packages || !Array.isArray(options.packages)) {
+            return;
+        }
+        for (const item of options.packages) {
+            if (isActionDockApp(item)) {
+                this.registerAppInternal(item, true);
+            }
+            else {
+                const app = new DefaultActionDockApp({
+                    ...item,
+                    hostSessionId: this.hostSessionId,
+                    platform: item.platform ?? options.platform,
+                    inMemory: item.inMemory ?? options.inMemory,
+                    customHome: item.customHome ?? options.customHome,
+                    dataDir: item.dataDir ?? options.dataDir,
+                    clock: item.clock ?? options.clock,
+                    process: item.process ?? options.process,
+                    logger: item.logger ?? options.logger,
+                    eventSink: item.eventSink ?? this.eventSink,
+                    maxCallDepth: item.maxCallDepth ?? this.maxCallDepth,
+                    maxSubRuns: item.maxSubRuns ?? this.maxSubRuns,
+                    recoverOrphans: this.recoverOrphans,
+                    packageContextResolver: this.resolvePackageContext.bind(this),
+                });
+                this.internallyCreatedApps.add(app);
+                this.registerAppInternal(app, true);
+            }
+        }
+    }
+    /**
+     * 阶段函数：自动加载当前工程并注册依赖闭包内的全部包。
+     *
+     * 失败语义区分场景：
+     * - 显式传入 projectRoot 时，任何解析失败（损坏 actiondock.json、文件系统错误等）
+     *   必须向上抛出，由调用方感知，严禁吞没；
+     * - 自动探测场景（未传 projectRoot，由 findProjectRoot 发现）失败时记录实例诊断
+     *   failedAutoLoad 并在创建时输出单行告警，保持宿主其余能力可用但绝不无声。
+     */
+    loadCurrentProject(options) {
+        const explicitRoot = options.projectRoot;
+        const root = resolveProjectRoot(options, () => findProjectRoot());
+        if (!root) {
+            return;
+        }
+        if (isProjectLockHeld(root)) {
+            const err = new Error("PROJECT_BUSY: Project directory is locked by another active process holding project.lock");
+            err.code = PROJECT_BUSY;
+            throw err;
+        }
+        if (hasPendingTransactions(root)) {
+            const err = new Error(`PROJECT_RECOVERY_REQUIRED: Project directory '${root}' has pending transactions requiring recovery; use async createActionDockHost() to recover automatically`);
+            err.code = PROJECT_RECOVERY_REQUIRED;
+            throw err;
+        }
+        try {
+            const config = loadProjectConfig(root);
+            this.hostPublicPackageIds.add(config.id);
+            this.resolver = new ActionPackageResolver({
+                projectRoot: root,
+                manifest: config,
+                allowDevLinks: options.scanLinkedPackages,
+                customHome: options.customHome,
+            });
+            const graph = this.resolver.resolveSync();
+            this.hostPublicPackageIds.add(graph.rootPackageId);
+            for (const depId of graph.directDependencyIds) {
+                this.hostPublicPackageIds.add(depId);
+            }
+            for (const pkg of graph.packages.values()) {
+                if (!this.apps.has(pkg.packageId)) {
+                    const isDirectOrRoot = this.hostPublicPackageIds.has(pkg.packageId);
+                    const app = new DefaultActionDockApp({
+                        packageRoot: pkg.packageRoot,
+                        projectConfig: pkg.manifest,
+                        hostSessionId: this.hostSessionId,
+                        platform: options.platform,
+                        inMemory: options.inMemory,
+                        customHome: options.customHome,
+                        dataDir: options.dataDir,
+                        clock: options.clock,
+                        process: options.process,
+                        logger: options.logger,
+                        eventSink: this.eventSink,
+                        maxCallDepth: this.maxCallDepth,
+                        maxSubRuns: this.maxSubRuns,
+                        recoverOrphans: this.recoverOrphans,
+                        packageContextResolver: this.resolvePackageContext.bind(this),
+                    });
+                    this.internallyCreatedApps.add(app);
+                    this.registerAppInternal(app, isDirectOrRoot);
+                }
+            }
+        }
+        catch (err) {
+            if (err?.code === ACTION_PACKAGE_VERSION_CONFLICT ||
+                err?.code === PROJECT_RECOVERY_REQUIRED ||
+                err?.code === PROJECT_BUSY) {
+                throw err;
+            }
+            if (explicitRoot) {
+                // 显式指定的工程根目录解析失败必须抛出：调用方明确指定了位置，损坏配置不允许被吞没
+                throw err;
+            }
+            // 自动探测场景：记录实例诊断并输出单行告警，避免损坏工程被无声跳过
+            const detail = err?.message || String(err);
+            this.failedAutoLoad = { projectRoot: root, error: detail };
+            console.warn(`[Host] Failed to auto-load project at '${root}': ${detail}`);
+        }
+    }
+    /**
+     * 阶段函数：扫描全局注册表中已软链接的外部包并注册至 Host。
+     * 加载失败的链接包记录至 failedLinkedPackages 诊断并在调阅时透传精准失败原因。
+     */
+    registerLinkedPackages(options) {
+        for (const linked of listLinkedPackages(options.customHome)) {
+            if (this.apps.has(linked.id)) {
+                continue;
+            }
+            if (!existsSync(linked.path)) {
+                const err = `Linked package '${linked.id}' path does not exist on disk: '${linked.path}'`;
+                this.failedLinkedPackages.set(linked.id, { path: linked.path, error: err });
+                options.logger?.warn?.(`[Host] ${err}`);
+                continue;
+            }
+            try {
+                const config = loadProjectConfig(linked.path);
+                this.hostPublicPackageIds.add(linked.id);
+                const app = new DefaultActionDockApp({
+                    packageRoot: linked.path,
+                    projectConfig: config,
+                    hostSessionId: this.hostSessionId,
+                    platform: options.platform,
+                    inMemory: options.inMemory,
+                    customHome: options.customHome,
+                    dataDir: options.dataDir,
+                    clock: options.clock,
+                    process: options.process,
+                    logger: options.logger,
+                    eventSink: this.eventSink,
+                    maxCallDepth: this.maxCallDepth,
+                    maxSubRuns: this.maxSubRuns,
+                    recoverOrphans: this.recoverOrphans,
+                    packageContextResolver: this.resolvePackageContext.bind(this),
+                });
+                this.internallyCreatedApps.add(app);
+                this.registerAppInternal(app, true);
+            }
+            catch (err) {
+                const errDetail = err?.message || String(err);
+                this.failedLinkedPackages.set(linked.id, { path: linked.path, error: errDetail });
+                options.logger?.warn?.(`[Host] Failed to load linked package '${linked.id}' from '${linked.path}': ${errDetail}`);
+            }
+        }
+    }
     resolvePackageContext(packageId) {
         const targetApp = this.getApp(packageId);
         if (!targetApp)
@@ -243,12 +266,26 @@ export class DefaultActionDockHost {
             runner.setPackageContextResolver(this.resolvePackageContext.bind(this));
         }
     }
+    /** 路由可见性上下文（公开包集合与依赖解析器） */
+    visibility() {
+        return {
+            hostPublicPackageIds: this.hostPublicPackageIds,
+            resolver: this.resolver,
+        };
+    }
     getApp(packageId) {
         return this.apps.get(packageId);
     }
     listApps() {
         return Array.from(this.apps.values());
     }
+    /**
+     * 获取自动加载工程的失败诊断信息。
+     * 仅自动探测场景会记录此诊断；显式传入 projectRoot 的加载失败会直接抛出，不产生此诊断。
+     */
+    getAutoLoadFailure() {
+        return this.failedAutoLoad;
+    }
     registerAppInternal(app, isPublic) {
         if (this.apps.has(app.packageId)) {
             const existing = this.apps.get(app.packageId);
@@ -262,22 +299,18 @@ export class DefaultActionDockHost {
             this.hostPublicPackageIds.add(app.packageId);
         }
         this.bindApp(app);
-        // 接管与恢复：自动将死亡会话或遗留非终态运行收敛为 interrupted
-        const st = app.storage;
-        if (st && typeof st.recoverDeadSessionRuns === "function") {
-            try {
-                st.recoverDeadSessionRuns(this.hostSessionId);
-            }
-            catch {
-                // 忽略单包恢复异常
-            }
-        }
-        else if (st && typeof st.recoverRunningRuns === "function") {
-            try {
-                st.recoverRunningRuns(this.hostSessionId);
-            }
-            catch {
-                // 忽略单包恢复异常
+        // 接管与恢复：仅持有者身份的 Host 自动将死亡会话或遗留非终态运行收敛为 interrupted；
+        // 旁观查询 Host（CLI state/runs/config 命令）跳过本步骤，不动其他进程的在途记录
+        if (this.recoverOrphans) {
+            const st = app.storage;
+            if (st && typeof st.recoverDeadSessionRuns === "function") {
+                try {
+                    st.recoverDeadSessionRuns(this.hostSessionId);
+                }
+                catch (err) {
+                    // 单包恢复失败不阻断整体接管流程，但必须可观测
+                    console.warn(`[actiondock] recoverDeadSessionRuns failed for package '${app.packageId}': ${err instanceof Error ? err.message : String(err)}`);
+                }
             }
         }
     }
@@ -285,16 +318,15 @@ export class DefaultActionDockHost {
         this.registerAppInternal(app, true);
     }
     async info() {
-        return Promise.all(this.listApps().map((app) => app.info()));
+        return collectPackageInfos(this.listApps());
     }
     async listActions(options) {
         let results = [];
         const apps = this.listApps();
         for (const app of apps) {
-            const isPublic = this.hostPublicPackageIds.has(app.packageId);
             const appSummaries = await app.listActions();
             for (const item of appSummaries) {
-                if (!isPublic && this.resolver && !this.resolver.canRootCall(app.packageId, item.id)) {
+                if (!isRootCallVisible(app.packageId, item.id, this.hostPublicPackageIds, this.resolver)) {
                     continue;
                 }
                 const qualifiedId = apps.length > 1 && !item.id.includes("/")
@@ -321,123 +353,13 @@ export class DefaultActionDockHost {
         return results;
     }
     async describeAction(ref) {
-        let parsed;
-        try {
-            parsed = ActionResolver.parseRef(ref);
-        }
-        catch {
-            parsed = typeof ref === "object" ? ref : { actionId: ref };
-        }
-        if (parsed.packageId) {
-            const isPublic = this.hostPublicPackageIds.has(parsed.packageId);
-            if (!isPublic && this.resolver && !this.resolver.canRootCall(parsed.packageId, parsed.actionId)) {
-                throw new Error(`UNDECLARED_ACTION_DEPENDENCY: Action '${parsed.packageId}/${parsed.actionId}' is not declared as a direct dependency in actiondock.json and is not delegated by a visible playbook`);
-            }
-            const app = this.getApp(parsed.packageId);
-            if (!app) {
-                const failed = this.failedLinkedPackages.get(parsed.packageId);
-                if (failed) {
-                    throw new Error(`Package '${parsed.packageId}' not found in host (failed to load from '${failed.path}': ${failed.error})`);
-                }
-                throw new Error(`Package '${parsed.packageId}' not found in host`);
-            }
-            const spec = await app.describeAction(parsed.actionId);
-            return {
-                ...spec,
-                packageId: app.packageId,
-            };
-        }
-        const matches = [];
-        for (const app of this.listApps()) {
-            try {
-                const isPublic = this.hostPublicPackageIds.has(app.packageId);
-                if (!isPublic && this.resolver && !this.resolver.canRootCall(app.packageId, parsed.actionId)) {
-                    continue;
-                }
-                const spec = await app.describeAction(parsed.actionId);
-                matches.push({ app, spec: { ...spec, packageId: app.packageId } });
-            }
-            catch (err) {
-                // 仅将 not-found 语义视为「包内无此 Action」；其余异常必须透传，避免内部错误伪装成 ACTION_NOT_FOUND
-                if (!isActionNotFoundLikeError(err)) {
-                    throw err;
-                }
-            }
-        }
-        if (matches.length === 1) {
-            return {
-                ...matches[0].spec,
-                packageId: matches[0].app.packageId,
-            };
-        }
-        if (matches.length > 1) {
-            const candidates = matches.map((m) => `${m.app.packageId}/${parsed.actionId}`).join(", ");
-            const err = new Error(`INVALID_ACTION_REF: Action '${parsed.actionId}' is ambiguous and provided by multiple packages: ${candidates}. Please specify '<package-id>/${parsed.actionId}'. (AMBIGUOUS_ACTION_REF)`);
-            err.code = "INVALID_ACTION_REF";
-            err.details = { alias: "AMBIGUOUS_ACTION_REF", candidates: matches.map((m) => m.app.packageId) };
-            throw err;
-        }
-        throw new Error(`ACTION_NOT_FOUND: Action '${parsed.actionId}' not found in any registered package`);
+        return describeActionAcrossApps(ref, this.listApps(), this.visibility(), this.failedLinkedPackages);
     }
     async listPlaybooks() {
-        const results = [];
-        const apps = this.listApps();
-        for (const app of apps) {
-            const isPublic = this.hostPublicPackageIds.has(app.packageId);
-            if (!isPublic && this.resolver) {
-                const graph = this.resolver.resolveSync();
-                if (!graph.directDependencyIds.has(app.packageId)) {
-                    continue;
-                }
-            }
-            const appPlaybooks = await app.listPlaybooks();
-            for (const item of appPlaybooks) {
-                const qualifiedId = apps.length > 1 && !item.id.includes("/")
-                    ? `${app.packageId}/${item.id}`
-                    : item.id;
-                results.push({
-                    ...item,
-                    id: qualifiedId,
-                    packageId: app.packageId,
-                });
-            }
-        }
-        return results;
+        return listVisiblePlaybooks(this.listApps(), this.visibility());
     }
     async describePlaybook(id) {
-        if (id.includes("/")) {
-            const lastSlashIndex = id.lastIndexOf("/");
-            const packageId = id.slice(0, lastSlashIndex);
-            const playbookId = id.slice(lastSlashIndex + 1);
-            const isPublic = this.hostPublicPackageIds.has(packageId);
-            if (!isPublic && this.resolver) {
-                const graph = this.resolver.resolveSync();
-                if (!graph.directDependencyIds.has(packageId)) {
-                    throw new Error(`UNDECLARED_ACTION_DEPENDENCY: Playbook '${id}' belongs to undeclared transitive package '${packageId}'`);
-                }
-            }
-            const app = this.getApp(packageId);
-            if (!app) {
-                throw new Error(`Package '${packageId}' not found in host`);
-            }
-            return app.describePlaybook(playbookId);
-        }
-        for (const app of this.listApps()) {
-            try {
-                const isPublic = this.hostPublicPackageIds.has(app.packageId);
-                if (!isPublic && this.resolver) {
-                    const graph = this.resolver.resolveSync();
-                    if (!graph.directDependencyIds.has(app.packageId)) {
-                        continue;
-                    }
-                }
-                return await app.describePlaybook(id);
-            }
-            catch {
-                // 忽略未匹配的包
-            }
-        }
-        throw new Error(`Playbook '${id}' not found in any registered package`);
+        return describeVisiblePlaybook(this.listApps(), id, this.visibility());
     }
     async runAction(ref, input, options = {}) {
         const ticket = await this.startAction(ref, input, options);
@@ -451,13 +373,7 @@ export class DefaultActionDockHost {
             throw new Error("ActionDockHost is closed: new tasks rejected");
         }
         // - 解析目标包与 Action 动作标识
-        let parsed;
-        try {
-            parsed = ActionResolver.parseRef(ref);
-        }
-        catch {
-            parsed = typeof ref === "object" ? ref : { actionId: ref };
-        }
+        const parsed = parseRefLoose(ref);
         let targetApp;
         let targetActionId = parsed.actionId;
         let targetPackageId = parsed.packageId;
@@ -465,14 +381,7 @@ export class DefaultActionDockHost {
             targetApp = this.getApp(targetPackageId);
             if (!targetApp) {
                 const runId = randomUUID();
-                const failed = this.failedLinkedPackages.get(targetPackageId);
-                const errorMsg = failed
-                    ? `Package '${targetPackageId}' not found in host (failed to load from '${failed.path}': ${failed.error})`
-                    : `Package '${targetPackageId}' not found in host`;
-                const error = {
-                    code: PACKAGE_NOT_FOUND,
-                    message: errorMsg,
-                };
+                const error = buildRuntimeError(PACKAGE_NOT_FOUND, packageNotFoundMessage(targetPackageId, this.failedLinkedPackages));
                 return {
                     runId,
                     status: "failed",
@@ -481,35 +390,14 @@ export class DefaultActionDockHost {
             }
         }
         else {
-            const matches = [];
-            for (const app of this.listApps()) {
-                try {
-                    const isPublic = this.hostPublicPackageIds.has(app.packageId);
-                    if (!isPublic && this.resolver && !this.resolver.canRootCall(app.packageId, targetActionId)) {
-                        continue;
-                    }
-                    await app.describeAction(targetActionId);
-                    matches.push(app);
-                }
-                catch (err) {
-                    // 仅将 not-found 语义视为「包内无此 Action」；其余异常必须透传，避免内部错误伪装成 ACTION_NOT_FOUND
-                    if (!isActionNotFoundLikeError(err)) {
-                        throw err;
-                    }
-                }
-            }
-            if (matches.length === 1) {
-                targetApp = matches[0];
+            const resolution = await resolveShortRef(this.listApps(), targetActionId, this.visibility());
+            if (resolution.kind === "unique") {
+                targetApp = resolution.app;
                 targetPackageId = targetApp.packageId;
             }
-            else if (matches.length > 1) {
-                const candidates = matches.map((m) => `${m.packageId}/${targetActionId}`).join(", ");
+            else if (resolution.kind === "ambiguous") {
                 const runId = randomUUID();
-                const error = {
-                    code: INVALID_ACTION_REF,
-                    message: `Action '${targetActionId}' is ambiguous and provided by multiple packages: ${candidates}. Please specify '<package-id>/${targetActionId}'.`,
-                    details: { alias: "AMBIGUOUS_ACTION_REF", candidates: matches.map((m) => m.packageId) },
-                };
+                const error = buildRuntimeError(INVALID_ACTION_REF, ambiguousActionMessage(targetActionId, resolution.candidates), { alias: "AMBIGUOUS_ACTION_REF", candidates: resolution.candidates });
                 return {
                     runId,
                     status: "failed",
@@ -518,10 +406,7 @@ export class DefaultActionDockHost {
             }
             else {
                 const runId = randomUUID();
-                const error = {
-                    code: ACTION_NOT_FOUND,
-                    message: `Action '${targetActionId}' not found in any registered package`,
-                };
+                const error = buildRuntimeError(ACTION_NOT_FOUND, `Action '${targetActionId}' not found in any registered package`);
                 return {
                     runId,
                     status: "failed",
@@ -532,16 +417,9 @@ export class DefaultActionDockHost {
         // 根调用可见性鉴权
         const parentRunId = options.parentRunId;
         if (!parentRunId && targetPackageId) {
-            const isPublic = this.hostPublicPackageIds.has(targetPackageId);
-            if (!isPublic && this.resolver && !this.resolver.canRootCall(targetPackageId, targetActionId)) {
+            if (!isRootCallVisible(targetPackageId, targetActionId, this.hostPublicPackageIds, this.resolver)) {
                 const runId = randomUUID();
-                const error = {
-                    code: UNDECLARED_ACTION_DEPENDENCY,
-                    message: `Root call to action '${targetPackageId}/${targetActionId}' is not allowed: package '${targetPackageId}' is not declared as a direct dependency in actiondock.json and is not delegated by a visible playbook`,
-                    details: {
-                        target: `${targetPackageId}/${targetActionId}`,
-                    },
-                };
+                const error = buildRuntimeError(UNDECLARED_ACTION_DEPENDENCY, `Root call to action '${targetPackageId}/${targetActionId}' is not allowed: package '${targetPackageId}' is not declared as a direct dependency in actiondock.json and is not delegated by a visible playbook`, { target: `${targetPackageId}/${targetActionId}` });
                 return {
                     runId,
                     status: "failed",
@@ -570,15 +448,11 @@ export class DefaultActionDockHost {
                                 : usesList.some((u) => u === targetRef || u === `${targetPackageId}/*` || u === targetPackageId);
                             if (!isAllowed) {
                                 const runId = randomUUID();
-                                const error = {
-                                    code: UNDECLARED_ACTION_DEPENDENCY,
-                                    message: `Action '${callerPackageId}/${callerActionId}' does not declare dependency on '${targetRef}' in 'uses'`,
-                                    details: {
-                                        caller: `${callerPackageId}/${callerActionId}`,
-                                        target: targetRef,
-                                        declaredUses: usesList,
-                                    },
-                                };
+                                const error = buildRuntimeError(UNDECLARED_ACTION_DEPENDENCY, `Action '${callerPackageId}/${callerActionId}' does not declare dependency on '${targetRef}' in 'uses'`, {
+                                    caller: `${callerPackageId}/${callerActionId}`,
+                                    target: targetRef,
+                                    declaredUses: usesList,
+                                });
                                 return {
                                     runId,
                                     status: "failed",
@@ -602,11 +476,7 @@ export class DefaultActionDockHost {
                 }
                 if (depth >= this.maxCallDepth) {
                     const runId = randomUUID();
-                    const error = {
-                        code: ACTION_CALL_CYCLE,
-                        message: `Maximum call depth of ${this.maxCallDepth} exceeded`,
-                        details: { alias: ACTION_MAX_DEPTH_EXCEEDED, reason: "depth_exceeded", maxDepth: this.maxCallDepth },
-                    };
+                    const error = buildRuntimeError(ACTION_CALL_CYCLE, `Maximum call depth of ${this.maxCallDepth} exceeded`, { alias: ACTION_MAX_DEPTH_EXCEEDED, reason: "depth_exceeded", maxDepth: this.maxCallDepth });
                     return {
                         runId,
                         status: "failed",
@@ -618,11 +488,7 @@ export class DefaultActionDockHost {
                     const currentSubRuns = this.activeSubRunsPerRoot.get(effectiveRootRunId) || 0;
                     if (currentSubRuns >= this.maxSubRuns) {
                         const runId = randomUUID();
-                        const error = {
-                            code: ACTION_SUBRUN_LIMIT,
-                            message: `Maximum concurrent sub-runs (${this.maxSubRuns}) reached for root run '${effectiveRootRunId}'`,
-                            details: { alias: MAX_SUBRUNS_REACHED, limit: this.maxSubRuns },
-                        };
+                        const error = buildRuntimeError(ACTION_SUBRUN_LIMIT, `Maximum concurrent sub-runs (${this.maxSubRuns}) reached for root run '${effectiveRootRunId}'`, { alias: MAX_SUBRUNS_REACHED, limit: this.maxSubRuns });
                         return {
                             runId,
                             status: "failed",
@@ -745,14 +611,8 @@ export async function createActionDockHost(options = {}) {
     let createdHost;
     try {
         if (options.autoLoadCurrentProject !== false) {
-            let root = options.projectRoot;
-            if (!root) {
-                const detected = findProjectRoot();
-                if (detected) {
-                    root = detected;
-                }
-            }
-            if (root && existsSync(root)) {
+            const root = resolveProjectRoot(options, () => findProjectRoot());
+            if (root) {
                 if (isProjectLockHeld(root)) {
                     const err = new Error("PROJECT_BUSY: Project directory is locked by another active process holding project.lock");
                     err.code = PROJECT_BUSY;