principles-disciple 1.126.0 → 1.128.0

package/dist/service/workflow-watchdog.js

@@ -0,0 +1,103 @@
+/**
+ * Workflow Watchdog - Extracted from evolution-worker.ts (lines 79-223)
+ *
+ * Detects stale/orphaned workflows, invalid results, and cleanup failures.
+ * Runs every heartbeat cycle, catching bugs like:
+ *   #185 — orphaned active workflows
+ *   #181 — structurally invalid results (all zeros)
+ *   #180/#183 — expired workflows not swept
+ *   #182 — unhandled rejections leaving workflows in limbo
+ *
+ * BUG-01: isExpectedSubagentError guard prevents marking daemon-mode stale
+ *         workflows as terminal_error (line 122)
+ * BUG-02: Gateway fallback cleans up child sessions via agentSession when
+ *         subagentRuntime unavailable (lines 148-156)
+ */
+import { WorkflowStore } from './subagent-workflow/workflow-store.js';
+import { isExpectedSubagentError } from './subagent-workflow/subagent-error-utils.js';
+import { WORKFLOW_TTL_MS } from '../config/defaults/runtime.js';
+export async function runWorkflowWatchdog(wctx, api, logger) {
+    const details = [];
+    const now = Date.now();
+    const subagentRuntime = api?.runtime?.subagent;
+    const agentSession = api?.runtime?.agent?.session;
+    try {
+        const store = new WorkflowStore({ workspaceDir: wctx.workspaceDir });
+        try {
+            const allWorkflows = store.listWorkflows();
+            const staleThreshold = WORKFLOW_TTL_MS * 2;
+            const staleActive = allWorkflows.filter((wf) => wf.state === 'active' && (now - wf.created_at) > staleThreshold);
+            if (staleActive.length > 0) {
+                for (const wf of staleActive) {
+                    const ageMin = Math.round((now - wf.created_at) / 60000);
+                    details.push(`stale_active: ${wf.workflow_id} (${wf.workflow_type}, ${ageMin}min old)`);
+                    const events = store.getEvents(wf.workflow_id);
+                    const lastEventReason = events.length > 0 ? events[events.length - 1].reason : 'unknown';
+                    if (isExpectedSubagentError(lastEventReason)) {
+                        logger?.debug?.(`[PD:Watchdog] Skipping stale active workflow ${wf.workflow_id}: expected subagent error (${lastEventReason})`);
+                        continue;
+                    }
+                    store.updateWorkflowState(wf.workflow_id, 'terminal_error');
+                    store.recordEvent(wf.workflow_id, 'watchdog_timeout', 'active', 'terminal_error', `Stale active > ${staleThreshold / 60000}s`, { ageMs: now - wf.created_at });
+                    if (wf.child_session_key) {
+                        try {
+                            if (subagentRuntime) {
+                                await subagentRuntime.deleteSession({ sessionKey: wf.child_session_key, deleteTranscript: true });
+                                logger?.info?.(`[PD:Watchdog] Cleaned up stale session: ${wf.child_session_key}`);
+                            }
+                            else if (agentSession) {
+                                const storePath = agentSession.resolveStorePath();
+                                const sessionStore = agentSession.loadSessionStore(storePath, { skipCache: true });
+                                const normalizedKey = wf.child_session_key.toLowerCase();
+                                if (sessionStore[normalizedKey]) {
+                                    delete sessionStore[normalizedKey];
+                                    await agentSession.saveSessionStore(storePath, sessionStore);
+                                    logger?.info?.(`[PD:Watchdog] Cleaned up stale session via agentSession fallback: ${wf.child_session_key}`);
+                                }
+                            }
+                        }
+                        catch (cleanupErr) {
+                            const errMsg = String(cleanupErr);
+                            if (errMsg.includes('gateway request') && agentSession) {
+                                const storePath = agentSession.resolveStorePath();
+                                const sessionStore = agentSession.loadSessionStore(storePath, { skipCache: true });
+                                const normalizedKey = wf.child_session_key.toLowerCase();
+                                if (sessionStore[normalizedKey]) {
+                                    delete sessionStore[normalizedKey];
+                                    await agentSession.saveSessionStore(storePath, sessionStore);
+                                    logger?.info?.(`[PD:Watchdog] Cleaned up stale session via agentSession fallback after gateway error: ${wf.child_session_key}`);
+                                }
+                            }
+                            else {
+                                logger?.warn?.(`[PD:Watchdog] Failed to cleanup session ${wf.child_session_key}: ${errMsg}`);
+                            }
+                        }
+                    }
+                }
+            }
+            const unclearedTerminal = allWorkflows.filter((wf) => (wf.state === 'terminal_error' || wf.state === 'expired') && wf.cleanup_state === 'pending');
+            if (unclearedTerminal.length > 0) {
+                details.push(`uncleared_terminal: ${unclearedTerminal.length} workflows (will be swept next cycle)`);
+            }
+            const stateCounts = {};
+            for (const wf of allWorkflows) {
+                stateCounts[wf.state] = (stateCounts[wf.state] || 0) + 1;
+            }
+            const stateSummary = Object.entries(stateCounts).map(([s, c]) => `${s}=${c}`).join(', ');
+            if (details.length === 0) {
+                logger?.debug?.(`[PD:Watchdog] OK — ${allWorkflows.length} workflows (${stateSummary})`);
+            }
+            else {
+                logger?.info?.(`[PD:Watchdog] ${details.length} anomalies — ${allWorkflows.length} workflows (${stateSummary})`);
+            }
+        }
+        finally {
+            store.dispose();
+        }
+    }
+    catch (err) {
+        logger?.warn?.(`[PD:Watchdog] Failed to scan workflows: ${String(err)}`);
+        return { anomalies: -1, details: [], scanError: String(err) };
+    }
+    return { anomalies: details.length, details };
+}

