principles-disciple 1.41.0 → 1.43.0

package/src/service/sleep-cycle.ts

@@ -0,0 +1,157 @@
+/**
+ * Sleep Cycle Orchestrator — extracted from evolution-worker.ts
+ *
+ * Responsibilities:
+ * - Idle workspace detection via nocturnal-runtime.js
+ * - Cooldown enforcement via nocturnal-runtime.js
+ * - Sleep reflection task enqueue orchestration (fire-and-forget)
+ * - Keyword optimization task enqueue orchestration (fire-and-forget)
+ * - Cycle heartbeat tracking and periodic trigger reset
+ *
+ * Does NOT include (remain in evolution-worker.ts facade):
+ * - checkPainFlag, processEvolutionQueueWithResult, processDetectionQueue
+ * - Workflow managers (EmpathyObserver, DeepReflect, Nocturnal)
+ * - Workflow watchdog (runWorkflowWatchdog)
+ * - Pain-flag-triggered immediate heartbeat
+ *
+ * Dependencies: nocturnal-runtime.js, nocturnal-config.js, queue-io.js
+ * Zero imports from evolution-worker.ts.
+ */
+
+import type { WorkspaceContext } from '../core/workspace-context.js';
+import type { OpenClawPluginApi, PluginLogger } from '../openclaw-sdk.js';
+import type { EventLog } from '../core/event-log.js';
+import { checkWorkspaceIdle, checkCooldown } from './nocturnal-runtime.js';
+import { loadNocturnalConfigMerged } from './nocturnal-config.js';
+import { enqueueSleepReflectionTask, enqueueKeywordOptimizationTask } from './queue-io.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface WorkerStatusReport {
+    timestamp: string;
+    cycle_start_ms: number;
+    duration_ms: number;
+    pain_flag: { exists: boolean; score: number | null; source: string | null; enqueued: boolean; skipped_reason: string | null };
+    queue: { total: number; pending: number; in_progress: number; completed_this_cycle: number; failed_this_cycle: number };
+    errors: string[];
+}
+
+export interface CycleOptions {
+    wctx: WorkspaceContext;
+    logger: PluginLogger | undefined;
+    eventLog: EventLog;
+    api: OpenClawPluginApi | undefined;
+    /** Mutable ref to the heartbeat counter — incremented by runCycle on each call */
+    heartbeatCounterRef: { value: number };
+}
+
+// ---------------------------------------------------------------------------
+// Cycle Orchestrator
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute one sleep-cycle heartbeat.
+ *
+ * Orchestrates:
+ * 1. Load merged nocturnal config
+ * 2. Check workspace idle state
+ * 3. Enqueue keyword_optimization task (independent periodic trigger)
+ * 4. Enqueue sleep_reflection task (idle-based OR periodic trigger + cooldown gate)
+ * 5. Cycle result reporting
+ *
+ * Does NOT directly call checkPainFlag, processEvolutionQueueWithResult, or
+ * processDetectionQueue — those remain in the evolution-worker.ts facade.
+ *
+ * @param options.wctx       — workspace context
+ * @param options.logger     — plugin logger
+ * @param options.eventLog   — event log
+ * @param options.api        — OpenClaw plugin API (optional)
+ * @param options.heartbeatCounterRef — mutable counter, incremented by runCycle
+ */
+export async function runCycle(options: CycleOptions): Promise<WorkerStatusReport> {
+    const { wctx, logger, eventLog: _eventLog, api: _api, heartbeatCounterRef } = options;
+    const cycleStart = Date.now();
+    heartbeatCounterRef.value++;
+
+    // ──── DEBUG: Verify subagent availability in heartbeat context ────
+    const hbSubagent = _api?.runtime?.subagent;
+    logger?.info?.(`[PD:DEBUG:SubagentCheck:Heartbeat] api_exists=${!!_api}, subagent_exists=${!!hbSubagent}, subagent.run_exists=${!!hbSubagent?.run}, heartbeatCounter=${heartbeatCounterRef.value}`);
+    if (hbSubagent?.run) {
+        logger?.info?.('[PD:DEBUG:SubagentCheck:Heartbeat] run entrypoint is callable');
+    }
+
+    const cycleResult: WorkerStatusReport = {
+        timestamp: new Date().toISOString(),
+        cycle_start_ms: cycleStart,
+        duration_ms: 0,
+        pain_flag: { exists: false, score: null, source: null, enqueued: false, skipped_reason: null },
+        queue: { total: 0, pending: 0, in_progress: 0, completed_this_cycle: 0, failed_this_cycle: 0 },
+        errors: [],
+    };
+
+    try {
+        // Load config on each cycle (supports runtime updates) — single file read
+        const mergedConfig = loadNocturnalConfigMerged(wctx.stateDir);
+        const { sleepReflection: sleepConfig, keywordOptimization: kwOptConfig } = mergedConfig;
+
+        const idleResult = checkWorkspaceIdle(wctx.workspaceDir, {});
+        logger?.info?.(`[PD:EvolutionWorker] HEARTBEAT cycle=${new Date().toISOString()} idle=${idleResult.isIdle} idleForMs=${idleResult.idleForMs} userActiveSessions=${idleResult.userActiveSessions} abandonedSessions=${idleResult.abandonedSessionIds.length} lastActivityEpoch=${idleResult.mostRecentActivityAt} triggerMode=${sleepConfig.trigger_mode}`);
+
+        let shouldTrySleepReflection = false;
+
+        // Path 1: Idle-based trigger (default mode)
+        if (idleResult.isIdle && sleepConfig.trigger_mode === 'idle') {
+            logger?.info?.(`[PD:EvolutionWorker] Workspace idle (${idleResult.idleForMs}ms since last activity)`);
+            shouldTrySleepReflection = true;
+        }
+
+        // keyword_optimization: Independent periodic trigger (CORR-07).
+        // Fires every kwOptConfig.period_heartbeats regardless of trigger_mode.
+        // Has its own dedicated config (default 24 heartbeats = 6 hours).
+        if (kwOptConfig.enabled && heartbeatCounterRef.value > 0 && heartbeatCounterRef.value % kwOptConfig.period_heartbeats === 0) {
+            logger?.info?.(`[PD:EvolutionWorker] keyword_optimization trigger at heartbeat ${heartbeatCounterRef.value} (trigger_mode=${sleepConfig.trigger_mode})`);
+            enqueueKeywordOptimizationTask(wctx, logger).catch((err) => {
+                logger?.error?.(`[PD:EvolutionWorker] Failed to enqueue keyword_optimization task: ${String(err)}`);
+            });
+        }
+
+        // Path 2: Periodic trigger for sleep_reflection (fires regardless of idle state)
+        if (sleepConfig.trigger_mode === 'periodic') {
+            if (heartbeatCounterRef.value >= sleepConfig.period_heartbeats) {
+                logger?.info?.(`[PD:EvolutionWorker] Periodic trigger: heartbeatCounter=${heartbeatCounterRef.value} >= period_heartbeats=${sleepConfig.period_heartbeats}`);
+                shouldTrySleepReflection = true;
+                heartbeatCounterRef.value = 0; // Reset counter
+            } else {
+                logger?.info?.(`[PD:EvolutionWorker] Periodic: ${heartbeatCounterRef.value}/${sleepConfig.period_heartbeats} heartbeats — waiting`);
+            }
+        }
+
+        if (shouldTrySleepReflection) {
+            const cooldown = checkCooldown(wctx.stateDir, undefined, {
+                globalCooldownMs: sleepConfig.cooldown_ms,
+                maxRunsPerWindow: sleepConfig.max_runs_per_day,
+                quotaWindowMs: 24 * 60 * 60 * 1000,
+            });
+            logger?.info?.(`[PD:EvolutionWorker] Cooldown check: globalCooldownActive=${cooldown.globalCooldownActive} quotaExhausted=${cooldown.quotaExhausted} runsRemaining=${cooldown.runsRemaining}`);
+            if (!cooldown.globalCooldownActive && !cooldown.quotaExhausted) {
+                logger?.info?.('[PD:EvolutionWorker] Attempting to enqueue sleep_reflection task...');
+                enqueueSleepReflectionTask(wctx, logger).catch((err) => {
+                    logger?.error?.(`[PD:EvolutionWorker] Failed to enqueue sleep_reflection task: ${String(err)}`);
+                });
+            } else {
+                logger?.info?.(`[PD:EvolutionWorker] Skipping sleep_reflection: globalCooldown=${cooldown.globalCooldownActive} quotaExhausted=${cooldown.quotaExhausted}`);
+            }
+        }
+
+        cycleResult.duration_ms = Date.now() - cycleStart;
+    } catch (err) {
+        const errMsg = `Error in runCycle: ${String(err)}`;
+        if (logger) logger.error(`[PD:EvolutionWorker] ${errMsg}`);
+        cycleResult.errors.push(errMsg);
+        cycleResult.duration_ms = Date.now() - cycleStart;
+    }
+
+    return cycleResult;
+}

