@actiondock/core 2.5.0 → 2.6.0

package/dist/storage/sqlite.d.ts

@@ -4,6 +4,18 @@ export { decodeStateKey, encodeStateKey, escapeStateSegment, unescapeStateSegmen
 /**
  * 统一 SQLite 运行时存储实现。
  * 通过 SqliteDriver 抽象驱动，解耦底层具体运行时引擎。
+ *
+ * 跨进程并发模型：
+ * - 同一数据目录下的 runtime.db 允许持有者进程（serve、mcp、ad run 等执行宿主）
+ *   与旁观查询进程（ad state、ad runs、ad config 等只读命令）并发打开。
+ * - 死亡会话遗留非终态运行记录的收割（recoverDeadSessionRuns）仅由显式声明
+ *   持有者身份的打开方执行：StorageOptions.recoverOrphans 为 true 时构造阶段收割，
+ *   宿主接管路径亦可显式调用 recoverDeadSessionRuns 收敛死亡会话记录。
+ * - 旁观打开（默认 recoverOrphans 为 false）保持只读语义，绝不收敛其他进程的在途
+ *   running 记录，防止查询进程把执行宿主的在途运行误收割为 interrupted，导致持有者
+ *   侧终态结算静默丢失。
+ * - updateRun 以 WHERE id = ? AND status = 'running' 条件更新；若命中零行且新状态
+ *   为终态，说明记录已被其他持有者或恢复流程改写，此处输出告警保证状态漂移可观测。
  */
 export declare class SqliteRuntimeStorage implements RuntimeStorage {
     private driver;
@@ -12,6 +24,7 @@ export declare class SqliteRuntimeStorage implements RuntimeStorage {
     private isClosed;
     private statementCache;
     private dbPath;
+    private recoverOrphans;
     get isOpen(): boolean;
     get closed(): boolean;
     constructor(options: StorageOptions);
@@ -24,11 +37,6 @@ export declare class SqliteRuntimeStorage implements RuntimeStorage {
      * - 打开旧版本或不兼容版本的数据库时，在写事务前直接抛出 UNSUPPORTED_STORAGE_SCHEMA 异常并拒绝启动。
      */
     private init;
-    /**
-     * 重启恢复：将未正常结算的非终态（running/pending）记录自动收敛为 interrupted。
-     * 若指定了当前新 Host 会话标识，将收敛不属于该会话（包括旧会话或空会话）的死亡任务。
-     */
-    recoverRunningRuns(currentHostSessionId?: string): number;
     /**
      * 收敛死亡会话遗留的非终态运行任务。
      */
@@ -48,7 +56,11 @@ export declare class SqliteRuntimeStorage implements RuntimeStorage {
     deleteState(namespace: string, key: string): Promise<boolean>;
     deleteStateSmart(targetKey: string, namespace?: string): Promise<boolean>;
     /**
-     * 清理已过期的状态记录
+     * 清理已过期的状态记录。
+     *
+     * 同时按 TargetInfo.idempotencyPolicy 声明的 24 小时保留窗口，
+     * 清理 idempotency_keys 表中超过保留期的幂等去重记录，
+     * 保证承诺的 retentionMs 策略与实际清理逻辑一致。
      */
     cleanExpiredState(): Promise<number>;
     clearState(options?: {
@@ -66,6 +78,7 @@ export declare class SqliteRuntimeStorage implements RuntimeStorage {
     getRun(id: string): RunRecord | null;
     listRuns(options?: {
         actionId?: string;
+        status?: string;
         limit?: number;
     }): RunRecord[];
     clearRuns(options?: {

package/dist/storage/sqlite.js

@@ -1,13 +1,26 @@
 import { chmodSync, existsSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 import { decodeStateKey, encodeStateKey, escapeStateSegment, unescapeStateSegment, } from "@actiondock/sdk";
-import { SystemClock } from "../runtime/clock.js";
+import { SystemClock } from "./clock.js";
 import { createDefaultSqliteDriver } from "./driver.js";
-import { STORAGE_SCHEMA_VERSION, } from "./types.js";
+import { safeParseStoredJson } from "./utils.js";
+import { IDEMPOTENCY_RETENTION_MS, STORAGE_SCHEMA_VERSION, isTerminalRunStatus, } from "./types.js";
 export { decodeStateKey, encodeStateKey, escapeStateSegment, unescapeStateSegment, };
 /**
  * 统一 SQLite 运行时存储实现。
  * 通过 SqliteDriver 抽象驱动，解耦底层具体运行时引擎。
+ *
+ * 跨进程并发模型：
+ * - 同一数据目录下的 runtime.db 允许持有者进程（serve、mcp、ad run 等执行宿主）
+ *   与旁观查询进程（ad state、ad runs、ad config 等只读命令）并发打开。
+ * - 死亡会话遗留非终态运行记录的收割（recoverDeadSessionRuns）仅由显式声明
+ *   持有者身份的打开方执行：StorageOptions.recoverOrphans 为 true 时构造阶段收割，
+ *   宿主接管路径亦可显式调用 recoverDeadSessionRuns 收敛死亡会话记录。
+ * - 旁观打开（默认 recoverOrphans 为 false）保持只读语义，绝不收敛其他进程的在途
+ *   running 记录，防止查询进程把执行宿主的在途运行误收割为 interrupted，导致持有者
+ *   侧终态结算静默丢失。
+ * - updateRun 以 WHERE id = ? AND status = 'running' 条件更新；若命中零行且新状态
+ *   为终态，说明记录已被其他持有者或恢复流程改写，此处输出告警保证状态漂移可观测。
  */
 export class SqliteRuntimeStorage {
     driver;
@@ -16,6 +29,7 @@ export class SqliteRuntimeStorage {
     isClosed = false;
     statementCache = new Map();
     dbPath;
+    recoverOrphans;
     get isOpen() {
         return !this.isClosed;
     }
@@ -27,6 +41,7 @@ export class SqliteRuntimeStorage {
         this.clock = options.clock ?? new SystemClock();
         const dbPath = options.dbPath || ":memory:";
         this.dbPath = dbPath;
+        this.recoverOrphans = options.recoverOrphans === true;
         if (dbPath !== ":memory:") {
             const dir = dirname(dbPath);
             if (!existsSync(dir)) {
@@ -142,15 +157,11 @@ export class SqliteRuntimeStorage {
                 // 忽略非结构化表或兼容驱动异常
             }
         }
-        // 重启恢复：将未正常结算的 running 与 pending 状态自动收敛为 interrupted
-        this.recoverRunningRuns();
-    }
-    /**
-     * 重启恢复：将未正常结算的非终态（running/pending）记录自动收敛为 interrupted。
-     * 若指定了当前新 Host 会话标识，将收敛不属于该会话（包括旧会话或空会话）的死亡任务。
-     */
-    recoverRunningRuns(currentHostSessionId) {
-        return this.recoverDeadSessionRuns(currentHostSessionId);
+        // 重启恢复：仅持有者身份的打开方在构造阶段收割死亡会话遗留的非终态运行；
+        // 旁观查询打开保持只读语义，绝不触碰其他进程的在途记录
+        if (this.recoverOrphans) {
+            this.recoverDeadSessionRuns();
+        }
     }
     /**
      * 收敛死亡会话遗留的非终态运行任务。
@@ -176,7 +187,8 @@ export class SqliteRuntimeStorage {
             const res = stmt.run(...params);
             return res.changes;
         }
-        catch {
+        catch (err) {
+            console.warn(`[actiondock] recoverDeadSessionRuns failed: ${err instanceof Error ? err.message : String(err)}`);
             return 0;
         }
     }
@@ -198,24 +210,14 @@ export class SqliteRuntimeStorage {
         if (!row || row.value_json === undefined || row.value_json === null) {
             return undefined;
         }
-        try {
-            return JSON.parse(row.value_json);
-        }
-        catch {
-            return row.value_json;
-        }
+        return safeParseStoredJson(row.value_json, `config db=${this.dbPath} package=${this.packageId} key=${key}`);
     }
     listConfig() {
         const stmt = this.getStatement("SELECT key, value_json FROM config WHERE package_id = ?");
         const rows = stmt.all(this.packageId);
         const result = {};
         for (const row of rows) {
-            try {
-                result[row.key] = JSON.parse(row.value_json);
-            }
-            catch {
-                result[row.key] = row.value_json;
-            }
+            result[row.key] = safeParseStoredJson(row.value_json, `config db=${this.dbPath} package=${this.packageId} key=${row.key}`);
         }
         return result;
     }
@@ -250,12 +252,7 @@ export class SqliteRuntimeStorage {
                 return undefined;
             }
         }
-        try {
-            return JSON.parse(row.value_json);
-        }
-        catch {
-            return row.value_json;
-        }
+        return safeParseStoredJson(row.value_json, `state db=${this.dbPath} package=${this.packageId} namespace=${namespace} key=${key}`);
     }
     async findMatchingStateRows(targetKey) {
         let decoded;
@@ -311,13 +308,7 @@ export class SqliteRuntimeStorage {
             return undefined;
         }
         const row = matchingRows[0];
-        let parsedVal;
-        try {
-            parsedVal = JSON.parse(row.value_json);
-        }
-        catch {
-            parsedVal = row.value_json;
-        }
+        const parsedVal = safeParseStoredJson(row.value_json, `state db=${this.dbPath} package=${this.packageId} namespace=${row.namespace} key=${row.key}`);
         return {
             packageId: this.packageId,
             namespace: row.namespace,
@@ -365,18 +356,32 @@ export class SqliteRuntimeStorage {
         return this.deleteState("", targetKey);
     }
     /**
-     * 清理已过期的状态记录
+     * 清理已过期的状态记录。
+     *
+     * 同时按 TargetInfo.idempotencyPolicy 声明的 24 小时保留窗口，
+     * 清理 idempotency_keys 表中超过保留期的幂等去重记录，
+     * 保证承诺的 retentionMs 策略与实际清理逻辑一致。
      */
     async cleanExpiredState() {
         if (this.isClosed)
             return 0;
         try {
-            const now = this.clock.now().toISOString();
+            const now = this.clock.now();
             const stmt = this.getStatement("DELETE FROM state WHERE package_id = ? AND expires_at IS NOT NULL AND expires_at <= ?");
-            const res = stmt.run(this.packageId, now);
+            const res = stmt.run(this.packageId, now.toISOString());
+            // 幂等去重记录保留窗口与 info() 声明的 retentionMs（24 小时）保持一致
+            const retentionCutoff = new Date(now.getTime() - IDEMPOTENCY_RETENTION_MS).toISOString();
+            try {
+                this.getStatement("DELETE FROM idempotency_keys WHERE created_at < ?").run(retentionCutoff);
+            }
+            catch (err) {
+                // 独立记录幂等清理失败，不影响状态清理主路径的返回语义
+                console.warn(`[actiondock] idempotency retention cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
             return res.changes;
         }
-        catch {
+        catch (err) {
+            console.warn(`[actiondock] cleanExpiredState failed: ${err instanceof Error ? err.message : String(err)}`);
             return 0;
         }
     }
@@ -449,13 +454,7 @@ export class SqliteRuntimeStorage {
             if (row.expires_at && now >= new Date(row.expires_at).getTime()) {
                 continue;
             }
-            let parsedVal;
-            try {
-                parsedVal = JSON.parse(row.value_json);
-            }
-            catch {
-                parsedVal = row.value_json;
-            }
+            const parsedVal = safeParseStoredJson(row.value_json, `state db=${this.dbPath} package=${this.packageId} namespace=${row.namespace} key=${row.key}`);
             results.push({
                 packageId: this.packageId,
                 namespace: row.namespace,
@@ -505,7 +504,12 @@ export class SqliteRuntimeStorage {
             END
         WHERE id = ? AND status = 'running'
       `);
-            stmt.run(status, output !== undefined ? JSON.stringify(output) : null, error ? JSON.stringify(error) : null, finishIso, finishIso, id);
+            const res = stmt.run(status, output !== undefined ? JSON.stringify(output) : null, error ? JSON.stringify(error) : null, finishIso, finishIso, id);
+            // 命中零行且新状态为终态：说明该记录已不再处于 running 状态（被其他持有者进程或
+            // 恢复流程改写），本次终态写入被丢弃；保持返回值语义不变，仅输出告警保证漂移可观测
+            if (res.changes === 0 && isTerminalRunStatus(status)) {
+                console.warn(`[actiondock] updateRun matched 0 rows: run '${id}' is no longer 'running' in db=${this.dbPath}; terminal status '${status}' was not persisted (record likely settled or recovered by another holder process)`);
+            }
         }
         catch (err) {
             if (this.isClosed)
@@ -523,25 +527,20 @@ export class SqliteRuntimeStorage {
     }
     listRuns(options = {}) {
         const limit = options.limit || 50;
-        let rows;
+        let sql = "SELECT * FROM runs WHERE package_id = ?";
+        const params = [this.packageId];
         if (options.actionId) {
-            const stmt = this.getStatement(`
-        SELECT * FROM runs
-        WHERE package_id = ? AND action_id = ?
-        ORDER BY started_at DESC
-        LIMIT ?
-      `);
-            rows = stmt.all(this.packageId, options.actionId, limit);
+            sql += " AND action_id = ?";
+            params.push(options.actionId);
         }
-        else {
-            const stmt = this.getStatement(`
-        SELECT * FROM runs
-        WHERE package_id = ?
-        ORDER BY started_at DESC
-        LIMIT ?
-      `);
-            rows = stmt.all(this.packageId, limit);
+        if (options.status) {
+            sql += " AND status = ?";
+            params.push(options.status);
         }
+        sql += " ORDER BY started_at DESC LIMIT ?";
+        params.push(limit);
+        const stmt = this.getStatement(sql);
+        const rows = stmt.all(...params);
         return rows.map((r) => this.mapRunRecord(r));
     }
     clearRuns(options = {}) {
@@ -561,7 +560,10 @@ export class SqliteRuntimeStorage {
         try {
             this.getStatement("DELETE FROM idempotency_keys WHERE run_id NOT IN (SELECT id FROM runs)").run();
         }
-        catch { }
+        catch (err) {
+            // 孤立索引清理失败不影响主清理结果的返回语义，但必须可观测
+            console.warn(`[actiondock] orphaned idempotency keys cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
         return res.changes;
     }
     // --- Idempotency 幂等去重管理 ---
@@ -634,27 +636,16 @@ export class SqliteRuntimeStorage {
         };
     }
     mapRunRecord(row) {
-        let input;
-        let output;
-        let error;
-        try {
-            input = row.input_json ? JSON.parse(row.input_json) : undefined;
-        }
-        catch {
-            input = row.input_json;
-        }
-        try {
-            output = row.output_json ? JSON.parse(row.output_json) : undefined;
-        }
-        catch {
-            output = row.output_json;
-        }
-        try {
-            error = row.error_json ? JSON.parse(row.error_json) : undefined;
-        }
-        catch {
-            error = undefined;
-        }
+        // 保留旧有的真值判断：空字符串列视为未存储，与历史行为一致
+        const input = safeParseStoredJson(row.input_json || undefined, `runs.input db=${this.dbPath} package=${this.packageId} run=${row.id}`);
+        const output = safeParseStoredJson(row.output_json || undefined, `runs.output db=${this.dbPath} package=${this.packageId} run=${row.id}`);
+        // error_json 损坏时保留原始文本到 message 字段，避免错误信息丢失
+        const error = safeParseStoredJson(row.error_json || undefined, `runs.error db=${this.dbPath} package=${this.packageId} run=${row.id}`);
+        const normalizedError = error !== undefined
+            ? typeof error === "object" && error !== null && typeof error.message === "string"
+                ? error
+                : { code: "STORED_ERROR_DECODE_FAILED", message: String(error) }
+            : undefined;
         return {
             id: row.id,
             rootRunId: row.root_run_id || row.id,
@@ -682,8 +673,9 @@ export class SqliteRuntimeStorage {
         try {
             this.driver.close();
         }
-        catch {
-            // 忽略重复关闭异常
+        catch (err) {
+            // 驱动关闭异常必须可观测，但不再重复抛出以免阻断上层关停链路
+            console.warn(`[actiondock] storage close failed (db=${this.dbPath}): ${err instanceof Error ? err.message : String(err)}`);
         }
     }
 }

package/dist/storage/types.d.ts

@@ -1,9 +1,14 @@
-import type { RuntimeError, RunRecord } from "@actiondock/sdk";
-import type { Clock } from "../runtime/clock.js";
+import type { RuntimeError, RunRecord, RunStatus } from "@actiondock/sdk";
+import type { Clock } from "./clock.js";
 /**
  * 固定的存储 Schema 目标版本常量。
  */
 export declare const STORAGE_SCHEMA_VERSION = 2;
+/**
+ * 幂等去重记录保留窗口（24 小时），与 LocalActionDockTarget.info()
+ * 声明的 idempotencyPolicy.retentionMs 承诺保持单一事实源。
+ */
+export declare const IDEMPOTENCY_RETENTION_MS = 86400000;
 /**
  * SQLite 基础参数值类型。
  */
@@ -82,6 +87,14 @@ export interface StorageOptions {
     driver?: SqliteDriver;
     /** 可选注入的时间提供器，便于与模拟时钟联动 */
     clock?: Clock;
+    /**
+     * 是否在打开时收割死亡会话遗留的非终态运行记录（收敛为 interrupted）。
+     *
+     * 默认 false：旁观查询打开（CLI 的 state/runs/config 类命令）不收割其他进程的在途记录。
+     * 仅数据目录持有者（serve、mcp、ad run 等执行宿主）显式置 true，
+     * 避免跨进程互毁在途运行。
+     */
+    recoverOrphans?: boolean;
 }
 /**
  * 数据库中存储的幂等请求去重记录实体。
@@ -120,6 +133,13 @@ export type TerminalRunStatus = "success" | "failed" | "cancelled" | "timed_out"
  * 判断指定运行状态是否为终态（收敛 success, failed, cancelled, timed_out, interrupted）。
  */
 export declare function isTerminalRunStatus(status: string): status is TerminalRunStatus;
+/**
+ * 执行终态到运行记录状态的统一映射单一事实源。
+ *
+ * 成功映射为 success；超时错误码映射为 timed_out；取消错误码映射为 cancelled；
+ * 其余失败一律映射为 failed。错误码常量来自全仓统一错误码单一事实源 errors.ts。
+ */
+export declare function resultStatusToRunStatus(ok: boolean, errorCode?: string): RunStatus;
 /**
  * 统一运行时存储抽象接口。
  */
@@ -153,15 +173,17 @@ export interface RuntimeStorage {
     getRun(id: string): RunRecord | null;
     listRuns(options?: {
         actionId?: string;
+        status?: string;
         limit?: number;
     }): RunRecord[];
     clearRuns(options?: {
         actionId?: string;
         status?: string;
     }): number;
-    /** 故障重启恢复：将遗留非终态运行收敛为 interrupted */
-    recoverRunningRuns?(currentHostSessionId?: string): number | Promise<number>;
-    /** 收敛死亡会话遗留的非终态运行任务 */
+    /**
+     * 收敛死亡会话遗留的非终态运行任务（含无会话标识的遗留非终态记录），
+     * 统一收敛为 interrupted。历史别名 recoverRunningRuns 已合并至本方法。
+     */
     recoverDeadSessionRuns?(currentHostSessionId?: string): number | Promise<number>;
     /** 确保底层存储与 Schema 初始化完成 */
     ensureInitialized?(): Promise<void>;

package/dist/storage/types.js

@@ -1,7 +1,13 @@
+import { ACTION_CANCELLED, ACTION_TIMEOUT } from "../errors.js";
 /**
  * 固定的存储 Schema 目标版本常量。
  */
 export const STORAGE_SCHEMA_VERSION = 2;
+/**
+ * 幂等去重记录保留窗口（24 小时），与 LocalActionDockTarget.info()
+ * 声明的 idempotencyPolicy.retentionMs 承诺保持单一事实源。
+ */
+export const IDEMPOTENCY_RETENTION_MS = 86_400_000;
 /**
  * 判断指定运行状态是否为终态（收敛 success, failed, cancelled, timed_out, interrupted）。
  */
@@ -12,3 +18,18 @@ export function isTerminalRunStatus(status) {
         status === "timed_out" ||
         status === "interrupted");
 }
+/**
+ * 执行终态到运行记录状态的统一映射单一事实源。
+ *
+ * 成功映射为 success；超时错误码映射为 timed_out；取消错误码映射为 cancelled；
+ * 其余失败一律映射为 failed。错误码常量来自全仓统一错误码单一事实源 errors.ts。
+ */
+export function resultStatusToRunStatus(ok, errorCode) {
+    if (ok)
+        return "success";
+    if (errorCode === ACTION_TIMEOUT)
+        return "timed_out";
+    if (errorCode === ACTION_CANCELLED)
+        return "cancelled";
+    return "failed";
+}

package/dist/storage/utils.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 存储层 JSON 载荷统一安全解析工具。
+ *
+ * 单一事实源：所有从 SQLite 读出的 JSON 字段（config.value_json、
+ * state.value_json、runs.input_json / output_json / error_json 等）
+ * 禁止在各自调用点散落 try/catch 静默降级，统一经由本函数完成
+ * 「解析 + 可观测告警 + 保守降级」的完整链路。
+ */
+/**
+ * 解析存储层 JSON 字符串，失败时输出单行警告并保守返回原始字符串。
+ *
+ * 降级策略说明：各调用方的返回类型为业务泛型 T，无法以标记对象区分
+ * 损坏数据，因此保持「返回原始字符串」的既有降级行为，但通过
+ * console.warn 保证损坏事件可观测，不再无声吞没。警告仅携带
+ * 上下文描述与解析失败原因，不输出完整原始值，避免敏感数据
+ * 泄漏到日志。
+ *
+ * @param raw 存储层原始 JSON 字符串
+ * @param context 存储路径上下文描述（包含数据库位置、包标识与键名）
+ * @returns 解析成功返回解析后的值；入参为空返回 undefined；解析失败返回原始字符串
+ */
+export declare function safeParseStoredJson<T = unknown>(raw: string | null | undefined, context: string): T | undefined;

package/dist/storage/utils.js

@@ -0,0 +1,34 @@
+/**
+ * 存储层 JSON 载荷统一安全解析工具。
+ *
+ * 单一事实源：所有从 SQLite 读出的 JSON 字段（config.value_json、
+ * state.value_json、runs.input_json / output_json / error_json 等）
+ * 禁止在各自调用点散落 try/catch 静默降级，统一经由本函数完成
+ * 「解析 + 可观测告警 + 保守降级」的完整链路。
+ */
+/**
+ * 解析存储层 JSON 字符串，失败时输出单行警告并保守返回原始字符串。
+ *
+ * 降级策略说明：各调用方的返回类型为业务泛型 T，无法以标记对象区分
+ * 损坏数据，因此保持「返回原始字符串」的既有降级行为，但通过
+ * console.warn 保证损坏事件可观测，不再无声吞没。警告仅携带
+ * 上下文描述与解析失败原因，不输出完整原始值，避免敏感数据
+ * 泄漏到日志。
+ *
+ * @param raw 存储层原始 JSON 字符串
+ * @param context 存储路径上下文描述（包含数据库位置、包标识与键名）
+ * @returns 解析成功返回解析后的值；入参为空返回 undefined；解析失败返回原始字符串
+ */
+export function safeParseStoredJson(raw, context) {
+    if (raw === null || raw === undefined) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        console.warn(`[actiondock] stored JSON corrupted at ${context}: ${reason}`);
+        return raw;
+    }
+}

package/dist/target/local.d.ts

@@ -34,6 +34,7 @@ export declare class LocalActionDockTarget implements ActionDockTarget {
         maxQueueSize?: number;
     }): AsyncIterable<ExecutionEvent>;
     private resolveApp;
+    private fallbackGlobalStorage?;
     private getGlobalStorage;
     private findDeclaredConfigItem;
     getConfig(packageId: string, key: string): Promise<ConfigValueView>;

package/dist/target/local.js

@@ -89,10 +89,12 @@ export class LocalActionDockTarget {
             const apps = options?.packageId
                 ? [this.target.getApp(options.packageId)].filter(Boolean)
                 : this.target.listApps();
-            let records = [];
+            const records = [];
             for (const app of apps) {
+                // 状态过滤下推到存储层 SQL，避免先分页后过滤导致某包前 N 条非目标状态时贡献 0 条
                 const recs = app.storage.listRuns({
                     actionId: options?.actionId,
+                    status: options?.status,
                     limit: options?.limit,
                 });
                 for (const r of recs) {
@@ -103,11 +105,9 @@ export class LocalActionDockTarget {
                 }
             }
             records.sort((a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime());
-            if (options?.status) {
-                records = records.filter((r) => r.status === options.status);
-            }
+            // 全局 limit 语义：合并后总条数不超过 limit，单处截断
             if (options?.limit && records.length > options.limit) {
-                records = records.slice(0, options.limit);
+                records.length = options.limit;
             }
             return records;
         }
@@ -115,17 +115,12 @@ export class LocalActionDockTarget {
             if (options?.packageId && options.packageId !== this.target.packageId) {
                 return [];
             }
-            let records = this.target.storage.listRuns({
+            // 状态过滤下推到存储层 SQL，单包场景由数据库直接返回目标状态记录
+            return this.target.storage.listRuns({
                 actionId: options?.actionId,
+                status: options?.status,
                 limit: options?.limit,
             });
-            if (options?.status) {
-                records = records.filter((r) => r.status === options.status);
-            }
-            if (options?.limit && records.length > options.limit) {
-                records = records.slice(0, options.limit);
-            }
-            return records;
         }
     }
     async clearRuns(options) {
@@ -176,6 +171,7 @@ export class LocalActionDockTarget {
             return undefined;
         }
     }
+    fallbackGlobalStorage;
     getGlobalStorage() {
         if ("globalStorage" in this.target && this.target.globalStorage) {
             return this.target.globalStorage;
@@ -185,10 +181,13 @@ export class LocalActionDockTarget {
             if (app.globalStorage)
                 return app.globalStorage;
         }
-        return createGlobalStorage({
-            dataDir: this.target.options?.dataDir,
-            customHome: this.target.options?.customHome,
-        });
+        if (!this.fallbackGlobalStorage) {
+            this.fallbackGlobalStorage = createGlobalStorage({
+                dataDir: this.target.options?.dataDir,
+                customHome: this.target.options?.customHome,
+            });
+        }
+        return this.fallbackGlobalStorage;
     }
     findDeclaredConfigItem(key) {
         if ("listApps" in this.target) {
@@ -323,6 +322,13 @@ export class LocalActionDockTarget {
         return app.storage.listStateEntries(options);
     }
     async close(options) {
+        try {
+            this.fallbackGlobalStorage?.close();
+        }
+        catch {
+            // 忽略兜底全局存储关闭异常
+        }
+        this.fallbackGlobalStorage = undefined;
         if (options?.timeoutMs && options.timeoutMs > 0) {
             let timer;
             const timeoutPromise = new Promise((_, reject) => {

package/dist/target/remote-errors.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 远端通信错误翻译层。
+ *
+ * 职责单一：将 profile/client 传输层抛出的底层异常翻译为统一的
+ * TargetError 结构化异常，供 RemoteActionDockTarget 各操作边界复用；
+ * 优先读取传输层透传的结构化错误码，无法识别时原样透传。
+ */
+/**
+ * 将远端通信异常包装翻译为统一的 TargetError。
+ *
+ * 无法识别的异常按防御与透明原则原样抛出，严禁静默吞没。
+ */
+export declare function wrapRemoteError(err: any): never;
+/**
+ * 判定远端状态键访问异常是否为键不存在。
+ *
+ * 优先读取传输层透传的结构化错误码（fetchRemoteJson 会将响应体 error.code
+ * 附加到抛出异常的 code 字段），仅当旧版服务器未透传 code 时回退到
+ * HTTP 状态与消息文本兼容嗅探。
+ */
+export declare function isRemoteStateKeyNotFound(err: any): boolean;