package/dist/types/event-types.d.ts

@@ -0,0 +1,2 @@
+export type { EventType, EventCategory, EventLogEntry, ToolCallEventData, PainSignalEventData, RuleMatchEventData, RulePromotionEventData, HookExecutionEventData, GateBlockEventData, GateBypassEventData, PlanApprovalEventData, EvolutionTaskEventData, EmpathyRollbackEventData, HeartbeatDiagnosisEventData, DiagnosisTaskEventData, DiagnosticianReportEventData, PrincipleCandidateEventData, RuleEnforcedEventData, RuleHostEvaluatedEventData, RuleHostBlockedEventData, RuleHostRequireApprovalEventData, RuleHostAutoCorrectProposedEventData, RuleHostAutoCorrectAppliedEventData, RuntimeV2PromptActivationsInjectedEventData, RuleHostUnhealthyEventData, ToolCallStats, ErrorStats, PainStats, EmpathyEventStats, GfiStats, EvolutionStats as EventEvolutionStats, HookStats, DailyStats, } from '@principles/core/runtime-v2';
+export { createEmptyDailyStats, } from '@principles/core/runtime-v2';

package/dist/types/event-types.js

@@ -0,0 +1 @@
+export { createEmptyDailyStats, } from '@principles/core/runtime-v2';

package/dist/types/hygiene-types.d.ts

@@ -0,0 +1,2 @@
+export type { PersistenceAction, HygieneStats, } from '@principles/core/runtime-v2';
+export { createEmptyHygieneStats, } from '@principles/core/runtime-v2';

package/dist/types/hygiene-types.js

@@ -0,0 +1 @@
+export { createEmptyHygieneStats, } from '@principles/core/runtime-v2';

package/{src/types/principle-tree-schema.ts → dist/types/principle-tree-schema.d.ts}

@@ -21,32 +21,9 @@
  *   - Monitor principles deprecated (solidified into code/weights)
  *   - Track principle value ranking (pain prevented, adherence rate)
  */
-
 import type { Principle as CorePrinciple } from '@principles/core/runtime-v2';
 import type { PrincipleDetectorSpec } from '../core/evolution-types.js';