package/src/service/subagent-workflow/empathy-observer-workflow-manager.ts

@@ -1,3 +1,4 @@
+/* eslint-disable no-console */
 import type { PluginLogger } from '../../openclaw-sdk.js';
 import type {
     SubagentWorkflowSpec,

package/src/service/subagent-workflow/runtime-direct-driver.ts

@@ -56,7 +56,7 @@ export interface CleanupParams {
 }
 
  
-type PluginRuntimeSubagent = {
+export type PluginRuntimeSubagent = {
     run: (params: {
         sessionKey: string;
         message: string;

package/src/service/subagent-workflow/subagent-error-utils.ts

@@ -5,7 +5,7 @@
  *
  * Callers should suppress warnings for these errors — they are not real failures.
  */
-    // eslint-disable-next-line complexity -- complexity 13, refactor candidate
+     
 export function isExpectedSubagentError(err: unknown): boolean {
     const msg = String(err);
     return (

package/src/service/subagent-workflow/workflow-store.ts

@@ -1,3 +1,4 @@
+/* eslint-disable no-console */
 import Database from 'better-sqlite3';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -233,7 +234,7 @@ export class WorkflowStore {
     }
     
      
-    // eslint-disable-next-line @typescript-eslint/max-params
+     
     recordEvent(
         workflowId: string,
         eventType: string,
@@ -270,7 +271,7 @@ export class WorkflowStore {
      * same idempotency_key already exists, this is a no-op (idempotent).
      */
      
-    // eslint-disable-next-line @typescript-eslint/max-params
+     
     recordStageOutput(
         workflowId: string,
         stage: 'dreamer' | 'philosopher',

package/src/service/workflow-watchdog.ts

@@ -0,0 +1,168 @@
+/**
+ * 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)
+ * BUG-03: Nocturnal workflow snapshot validation detects pain_context_fallback
+ *         with zero stats (lines 184-198)
+ */
+
+import type { WorkspaceContext } from '../core/workspace-context.js';
+import type { OpenClawPluginApi, PluginLogger } from '../openclaw-sdk.js';
+import type { WorkflowRow } from './subagent-workflow/types.js';
+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 interface WatchdogResult {
+  anomalies: number;
+  details: string[];
+  /** Set when the watchdog scan itself failed (e.g., store errors). Undefined means scan succeeded. */
+  scanError?: string;
+}
+
+ 
+export async function runWorkflowWatchdog(
+  wctx: WorkspaceContext,
+  api: OpenClawPluginApi | null,
+  logger?: PluginLogger,
+): Promise<WatchdogResult> {
+  const details: string[] = [];
+  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: WorkflowRow[] = store.listWorkflows();
+
+      // Check 1: Stale active workflows (active > 2x TTL)
+      const staleThreshold = WORKFLOW_TTL_MS * 2;
+      const staleActive = allWorkflows.filter(
+        (wf: WorkflowRow) => 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)`);
+
+          // #257: Check if the last recorded event reason indicates expected subagent unavailability.
+          // If so, skip marking as terminal_error — the workflow is stale because the subagent
+          // was expectedly unavailable (daemon mode, process isolation), not due to a hard failure.
+          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 });
+
+          // Cleanup session if possible (#188: gateway-safe fallback)
+          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}`);
+              }
+            }
+          }
+        }
+      }
+
+      // Check 2: Workflows in terminal_error/expired without cleanup
+      const unclearedTerminal = allWorkflows.filter(
+        (wf: WorkflowRow) => (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)`);
+      }
+
+      // Check 3: Nocturnal workflow result validation (#181 pattern)
+      const nocturnalCompleted = allWorkflows.filter(
+        (wf: WorkflowRow) => wf.workflow_type === 'nocturnal' && wf.state === 'completed',
+      );
+      for (const wf of nocturnalCompleted) {
+        // Check if the metadata snapshot has all zeros (invalid data)
+        try {
+          const meta = JSON.parse(wf.metadata_json) as Record<string, unknown>;
+          const snapshot = meta.snapshot as Record<string, unknown> | undefined;
+          if (snapshot) {
+            // #219: Check for fallback data source (partial stats from pain context)
+            const dataSource = snapshot._dataSource as string | undefined;
+            if (dataSource === 'pain_context_fallback') {
+              details.push(`fallback_snapshot: nocturnal workflow ${wf.workflow_id} uses pain-context fallback (stats may be incomplete)`);
+            }
+            const stats = snapshot.stats as Record<string, number> | undefined;
+            // #246: Stats are now always number (never null). Detect "empty" fallback:
+            // fallback + all counts zero means no real data was available.
+            // NOTE: totalAssistantTurns may be 0 even for valid sessions because
+            // listRecentNocturnalCandidateSessions (used in fallback path) does not
+            // populate assistantTurnCount (only getNocturnalSessionSnapshot does).
+            // We use totalToolCalls=0 as the primary indicator instead.
+            if (stats && dataSource === 'pain_context_fallback' &&
+                stats.totalToolCalls === 0 && stats.totalGateBlocks === 0 &&
+                stats.failureCount === 0) {
+              details.push(`fallback_snapshot_stats: nocturnal workflow ${wf.workflow_id} has empty fallback stats (no trajectory data found)`);
+            }
+          }
+        } catch (err) {
+          details.push(`malformed_metadata: workflow ${wf.workflow_id} has unparseable metadata: ${String(err).slice(0, 100)}`);
+        }
+      }
+
+      // Summary
+      const stateCounts: Record<string, number> = {};
+      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/src/tools/critique-prompt.ts

@@ -17,7 +17,7 @@ const DEPTH_INSTRUCTIONS = {
  * 严格按照测试用例的调用习惯和断言要求进行重写。
  * 增加 OpenClaw 兼容性路径解析。
  */
-    // eslint-disable-next-line complexity -- complexity 12, refactor candidate
+     
 export function buildCritiquePromptV2(
     params: {
         context: string;

package/src/tools/deep-reflect.ts

@@ -1,4 +1,5 @@
 import type { OpenClawPluginApi } from '../openclaw-sdk.js';
+import type { PluginRuntimeSubagent } from '../service/subagent-workflow/runtime-direct-driver.js';
 import { Type } from '@sinclair/typebox';
 import * as fs from 'fs';
 import { EventLogService } from '../core/event-log.js';
@@ -23,6 +24,16 @@ interface DeepReflectionConfig {
     timeout_ms?: number;
 }
 
+/**
+ * Type assertion: OpenClaw SDK subagent -> workflow manager subagent type.
+ * Both types are structurally identical but come from different import paths.
+ */
+function toWorkflowSubagent(
+  subagent: NonNullable<OpenClawPluginApi['runtime']>['subagent']
+): PluginRuntimeSubagent {
+  return subagent as unknown as PluginRuntimeSubagent;
+}
+
 const DEFAULT_CONFIG: DeepReflectionConfig = {
     enabled: true,
     mode: 'auto',
@@ -108,7 +119,7 @@ export function createDeepReflectTool(api: OpenClawPluginApi) {
             }
 
              
-            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+             
             const effectiveWorkspaceDir = resolveReflectionWorkspace(api);
 
             const config = loadConfig(effectiveWorkspaceDir, api);
@@ -122,11 +133,11 @@ export function createDeepReflectTool(api: OpenClawPluginApi) {
 
             try {
                  
-                // eslint-disable-next-line @typescript-eslint/no-use-before-define
+                 
                 return await executeReflectionWorkflow(effectiveWorkspaceDir, config, context, depth, model_id, api);
             } catch (err) {
                  
-                // eslint-disable-next-line @typescript-eslint/no-use-before-define
+                 
                 return handleReflectionError(err, context, depth, model_id, effectiveWorkspaceDir, api);
             }
         }
@@ -149,7 +160,7 @@ function resolveReflectionWorkspace(api: OpenClawPluginApi): string {
  * Execute the deep reflection workflow: start, poll, collect results.
  */
  
-// eslint-disable-next-line @typescript-eslint/max-params
+ 
 async function executeReflectionWorkflow(
     effectiveWorkspaceDir: string,
     config: DeepReflectionConfig,
@@ -165,8 +176,8 @@ async function executeReflectionWorkflow(
     const manager = new DeepReflectWorkflowManager({
         workspaceDir: effectiveWorkspaceDir,
         logger: api.logger,
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Reason: api.runtime.subagent has structurally compatible shape but differs from PluginRuntimeSubagent due to optional provider/model fields
-        subagent: api.runtime.subagent as any,
+         
+        subagent: toWorkflowSubagent(api.runtime.subagent),
         agentSession: api.runtime.agent?.session,
     });
 
@@ -181,7 +192,7 @@ async function executeReflectionWorkflow(
         const startTime = Date.now();
         const timeoutMs = config.timeout_ms ?? 60000;
          
-        // eslint-disable-next-line @typescript-eslint/no-use-before-define
+         
         return await pollReflectionCompletion(manager, handle, timeoutMs, startTime, eventLog, effectiveWorkspaceDir, context, model_id, depth);
     } finally {
         manager.dispose();
@@ -192,7 +203,7 @@ async function executeReflectionWorkflow(
  * Poll the reflection workflow until completion, timeout, or error.
  */
  
-// eslint-disable-next-line @typescript-eslint/max-params
+ 
 async function pollReflectionCompletion(
     manager: DeepReflectWorkflowManager,
     handle: { workflowId: string; childSessionKey: string },
@@ -213,7 +224,7 @@ async function pollReflectionCompletion(
 
         if (workflowState === 'completed') {
              
-            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+             
             return formatReflectionSuccess(handle, context, depth, model_id, startTime, eventLog, workspaceDir);
         }
 
@@ -229,7 +240,7 @@ async function pollReflectionCompletion(
  * Format the success response from a completed reflection.
  */
  
-// eslint-disable-next-line @typescript-eslint/max-params
+ 
 function formatReflectionSuccess(
     handle: { childSessionKey: string },
     context: string,
@@ -283,7 +294,7 @@ ${insights || '反思完成，详见 REFLECTION_LOG。'}
  * Handle reflection errors and format error response.
  */
  
-// eslint-disable-next-line @typescript-eslint/max-params
+ 
 function handleReflectionError(
     err: unknown,
     context: string,

package/src/tools/model-index.ts

@@ -62,7 +62,7 @@ export function loadModelIndex(
         const customConfig = loadCustomConfig(wctx);
         
          
-        // eslint-disable-next-line @typescript-eslint/init-declarations
+         
         let modelsDir: string;
         if (customConfig?.modelsDir) {
             modelsDir = path.isAbsolute(customConfig.modelsDir) 

package/src/types/event-payload.ts

@@ -0,0 +1,80 @@
+/**
+ * Discriminated union for EventLogEntry — replaces flat data: Record<string, unknown>.
+ * Each union member is keyed on the `type` field for type narrowing.
+ */
+
+import type {
+  ToolCallEventData,
+  PainSignalEventData,
+  RuleMatchEventData,
+  RulePromotionEventData,
+  HookExecutionEventData,
+  GateBlockEventData,
+  GateBypassEventData,
+  PlanApprovalEventData,
+  EvolutionTaskEventData,
+  DeepReflectionEventData,
+  EmpathyRollbackEventData,
+  EventCategory,
+} from './event-types.js';
+
+export type EventLogEntry =
+  | { ts: string; date: string; type: 'tool_call'; category: EventCategory; sessionId?: string; workspaceDir?: string; data: ToolCallEventData }
+  | { ts: string; date: string; type: 'pain_signal'; category: EventCategory; sessionId?: string; workspaceDir?: string; data: PainSignalEventData }
+  | { ts: string; date: string; type: 'rule_match'; category: EventCategory; sessionId?: string; workspaceDir?: string; data: RuleMatchEventData }
+  | { ts: string; date: string; type: 'rule_promotion'; category: EventCategory; sessionId?: string; workspaceDir?: string; data: RulePromotionEventData }
+  | { ts: string; date: string; type: 'hook_execution'; category: EventCategory; sessionId?: string; workspaceDir?: string; data: HookExecutionEventData }
+  | { ts: string; date: string; type: 'gate_block'; category: EventCategory; sessionId?: string; workspaceDir?: string; data: GateBlockEventData }
+  | { ts: string; date: string; type: 'gate_bypass'; category: EventCategory; sessionId?: string; workspaceDir?: string; data: GateBypassEventData }
+  | { ts: string; date: string; type: 'plan_approval'; category: EventCategory; sessionId?: string; workspaceDir?: string; data: PlanApprovalEventData }
+  | { ts: string; date: string; type: 'evolution_task'; category: EventCategory; sessionId?: string; workspaceDir?: string; data: EvolutionTaskEventData }
+  | { ts: string; date: string; type: 'deep_reflection'; category: EventCategory; sessionId?: string; workspaceDir?: string; data: DeepReflectionEventData }
+  | { ts: string; date: string; type: 'empathy_rollback'; category: EventCategory; sessionId?: string; workspaceDir?: string; data: EmpathyRollbackEventData }
+  | { ts: string; date: string; type: 'error'; category: EventCategory; sessionId?: string; workspaceDir?: string; data: Record<string, unknown> }
+  | { ts: string; date: string; type: 'warn'; category: EventCategory; sessionId?: string; workspaceDir?: string; data: Record<string, unknown> };
+
+// Type predicates for safe narrowing
+
+export function isToolCallEventEntry(entry: EventLogEntry): entry is Extract<EventLogEntry, { type: 'tool_call' }> {
+  return entry.type === 'tool_call';
+}
+
+export function isPainSignalEventEntry(entry: EventLogEntry): entry is Extract<EventLogEntry, { type: 'pain_signal' }> {
+  return entry.type === 'pain_signal';
+}
+
+export function isRuleMatchEventEntry(entry: EventLogEntry): entry is Extract<EventLogEntry, { type: 'rule_match' }> {
+  return entry.type === 'rule_match';
+}
+
+export function isRulePromotionEventEntry(entry: EventLogEntry): entry is Extract<EventLogEntry, { type: 'rule_promotion' }> {
+  return entry.type === 'rule_promotion';
+}
+
+export function isHookExecutionEventEntry(entry: EventLogEntry): entry is Extract<EventLogEntry, { type: 'hook_execution' }> {
+  return entry.type === 'hook_execution';
+}
+
+export function isGateBlockEventEntry(entry: EventLogEntry): entry is Extract<EventLogEntry, { type: 'gate_block' }> {
+  return entry.type === 'gate_block';
+}
+
+export function isGateBypassEventEntry(entry: EventLogEntry): entry is Extract<EventLogEntry, { type: 'gate_bypass' }> {
+  return entry.type === 'gate_bypass';
+}
+
+export function isPlanApprovalEventEntry(entry: EventLogEntry): entry is Extract<EventLogEntry, { type: 'plan_approval' }> {
+  return entry.type === 'plan_approval';
+}
+
+export function isEvolutionTaskEventEntry(entry: EventLogEntry): entry is Extract<EventLogEntry, { type: 'evolution_task' }> {
+  return entry.type === 'evolution_task';
+}
+
+export function isDeepReflectionEventEntry(entry: EventLogEntry): entry is Extract<EventLogEntry, { type: 'deep_reflection' }> {
+  return entry.type === 'deep_reflection';
+}
+
+export function isEmpathyRollbackEventEntry(entry: EventLogEntry): entry is Extract<EventLogEntry, { type: 'empathy_rollback' }> {
+  return entry.type === 'empathy_rollback';
+}

package/src/types/queue.ts

@@ -0,0 +1,70 @@
+/**
+ * Branded types for queue and workflow domain identifiers.
+ * These prevent accidental interchange of plain strings with domain-specific IDs.
+ */
+
+/**
+ * Brand type constructor using intersection type pattern.
+ * @example type UserId = Brand<string, 'UserId'>;
+ */
+export type Brand<T, B> = T & { readonly _brand: B };
+
+/**
+ * Queue item identifier — not interchangeable with plain string.
+ */
+export type QueueItemId = Brand<string, 'QueueItemId'>;
+
+/**
+ * Workflow identifier — not interchangeable with plain string.
+ */
+export type WorkflowId = Brand<string, 'WorkflowId'>;
+
+/**
+ * Session key — not interchangeable with plain string.
+ */
+export type SessionKey = Brand<string, 'SessionKey'>;
+
+/**
+ * Constructor for QueueItemId.
+ * @param id - raw string ID from queue operations
+ */
+export function toQueueItemId(id: string): QueueItemId {
+  return id as QueueItemId;
+}
+
+/**
+ * Constructor for WorkflowId.
+ * @param id - raw string ID from workflow operations
+ */
+export function toWorkflowId(id: string): WorkflowId {
+  return id as WorkflowId;
+}
+
+/**
+ * Constructor for SessionKey.
+ * @param key - raw string key from session operations
+ */
+export function toSessionKey(key: string): SessionKey {
+  return key as SessionKey;
+}
+
+/**
+ * Type predicate: true if value is a QueueItemId.
+ */
+export function isQueueItemId(value: unknown): value is QueueItemId {
+  return typeof value === 'string';
+}
+
+/**
+ * Type predicate: true if value is a WorkflowId.
+ */
+export function isWorkflowId(value: unknown): value is WorkflowId {
+  return typeof value === 'string';
+}
+
+/**
+ * Type predicate: true if value is a SessionKey.
+ */
+export function isSessionKey(value: unknown): value is SessionKey {
+  return typeof value === 'string';
+}

package/src/utils/file-lock.ts

@@ -322,7 +322,7 @@ export async function withLockAsync<T>(
  * 注意：这是一个简化的实现，适用于单进程内的异步并发控制
  * 对于多进程场景，应使用同步版本的 acquireLock
  */
-const asyncLockQueues = new Map<string, Promise<void>>();
+export const asyncLockQueues = new Map<string, Promise<void>>();
 
 export async function withAsyncLock<T>(
   filePath: string,
@@ -335,7 +335,7 @@ export async function withAsyncLock<T>(
   
   // 创建新的 Promise 链
    
-  // eslint-disable-next-line @typescript-eslint/init-declarations
+   
   let resolveRelease: () => void;
   const releasePromise = new Promise<void>(resolve => {
     resolveRelease = resolve;