principles-disciple 1.41.0 → 1.42.0

package/.planning/codebase/STRUCTURE.md

@@ -0,0 +1,193 @@
+# Codebase Structure
+
+**Analysis Date:** 2026-04-15
+
+## Directory Layout
+
+```
+openclaw-plugin/
+├── src/                    # Main source code
+│   ├── commands/           # Slash command implementations
+│   ├── config/            # Configuration defaults and errors
+│   ├── constants/          # Shared constants
+│   ├── core/               # Core business logic
+│   │   ├── hygiene/        # Hygiene tracking
+│   │   ├── principle-internalization/  # Principle lifecycle
+│   │   └── schema/         # Database schema and migrations
+│   ├── hooks/              # OpenClaw hook handlers
+│   ├── http/               # HTTP route handlers
+│   ├── i18n/               # Internationalization
+│   ├── service/            # Background services
+│   │   └── subagent-workflow/  # Workflow managers
+│   ├── tools/              # Plugin tools
+│   ├── types/              # TypeScript type definitions
+│   └── utils/              # Utility functions
+├── ui/                     # React UI
+│   └── src/
+│       ├── components/     # React components
+│       ├── context/        # React contexts
+│       ├── hooks/          # React hooks
+│       └── pages/          # Page components
+├── tests/                  # Test suite
+│   ├── commands/           # Command tests
+│   ├── core/               # Core module tests
+│   ├── fixtures/           # Test fixtures
+│   ├── hooks/              # Hook tests
+│   ├── integration/        # Integration tests
+│   ├── service/            # Service tests
+│   └── utils/              # Utility tests
+├── templates/               # Workspace templates
+│   ├── langs/              # Language-specific templates
+│   └── workspace/           # Workspace structure templates
+├── dist/                   # Build output
+├── scripts/                # Build scripts
+├── .state/                 # Runtime state (gitignored)
+└── .tmp/                   # Temporary files (gitignored)
+```
+
+## Directory Purposes
+
+**src/commands/:**
+- Purpose: Slash command implementations
+- Contains: 20+ command handlers (strategy, focus, pain, rollback, nocturnal-review, nocturnal-train, etc.)
+- Key files: `strategy.ts`, `focus.ts`, `nocturnal-train.ts`, `nocturnal-rollout.ts`
+
+**src/core/:**
+- Purpose: Core business logic (evolution, trajectory, pain, training, rules)
+- Contains: 70+ core modules including `evolution-engine.ts`, `trajectory.ts`, `nocturnal-trinity.ts`, `pain.ts`, `principle-tree-ledger.ts`
+- Key files: `evolution-engine.ts`, `nocturnal-trinity.ts`, `rule-host.ts`
+
+**src/hooks/:**
+- Purpose: OpenClaw hook handlers for intercepting agent behavior
+- Contains: `prompt.ts`, `gate.ts`, `pain.ts`, `llm.ts`, `lifecycle.ts`, `subagent.ts`, `trajectory-collector.ts`
+- Key files: `gate.ts` (security), `prompt.ts` (context injection)
+
+**src/service/:**
+- Purpose: Background worker services
+- Contains: `evolution-worker.ts` (main worker), `nocturnal-service.ts`, `trajectory-service.ts`, `central-database.ts`
+- Key files: `evolution-worker.ts` (144KB, main async processor)
+
+**src/service/subagent-workflow/:**
+- Purpose: Workflow orchestration for complex subagent operations
+- Contains: `nocturnal-workflow-manager.ts`, `deep-reflect-workflow-manager.ts`, `empathy-observer-workflow-manager.ts`
+- Key files: `workflow-manager-base.ts`, `dynamic-timeout.ts`
+
+**src/utils/:**
+- Purpose: Shared utility functions
+- Contains: `io.ts` (atomic writes), `plugin-logger.ts`, `retry.ts`, `hashing.ts`, `file-lock.ts`
+- Key files: `io.ts` (critical for safe file operations)
+
+**src/schema/:**
+- Purpose: SQLite database schema and migrations
+- Contains: `schema-definitions.ts`, `migration-runner.ts`, `migrations/*.ts`
+- Migrations: 4 migrations (001-004)
+
+**ui/src/:**
+- Purpose: React-based plugin UI
+- Contains: Pages (Overview, Evolution, Feedback, GateMonitor), components (Shell, ProtectedRoute)
+- Key files: `App.tsx`, `pages/EvolutionPage.tsx`, `pages/FeedbackPage.tsx`
+
+## Key File Locations
+
+**Entry Points:**
+- `src/index.ts`: Plugin entry point, registers all hooks/commands/tools
+
+**Configuration:**
+- `src/core/config.ts`: PainSettings defaults
+- `src/core/paths.ts`: Directory and file path constants (PD_DIRS, PD_FILES)
+- `openclaw.plugin.json`: Plugin manifest
+
+**Core Logic:**
+- `src/core/evolution-engine.ts`: Evolution processing (18KB)
+- `src/core/nocturnal-trinity.ts`: Nocturnal training orchestration (87KB - largest file)
+- `src/core/trajectory.ts`: Trajectory tracking (64KB)
+- `src/core/principle-tree-ledger.ts`: Principle lifecycle management (22KB)
+- `src/core/rule-host.ts`: Sandboxed rule execution (7KB)
+
+**Service Layer:**
+- `src/service/evolution-worker.ts`: Background evolution worker (144KB - largest file)
+- `src/service/nocturnal-service.ts`: Nocturnal training service (59KB)
+- `src/service/nocturnal-runtime.ts`: Runtime for nocturnal operations (24KB)
+
+**Testing:**
+- `tests/`: Test suite with unit and integration layers
+- `vitest.config.ts`: Test configuration with unit/integration project separation
+
+## Naming Conventions
+
+**Files:**
+- TypeScript: `kebab-case.ts` or `camelCase.ts` depending on module type
+- Commands: `kebab-case.ts` (e.g., `nocturnal-review.ts`)
+- Core modules: `camelCase.ts` (e.g., `evolutionEngine.ts`)
+- React components: `PascalCase.tsx`
+
+**Directories:**
+- kebab-case: `subagent-workflow`, `principle-internalization`
+
+**Types:**
+- Interfaces: `PascalCase` (e.g., `PainSettings`, `EvolutionContext`)
+- Type aliases: `PascalCase`
+- Enums: `PascalCase`
+
+## Where to Add New Code
+
+**New Command:**
+- Primary code: `src/commands/<name>.ts`
+- Handler registration: `src/index.ts` in `registerCommandWithAlias()` or `api.registerCommand()`
+- Tests: `tests/commands/<name>.test.ts`
+
+**New Hook Handler:**
+- Implementation: `src/hooks/<name>.ts`
+- Registration: `src/index.ts` in `api.on('<hook_name>', ...)` call
+- Tests: `tests/hooks/<name>.test.ts`
+
+**New Core Service:**
+- Implementation: `src/core/<name>.ts` or `src/service/<name>.ts`
+- Registration: `src/index.ts` in `api.registerService()`
+- Tests: `tests/core/<name>.test.ts` or `tests/service/<name>.test.ts`
+
+**New Workflow Manager:**
+- Implementation: `src/service/subagent-workflow/<name>-workflow-manager.ts`
+- Base class: `src/service/subagent-workflow/workflow-manager-base.ts`
+- Tests: `tests/service/subagent-workflow/<name>.test.ts`
+
+**New Database Migration:**
+- Implementation: `src/core/schema/migrations/<number>-<description>.ts`
+- Registration: `src/core/schema/migrations/index.ts`
+- Tests: Integration test in `tests/core/control-ui-db.test.ts`
+
+**New Utility:**
+- Shared: `src/utils/<name>.ts`
+- Tests: `tests/utils/<name>.test.ts`
+
+## Special Directories
+
+**.state/:**
+- Purpose: Runtime state (per workspace)
+- Generated: Yes (created at runtime)
+- Committed: No (gitignored)
+
+**.tmp/:**
+- Purpose: Temporary files during build/dev
+- Generated: Yes
+- Committed: No (gitignored)
+
+**dist/:**
+- Purpose: Build output
+- Generated: Yes (by `npm run build`)
+- Committed: Yes (in some branches)
+
+**templates/:**
+- Purpose: Workspace template files copied on init
+- Generated: No
+- Committed: Yes
+- Contains: Language-specific templates (en, zh), workspace structure
+
+**node_modules/:**
+- Purpose: Dependencies
+- Generated: Yes (by pnpm install)
+- Committed: No
+
+---
+
+*Structure analysis: 2026-04-15*