-
-// Re-exported from core (PRI-51) for plugin consumers
-export type {
-  PrinciplePriority,
-  PrincipleScope,
-  PrincipleEvaluability,
-  RuleStatus,
-  RuleType,
-  ImplementationLifecycleState,
-  ImplementationType,
-  Rule,
-  Implementation,
-  PrincipleDependency,
-  PrincipleValueMetrics,
-  PrincipleEventType,
-  PrincipleLifecycleEvent,
-  PrincipleTreeStore,
-} from '@principles/core/runtime-v2';
-
-// =========================================================================
-// 1. PRINCIPLE (Tree Root) — Highly abstract, cross-scenario, value-driven
-// =========================================================================
-
+export type { PrinciplePriority, PrincipleScope, PrincipleEvaluability, RuleStatus, RuleType, ImplementationLifecycleState, ImplementationType, Rule, Implementation, PrincipleDependency, PrincipleValueMetrics, PrincipleEventType, PrincipleLifecycleEvent, PrincipleTreeStore, } from '@principles/core/runtime-v2';
 export interface Principle extends CorePrinciple {
-  detectorMetadata?: PrincipleDetectorSpec;
+    detectorMetadata?: PrincipleDetectorSpec;
 }

package/dist/types/principle-tree-schema.js

@@ -0,0 +1,24 @@
+/**
+ * Principle-Tree Schema Design
+ *
+ * Concept: Principles are the root of a tree that branches into Rules
+ * and eventually into concrete Implementations (code, skills, LoRA weights).
+ *
+ * A principle without supporting rules is an empty concept — LLM may ignore it.
+ * A rule without a parent principle lacks strategic direction.
+ *
+ * Lifecycle:
+ *   Pain Signal → Diagnosis → Principle (root)
+ *                              ↓
+ *                         Rule (trunk)
+ *                              ↓
+ *                    Implementation (leaf)
+ *                              ↓
+ *                    Rule 100% covered → Principle deprecated
+ *
+ * User Focus:
+ *   - Monitor new principles added by diagnostician
+ *   - Monitor principles deprecated (solidified into code/weights)
+ *   - Track principle value ranking (pain prevented, adherence rate)
+ */
+export {};

package/dist/types/queue.d.ts

@@ -0,0 +1,2 @@
+export type { Brand, QueueItemId, WorkflowId, SessionKey, } from '@principles/core/runtime-v2';
+export { toQueueItemId, toWorkflowId, toSessionKey, isQueueItemId, isWorkflowId, isSessionKey, } from '@principles/core/runtime-v2';

package/dist/types/queue.js

@@ -0,0 +1 @@
+export { toQueueItemId, toWorkflowId, toSessionKey, isQueueItemId, isWorkflowId, isSessionKey, } from '@principles/core/runtime-v2';

package/dist/types/runtime-summary.d.ts

@@ -0,0 +1 @@
+export type { RuntimeTruth, AnalyticsTruth, TrendMetrics, } from '@principles/core/runtime-v2';

package/dist/types/runtime-summary.js

@@ -0,0 +1 @@
+export {};

package/dist/types.d.ts

@@ -0,0 +1,33 @@
+export type { PluginCommandContext, PluginCommandResult } from './openclaw-sdk.js';
+/**
+ * Context Injection Configuration
+ * Controls what content gets injected into the LLM prompt.
+ *
+ * NOTE: Core Principles (PRINCIPLES.md) are ALWAYS injected and cannot be disabled.
+ * This is by design - principles are the foundation of the agent's behavior.
+ */
+export type ProjectFocusMode = 'full' | 'summary' | 'off';
+export interface EvolutionContextConfig {
+    /** Enable conversation context in evolution task (default: true) */
+    enabled: boolean;
+    /** Max recent messages included in evolution task (default: 4) */
+    maxMessages: number;
+    /** Max chars per message snippet (default: 200) */
+    maxCharsPerMessage: number;
+}
+export interface ContextInjectionConfig {
+    /** Thinking OS (mental models) - can be toggled */
+    thinkingOs: boolean;
+    /** Project context (CURRENT_FOCUS.md) mode */
+    projectFocus: ProjectFocusMode;
+    /** Evolution task context injection settings */
+    evolutionContext: EvolutionContextConfig;
+}
+/**
+ * Default context injection configuration
+ * Based on MVP-first strategy (ADR-0014):
+ * - principles: always on (not configurable)
+ * - thinkingOs: false by default (MVP-Quiet, user can opt-in via /pd-context)
+ * - projectFocus: 'off' (default closed, user can enable)
+ */
+export declare const defaultContextConfig: ContextInjectionConfig;