package/.planning/codebase/TESTING.md

@@ -0,0 +1,243 @@
+# Testing Patterns
+
+**Analysis Date:** 2026-04-15
+
+## Test Framework
+
+**Runner:** Vitest 4.1.0
+- Config: `vitest.config.ts`
+- Environment: `node`
+- Pool: `threads` (required for `better-sqlite3` native handle cleanup)
+
+**Assertion Library:** Vitest built-in (`expect`)
+
+**Coverage:** `@vitest/coverage-v8`
+- Thresholds: lines 70%, functions 70%, branches 60%, statements 70%
+- Excludes: `tests/**`
+
+**Run Commands:**
+```bash
+npm test              # Run unit tests (fast, parallel)
+npm run test:unit     # Alias for above
+npm run test:integration  # Run integration tests only
+npm run test:coverage # Run with coverage report
+npm run test:all      # Run all tests (unit + integration)
+```
+
+## Test File Organization
+
+**Location:**
+- Tests co-located in `tests/` directory, mirroring `src/` structure
+- `tests/core/`, `tests/commands/`, `tests/hooks/`, `tests/service/`, `tests/utils/`
+- Integration tests in `tests/integration/`
+
+**Naming:**
+- `*.test.ts` suffix for all test files
+- Example: `tests/core/detection-service.test.ts`
+
+**Structure:**
+```
+tests/
+├── commands/     # Command handlers
+├── core/         # Core services and logic
+├── fixtures/     # Shared fixtures
+├── hooks/        # Hook handlers
+├── integration/  # End-to-end tests
+├── scripts/      # Script tests
+└── service/      # Service layer
+```
+
+## Test Structure
+
+**Suite Organization:**
+```typescript
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+describe('DetectionService', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        // Reset state between tests
+        DetectionService.reset();
+    });
+
+    it('should create a new instance on first get', () => {
+        // Test implementation
+    });
+});
+```
+
+**Patterns:**
+- `beforeEach` for setup, `afterEach` for teardown
+- `vi.clearAllMocks()` between tests (not `vi.resetAllMocks()`)
+- `vi.useFakeTimers()` / `vi.useRealTimers()` for time-sensitive tests
+
+## Mocking
+
+**Framework:** Vitest's `vi.fn()` and `vi.mock()`
+
+**Module Mocking:**
+```typescript
+vi.mock('../../src/core/dictionary-service.js');
+vi.mock('../../src/core/detection-funnel.js');
+
+// Then configure mock implementations
+vi.mocked(DictionaryService.get).mockReturnValue(mockDict as any);
+```
+
+**Built-in Module Mocking:**
+```typescript
+vi.mock('fs');
+vi.mocked(fs.existsSync).mockReturnValue(true);
+vi.mocked(fs.readFileSync).mockImplementation((p) => {
+    if (p.toString() === configPath) return JSON.stringify(mockConfig);
+    return '';
+});
+```
+
+**Mock Reset:**
+- `vi.clearAllMocks()` clears call history but keeps implementations
+- `vi.resetAllMocks()` clears both (use with caution)
+- Reset singleton state: `DetectionService.reset()`, `WorkspaceContext.clearCache()`
+
+**Partial Mocks:**
+```typescript
+vi.mocked(fs.existsSync).mockImplementation((p) => p.toString() === configPath);
+```
+
+## Fixtures and Factories
+
+**Temp Directory Pattern (integration tests):**
+```typescript
+const tempDirs: string[] = [];
+
+function makeWorkspace(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-runtime-summary-'));
+  tempDirs.push(dir);
+  fs.mkdirSync(path.join(dir, '.state', 'sessions'), { recursive: true });
+  return dir;
+}
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+```
+
+**JSON Fixture Writing:**
+```typescript
+function writeJson(filePath: string, value: unknown): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(value, null, 2), 'utf8');
+}
+```
+
+**Session File Helper:**
+```typescript
+function writeSession(workspace: string, sessionId: string, payload: Record<string, unknown>): void {
+  writeJson(path.join(workspace, '.state', 'sessions', `${sessionId}.json`), {
+    sessionId,
+    ...payload,
+  });
+}
+```
+
+## Integration Tests
+
+**Requirements:**
+- Real SQLite database via `better-sqlite3`
+- Thread pool required (not `vm` pool) due to native handle cleanup issues
+- Explicit file list in `vitest.config.ts` integration array
+
+**Integration Test Files:**
+```typescript
+const integrationTests = [
+  'tests/core/control-ui-db.test.ts',
+  'tests/core/evolution-logger.test.ts',
+  'tests/core/nocturnal-e2e.test.ts',
+  // ...
+];
+```
+
+## Common Patterns
+
+**Async Testing with Fake Timers:**
+```typescript
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+it('should retry on retryable error', async () => {
+  const fn = vi.fn()
+    .mockRejectedValueOnce(new Error('ETIMEDOUT'))
+    .mockResolvedValue('success');
+
+  const resultPromise = retryAsync(fn, { initialDelayMs: 100 });
+  await vi.advanceTimersByTimeAsync(100);
+  const result = await resultPromise;
+  expect(result).toBe('success');
+});
+```
+
+**Error Testing:**
+```typescript
+it('should throw after max retries exceeded', async () => {
+  vi.useRealTimers();
+  const fn = vi.fn().mockRejectedValue(new Error('ETIMEDOUT'));
+
+  await expect(retryAsync(fn, { maxRetries: 1, initialDelayMs: 1, logger: { warn: vi.fn() } }))
+    .rejects.toThrow('ETIMEDOUT');
+});
+```
+
+**Singleton Reset Pattern:**
+```typescript
+// Many services use singleton pattern requiring reset between tests
+DetectionService.reset();
+WorkspaceContext.clearCache();
+clearSession('live-session');
+```
+
+## Test Naming and Documentation
+
+**Descriptive Test Names:**
+```typescript
+it('should block risk path writes at Seed tier (EP system)', () => { ... });
+it('should return default values if file does not exist', () => { ... });
+```
+
+**Test Comments for Context:**
+```typescript
+// Task 4: Default Values Consistency Tests
+describe('Gate Default Values Consistency', () => {
+  /**
+   * PURPOSE: Prove that gate.ts inline defaults match PROFILE_DEFAULTS.
+   * If gate.ts has inline defaults that differ from normalizeProfile(),
+   * this is a bug - the defaults should come from a single source of truth.
+   */
+});
+```
+
+## Test Isolation
+
+**Environment Variable Injection:**
+```typescript
+// Set env before module load
+process.env.PD_TEST_AGENTS_DIR = TEST_AGENTS_DIR;
+```
+
+**Path Traversal Protection Tests:**
+```typescript
+it('rejects path traversal session IDs', async () => {
+  const result = await extractRecentConversation('../../etc/passwd', 'main');
+  expect(result).toBe('');
+});
+```
+
+---
+
+*Testing analysis: 2026-04-15*

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "principles-disciple",
   "name": "Principles Disciple",
   "description": "Evolutionary programming agent framework with strategic guardrails and reflection loops.",