package/dist/types.js

@@ -0,0 +1,16 @@
+/**
+ * Default context injection configuration
+ * Based on MVP-first strategy (ADR-0014):
+ * - principles: always on (not configurable)
+ * - thinkingOs: false by default (MVP-Quiet, user can opt-in via /pd-context)
+ * - projectFocus: 'off' (default closed, user can enable)
+ */
+export const defaultContextConfig = {
+    thinkingOs: false,
+    projectFocus: 'off',
+    evolutionContext: {
+        enabled: true,
+        maxMessages: 4,
+        maxCharsPerMessage: 200,
+    },
+};

package/dist/utils/file-lock.d.ts

@@ -0,0 +1,68 @@
+export interface LockOptions {
+    /** 最大重试次数，默认 50 */
+    maxRetries?: number;
+    /** 基础重试延迟(ms)，默认 10 */
+    baseRetryDelayMs?: number;
+    /** 最大重试延迟(ms)，默认 500 */
+    maxRetryDelayMs?: number;
+    /** 锁过期时间(ms)，默认 10000 (10秒) */
+    lockStaleMs?: number;
+    /** 锁文件后缀，默认 '.lock' */
+    lockSuffix?: string;
+}
+export interface LockContext {
+    /** 锁文件路径 */
+    lockPath: string;
+    /** 持有锁的 PID */
+    pid: number;
+    /** 获取锁的时间 */
+    acquiredAt: number;
+}
+export declare class LockAcquisitionError extends Error {
+    readonly filePath: string;
+    readonly lockPath: string;
+    constructor(message: string, filePath: string, lockPath: string);
+}
+/**
+ * 获取文件锁
+ *
+ * @param filePath 要锁定的文件路径
+ * @param options 锁选项
+ * @returns 锁上下文（用于后续释放）
+ * @throws Error 如果无法获取锁
+ */
+export declare function acquireLock(filePath: string, options?: LockOptions): LockContext;
+export declare function acquireLockAsync(filePath: string, options?: LockOptions): Promise<LockContext>;
+/**
+ * 释放文件锁
+ *
+ * @param ctx 锁上下文（由 acquireLock 返回）
+ */
+export declare function releaseLock(ctx: LockContext): void;
+/**
+ * 使用锁执行操作（自动获取和释放）
+ *
+ * @param filePath 要锁定的文件路径
+ * @param fn 要执行的操作
+ * @param options 锁选项
+ * @returns 操作的返回值
+ */
+export declare function withLock<T>(filePath: string, fn: () => T, options?: LockOptions): T;
+export declare function withLockAsync<T>(filePath: string, fn: () => Promise<T>, options?: LockOptions): Promise<T>;
+/**
+ * 异步版本的文件锁（使用 Promise 链）
+ *
+ * 注意：这是一个简化的实现，适用于单进程内的异步并发控制
+ * 对于多进程场景，应使用同步版本的 acquireLock
+ */
+export declare const asyncLockQueues: Map<string, Promise<void>>;
+export declare function withAsyncLock<T>(filePath: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * 检查锁状态（用于调试）
+ */
+export declare function getLockStatus(filePath: string, options?: LockOptions): {
+    locked: boolean;
+    holderPid: number | null;
+    holderAlive: boolean;
+    lockAge: number | null;
+};

package/dist/utils/file-lock.js

@@ -0,0 +1,310 @@
+/**
+ * Reliable File Lock - 可靠的文件锁实现
+ *
+ * 设计原则：
+ * 1. 使用 O_EXCL | O_CREAT 实现真正的原子锁获取
+ * 2. PID 存活检测避免死锁
+ * 3. 带退避的重试机制
+ * 4. 锁获取后二次验证
+ * 5. 数据不丢失：失败时抛出异常而非静默返回
+ */
+/* global NodeJS */
+import * as fs from 'fs';
+import * as path from 'path';
+export class LockAcquisitionError extends Error {
+    filePath;
+    lockPath;
+    constructor(message, filePath, lockPath) {
+        super(message);
+        this.name = 'LockAcquisitionError';
+        this.filePath = filePath;
+        this.lockPath = lockPath;
+    }
+}
+/** 默认锁选项 */
+const DEFAULT_OPTIONS = {
+    maxRetries: 50,
+    baseRetryDelayMs: 10,
+    maxRetryDelayMs: 500,
+    lockStaleMs: 10000,
+    lockSuffix: '.lock',
+};
+/**
+ * 检查进程是否存活
+ */
+function isProcessAlive(pid) {
+    try {
+        // 发送信号 0 不会真正发送信号，只检查进程是否存在
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 原子创建锁文件
+ * 使用 O_EXCL | O_CREAT 确保原子性
+ *
+ * @returns true 表示成功获取锁，false 表示锁被占用
+ */
+function tryAcquireLock(lockPath, pid) {
+    try {
+        // 确保锁文件的目录存在
+        const lockDir = path.dirname(lockPath);
+        if (!fs.existsSync(lockDir)) {
+            fs.mkdirSync(lockDir, { recursive: true });
+        }
+        // 使用 fs.constants 获取正确的 flag 值
+        // O_EXCL: 排他创建 - 与 O_CREAT 一起使用时，如果文件存在则失败
+        // O_CREAT: 文件不存在时创建
+        // O_WRONLY: 只写模式
+        const flags = fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL;
+        // 使用底层的 openSync 实现真正的原子操作
+        // 如果文件已存在，会抛出 EEXIST 错误
+        const fd = fs.openSync(lockPath, flags);
+        // 写入 PID
+        fs.writeSync(fd, String(pid));
+        fs.fsyncSync(fd); // 确保数据落盘
+        fs.closeSync(fd);
+        return true;
+    }
+    catch (err) {
+        if (err.code === 'EEXIST') {
+            return false; // 锁已被占用
+        }
+        // 其他错误（权限、磁盘满等）向上抛出
+        throw err;
+    }
+}
+/**
+ * 读取锁文件中的 PID
+ * @returns PID 或 null（如果文件不存在或无法解析）
+ */
+function readLockPid(lockPath) {
+    try {
+        const content = fs.readFileSync(lockPath, 'utf8');
+        const pid = parseInt(content.trim(), 10);
+        return Number.isNaN(pid) ? null : pid;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 安全删除锁文件
+ * 只有当锁文件包含当前进程的 PID 时才删除
+ */
+function safeReleaseLock(lockPath, expectedPid) {
+    try {
+        const pid = readLockPid(lockPath);
+        if (pid === expectedPid) {
+            fs.unlinkSync(lockPath);
+        }
+        // 如果 PID 不匹配，说明锁已被其他进程重新获取，不删除
+    }
+    catch {
+        // 忽略删除错误
+    }
+}
+/**
+ * 检查并清理过期锁
+ */
+function cleanupStaleLock(lockPath, staleMs) {
+    try {
+        const stat = fs.statSync(lockPath);
+        const pid = readLockPid(lockPath);
+        // 检查是否过期
+        const isStale = Date.now() - stat.mtimeMs > staleMs;
+        // 检查持有者是否已死亡
+        // PID 为 null 表示锁文件损坏，应视为无效锁
+        const isDead = pid === null || !isProcessAlive(pid);
+        // 满足任一条件即可清理：过期、持有者死亡、PID 无效
+        if (isStale || isDead) {
+            try {
+                fs.unlinkSync(lockPath);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 计算退避延迟（指数退避 + 抖动）
+ */
+function calculateBackoff(attempt, baseMs, maxMs) {
+    // 指数退避：10, 20, 40, 80, 160, 320, 500, 500, ...
+    const exponentialDelay = Math.min(baseMs * Math.pow(2, attempt), maxMs);
+    // 添加 20% 的随机抖动，避免多个进程同时重试
+    const jitter = exponentialDelay * 0.2 * Math.random();
+    return Math.floor(exponentialDelay + jitter);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function sleepSync(ms) {
+    const end = Date.now() + ms;
+    while (Date.now() < end) {
+        // busy wait for synchronous retry
+    }
+}
+function buildLockError(filePath, lockPath) {
+    const holderPid = readLockPid(lockPath);
+    const holderStatus = holderPid !== null
+        ? (isProcessAlive(holderPid) ? `alive (PID ${holderPid})` : `dead (PID ${holderPid})`)
+        : 'unknown';
+    return new LockAcquisitionError(`Failed to acquire lock for ${filePath}. Lock holder: ${holderStatus}.`, filePath, lockPath);
+}
+function tryAcquireWithStaleCleanup(filePath, opts, pid) {
+    const lockPath = filePath + opts.lockSuffix;
+    if (tryAcquireLock(lockPath, pid)) {
+        const actualPid = readLockPid(lockPath);
+        if (actualPid === pid) {
+            return { lockPath, pid, acquiredAt: Date.now() };
+        }
+    }
+    cleanupStaleLock(lockPath, opts.lockStaleMs);
+    if (tryAcquireLock(lockPath, pid)) {
+        const actualPid = readLockPid(lockPath);
+        if (actualPid === pid) {
+            return { lockPath, pid, acquiredAt: Date.now() };
+        }
+    }
+    return null;
+}
+/**
+ * 获取文件锁
+ *
+ * @param filePath 要锁定的文件路径
+ * @param options 锁选项
+ * @returns 锁上下文（用于后续释放）
+ * @throws Error 如果无法获取锁
+ */
+export function acquireLock(filePath, options = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const { pid } = process;
+    for (let attempt = 0; attempt < opts.maxRetries; attempt++) {
+        const ctx = tryAcquireWithStaleCleanup(filePath, opts, pid);
+        if (ctx) {
+            return ctx;
+        }
+        if (attempt < opts.maxRetries - 1) {
+            const delay = calculateBackoff(attempt, opts.baseRetryDelayMs, opts.maxRetryDelayMs);
+            sleepSync(delay);
+        }
+    }
+    throw buildLockError(filePath, filePath + opts.lockSuffix);
+}
+export async function acquireLockAsync(filePath, options = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const { pid } = process;
+    for (let attempt = 0; attempt < opts.maxRetries; attempt++) {
+        const ctx = tryAcquireWithStaleCleanup(filePath, opts, pid);
+        if (ctx) {
+            return ctx;
+        }
+        if (attempt < opts.maxRetries - 1) {
+            const delay = calculateBackoff(attempt, opts.baseRetryDelayMs, opts.maxRetryDelayMs);
+            await sleep(delay);
+        }
+    }
+    throw buildLockError(filePath, filePath + opts.lockSuffix);
+}
+/**
+ * 释放文件锁
+ *
+ * @param ctx 锁上下文（由 acquireLock 返回）
+ */
+export function releaseLock(ctx) {
+    safeReleaseLock(ctx.lockPath, ctx.pid);
+}
+/**
+ * 使用锁执行操作（自动获取和释放）
+ *
+ * @param filePath 要锁定的文件路径
+ * @param fn 要执行的操作
+ * @param options 锁选项
+ * @returns 操作的返回值
+ */
+export function withLock(filePath, fn, options = {}) {
+    const ctx = acquireLock(filePath, options);
+    try {
+        return fn();
+    }
+    finally {
+        releaseLock(ctx);
+    }
+}
+export async function withLockAsync(filePath, fn, options = {}) {
+    const ctx = await acquireLockAsync(filePath, options);
+    try {
+        return await fn();
+    }
+    finally {
+        releaseLock(ctx);
+    }
+}
+/**
+ * 异步版本的文件锁（使用 Promise 链）
+ *
+ * 注意：这是一个简化的实现，适用于单进程内的异步并发控制
+ * 对于多进程场景，应使用同步版本的 acquireLock
+ */
+export const asyncLockQueues = new Map();
+export async function withAsyncLock(filePath, fn) {
+    const lockPath = filePath + '.async';
+    // 获取或创建该文件的任务队列
+    let queue = asyncLockQueues.get(lockPath);
+    // 创建新的 Promise 链
+    let resolveRelease;
+    const releasePromise = new Promise(resolve => {
+        resolveRelease = resolve;
+    });
+    // 将当前任务加入队列
+    const previousQueue = queue || Promise.resolve();
+    const currentQueue = previousQueue.then(() => releasePromise);
+    asyncLockQueues.set(lockPath, currentQueue);
+    // 等待前面的任务完成
+    await previousQueue;
+    try {
+        return await fn();
+    }
+    finally {
+        resolveRelease();
+        // 清理已完成的队列
+        if (asyncLockQueues.get(lockPath) === currentQueue) {
+            asyncLockQueues.delete(lockPath);
+        }
+    }
+}
+/**
+ * 检查锁状态（用于调试）
+ */
+export function getLockStatus(filePath, options = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const lockPath = filePath + opts.lockSuffix;
+    try {
+        const stat = fs.statSync(lockPath);
+        const pid = readLockPid(lockPath);
+        return {
+            locked: true,
+            holderPid: pid,
+            holderAlive: pid !== null && isProcessAlive(pid),
+            lockAge: Date.now() - stat.mtimeMs,
+        };
+    }
+    catch {
+        return {
+            locked: false,
+            holderPid: null,
+            holderAlive: false,
+            lockAge: null,
+        };
+    }
+}

package/dist/utils/hashing.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Strips timestamps, UUIDs, and hex memory addresses from error messages
+ * to allow for consistent loop detection even if the raw text varies slightly.
+ */
+export declare function denoiseError(text: string): string;
+/**
+ * Computes a simple SHA-256 hash of the given string.
+ */
+export declare function computeHash(text: string): string;

package/{src/utils/hashing.ts → dist/utils/hashing.js}

@@ -1,12 +1,11 @@
 import { createHash } from 'crypto';
-
 /**
  * Strips timestamps, UUIDs, and hex memory addresses from error messages
  * to allow for consistent loop detection even if the raw text varies slightly.
  */
-export function denoiseError(text: string): string {
-    if (!text) return '';
-    
+export function denoiseError(text) {
+    if (!text)
+        return '';
     return text
         // Strip ISO timestamps and common date formats
         .replace(/\d{4}-\d{2}-\d{2}[T\s]\d{2}:\d{2}:\d{2}(\.\d+)?Z?/g, '[TIME]')
@@ -18,10 +17,9 @@ export function denoiseError(text: string): string {
         .replace(/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/g, '[UUID]')
         .trim();
 }
-
 /**
  * Computes a simple SHA-256 hash of the given string.
  */
-export function computeHash(text: string): string {
+export function computeHash(text) {
     return createHash('sha256').update(text).digest('hex');
 }

package/dist/utils/io.d.ts

@@ -0,0 +1,11 @@
+export declare function atomicWriteFileSync(filePath: string, data: string): void;
+export declare function normalizePath(filePath: string, projectDir: string): string;
+export declare function normalizeRiskPath(p: string): string;
+export declare function isRisky(relPath: string, riskPaths: string[]): boolean;
+export declare function parseKvLines(text: string): Record<string, string>;
+export declare function serializeKvLines(data: Record<string, any>): string;
+/**
+ * Normalize command arguments from PluginCommandContext.args.
+ * Handles string | string[] | undefined union by joining arrays with spaces.
+ */
+export declare function normalizeCommandArgs(args: string | string[] | undefined): string;