-  "version": "1.41.0",
+  "version": "1.42.0",
   "skills": [
     "./skills"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "principles-disciple",
-  "version": "1.41.0",
+  "version": "1.42.0",
   "description": "Native OpenClaw plugin for Principles Disciple",
   "type": "module",
   "main": "./dist/bundle.js",

package/src/commands/pain.ts

@@ -80,6 +80,14 @@ function formatEmpathyCard(stats: EmpathyEventStats, range: string, isZh: boolea
     return lines.join('\n');
 }
 
+/**
+ * Extended context interface that includes sessionId injected by the plugin framework.
+ * PluginCommandContext does not include sessionId in its type definition.
+ */
+interface SessionAwareCommandContext extends PluginCommandContext {
+  sessionId: string;
+}
+
 /**
  * Handles the /pd-status command
  */
@@ -89,15 +97,14 @@ export function handlePainCommand(ctx: PluginCommandContext): PluginCommandResul
     const wctx = WorkspaceContext.fromHookContext({ workspaceDir, ...ctx.config });
     const lang = (ctx.config?.language as string) || 'en';
     const isZh = lang === 'zh';
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Reason: sessionId injected by OpenClaw plugin framework - type not available in PluginCommandContext
-    const {sessionId} = (ctx as any);
+    const { sessionId } = ctx as SessionAwareCommandContext;
 
     const args = (ctx.args || '').trim();
 
     // Handle empathy subcommand
     if (args.startsWith('empathy')) {
          
-        // eslint-disable-next-line @typescript-eslint/no-use-before-define
+         
         return handleEmpathySubcommand(wctx, args, sessionId, isZh);
     }
 
@@ -138,7 +145,7 @@ export function handlePainCommand(ctx: PluginCommandContext): PluginCommandResul
     
     // Determine health status based on GFI
      
-    // eslint-disable-next-line @typescript-eslint/init-declarations
+     
     let healthLabel: string;
     let suggestionText = '';
 
@@ -218,7 +225,7 @@ export function handlePainCommand(ctx: PluginCommandContext): PluginCommandResul
  * Handle /pd-status empathy subcommand
  */
  
-    // eslint-disable-next-line @typescript-eslint/max-params -- complexity 13, refactor candidate
+     
 function handleEmpathySubcommand(
     wctx: WorkspaceContext,
     args: string,

package/src/commands/promote-impl.ts

@@ -28,7 +28,7 @@ import {
 } from '../core/principle-tree-ledger.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
-import type { Implementation } from '../types/principle-tree-schema.js';
+import type { Implementation, ImplementationLifecycleState } from '../types/principle-tree-schema.js';
 import { withLock } from '../utils/file-lock.js';
 import { atomicWriteFileSync } from '../utils/io.js';
 
@@ -37,16 +37,23 @@ function getAllImplementations(stateDir: string): Implementation[] {
   return Object.values(ledger.tree.implementations);
 }
 
+/**
+ * Type predicate: true if impl has lifecycleState of 'candidate' or 'disabled'.
+ * The ledger adds lifecycleState at runtime beyond what's in the manifest interface.
+ */
+function isCandidateOrDisabled(
+  impl: Implementation
+): impl is Implementation & { lifecycleState: ImplementationLifecycleState } {
+  return impl.lifecycleState === 'candidate' || impl.lifecycleState === 'disabled';
+}
+
 function _handleListCandidates(
   stateDir: string,
   isZh: boolean,
 ): PluginCommandResult {
   const engine = new ReplayEngine('', stateDir);
   const allImpls = getAllImplementations(stateDir);
-  const candidates = allImpls.filter(
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Reason: lifecycleState is a dynamic property added by the system - type not in official interface
-    (impl) => (impl as any).lifecycleState === 'candidate',
-  );
+  const candidates = allImpls.filter(isCandidateOrDisabled);
 
   if (candidates.length === 0) {
     return {
@@ -141,8 +148,7 @@ function _handlePromoteImpl(options: PromoteImplOptions): PluginCommandResult {
     };
   }
 
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Reason: lifecycleState is a dynamic property added by the system - type not in official interface
-  const currentState = (candidate as any).lifecycleState || 'candidate';
+  const currentState = candidate.lifecycleState || 'candidate';
 
   if (currentState !== 'candidate' && currentState !== 'disabled') {
     return {

package/src/commands/rollback.ts

@@ -2,6 +2,14 @@ import { WorkspaceContext } from '../core/workspace-context.js';
 import { resetFriction } from '../core/session-tracker.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
 
+/**
+ * Extended context interface that includes sessionId injected by the plugin framework.
+ * PluginCommandContext does not include sessionId in its type definition.
+ */
+interface SessionAwareCommandContext extends PluginCommandContext {
+  sessionId: string;
+}
+
 /**
  * Handles the /pd-rollback command
  * 
@@ -15,8 +23,7 @@ export function handleRollbackCommand(ctx: PluginCommandContext): PluginCommandR
     const wctx = WorkspaceContext.fromHookContext({ workspaceDir, ...ctx.config });
     const lang = (ctx.config?.language as string) || 'en';
     const isZh = lang === 'zh';
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Reason: sessionId injected by OpenClaw plugin framework - type not available in PluginCommandContext
-    const {sessionId} = (ctx as any);
+    const { sessionId } = ctx as SessionAwareCommandContext;
 
     const args = (ctx.args || '').trim();
 
@@ -45,7 +52,7 @@ Usage:
     }
 
      
-    // eslint-disable-next-line @typescript-eslint/init-declarations
+     
     let eventId: string | null;
      
     const _triggerMethod = 'user_command' as const;

package/src/core/event-log.ts

@@ -1,3 +1,4 @@
+/* eslint-disable max-lines */
 import * as fs from 'fs';
 import * as path from 'path';
 import type {
@@ -94,7 +95,7 @@ export class EventLog {
   /**
    * Clean up event files older than EVENT_LOG_RETENTION_DAYS.
    */
-  private cleanupOldEventFiles(today: string): void {
+  private cleanupOldEventFiles(_today: string): void {
     if (EVENT_LOG_RETENTION_DAYS <= 0) return;
 
     try {
@@ -110,8 +111,8 @@ export class EventLog {
           fs.unlinkSync(filePath);
         }
       }
-    } catch {
-      // Silently fail cleanup
+    } catch (err) {
+      this.logger?.debug?.(`[PD] Event file cleanup failed (non-blocking): ${String(err)}`);
     }
   }
   
@@ -220,6 +221,7 @@ export class EventLog {
     }
   }
 
+  /* eslint-disable complexity */
   private updateStats(entry: EventLogEntry): void {
     let stats = this.statsCache.get(entry.date);
     if (!stats) {
@@ -228,8 +230,6 @@ export class EventLog {
     }
 
     if (entry.type === 'tool_call') {
-       
-      const _data = entry.data as unknown as ToolCallEventData;
       stats.tools.total++;
       if (entry.category === 'success') stats.tools.success++;
       else stats.tools.failure++;
@@ -349,7 +349,8 @@ export class EventLog {
         .map((line) => {
           try {
             return JSON.parse(line) as EventLogEntry;
-          } catch {
+          } catch (err) {
+            this.logger?.warn?.(`[PD] Corrupted event line skipped: ${String(err).slice(0, 100)}`);
             return null;
           }
         })
@@ -499,6 +500,7 @@ export class EventLog {
   /**
    * Aggregate empathy stats for a specific session.
    */
+  /* eslint-disable complexity */
   private aggregateSessionEmpathy(sessionId: string, result: EmpathyEventStats): void {
     for (const entry of this.getMergedEvents()) {
       if (entry.sessionId === sessionId && entry.type === 'pain_signal') {

package/src/core/evolution-types.ts

@@ -1,6 +1,6 @@
 /**
  * Evolution Points System V2.0 - MVP
- * 
+ *
  * Core Philosophy: Growth-driven替代Penalty-driven
  * - 起点0分，只能增加，不扣分
  * - 失败记录教训，不扣分
@@ -8,6 +8,9 @@
  * - 5级成长路径：Seed → Forest
  */
 
+// V2 queue types require TaskKind/TaskPriority from trajectory-types
+import type { TaskKind, TaskPriority } from './trajectory-types.js';
+
 // ===== 等级定义 =====
 
  
@@ -464,3 +467,32 @@ export type EvolutionLoopEvent =
   | { ts: string; type: 'principle_rolled_back'; data: PrincipleRolledBackData }
   | { ts: string; type: 'circuit_breaker_opened'; data: CircuitBreakerOpenedData }
   | { ts: string; type: 'legacy_import'; data: LegacyImportData };
+
+// V2 Queue Types (moved from evolution-worker.ts for shared use)
+export type QueueStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'canceled';
+export type TaskResolution = 'marker_detected' | 'auto_completed_timeout' | 'failed_max_retries' | 'runtime_unavailable' | 'canceled' | 'late_marker_principle_created' | 'late_marker_no_principle' | 'stub_fallback' | 'skipped_thin_violation' | 'success' | 'failure' | 'skipped';
+
+export interface EvolutionQueueItem {
+  id: string;
+  taskKind: TaskKind;
+  priority: TaskPriority;
+  source: string;
+  traceId?: string;
+  task?: string;
+  score: number;
+  reason: string;
+  timestamp: string;
+  enqueued_at?: string;
+  started_at?: string;
+  completed_at?: string;
+  assigned_session_key?: string;
+  trigger_text_preview?: string;
+  status: QueueStatus;
+  resolution?: TaskResolution;
+  session_id?: string;
+  agent_id?: string;
+  retryCount: number;
+  maxRetries: number;
+  lastError?: string;
+  resultRef?: string;
+}