principles-disciple 1.36.0 → 1.37.0

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.36.0",
+  "version": "1.37.0",
   "skills": [
     "./skills"
   ],

package/package.json

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

package/src/commands/nocturnal-train.ts

@@ -333,6 +333,7 @@ Hardware tiers:
                 proc.kill();
                 reject(new Error(`Trainer timed out after ${timeoutMs}ms`));
               }, timeoutMs);
+              timer.unref(); // Don't keep process alive for timeout
 
               proc.on('close', (code) => {
                 clearTimeout(timer);

package/src/core/event-log.ts

@@ -295,6 +295,9 @@ export class EventLog {
 
   private startFlushTimer(): void {
     this.flushTimer = setInterval(() => this.flush(), this.flushIntervalMs);
+    // Don't keep the process alive just for this timer
+    // This allows tests and CLI to exit without waiting for flush
+    this.flushTimer.unref();
   }
 
   flush(): void {

package/src/core/evolution-engine.ts

@@ -469,6 +469,7 @@ export class EvolutionEngine {
       this.retryTimer = setTimeout(() => {
         this.processRetryQueue();
       }, 1000);
+      this.retryTimer.unref(); // Don't keep process alive for retry
     }
   }
 

package/src/core/nocturnal-trinity-types.ts

@@ -5,6 +5,8 @@
  * Extracted to break circular dependency.
  */
 
+import type { TrinityArtificerContext } from './nocturnal-artificer.js';
+
 // ---------------------------------------------------------------------------
 // Dreamer Types
 // ---------------------------------------------------------------------------
@@ -92,3 +94,125 @@ export interface PhilosopherOutput {
   /** Timestamp of generation */
   generatedAt: string;
 }
+
+// ---------------------------------------------------------------------------
+// Trinity Result Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Tournament trace entry for explainability.
+ */
+export interface TournamentTraceEntry {
+  candidateIndex: number;
+  reason: string;
+}
+
+/**
+ * Analysis of a rejected candidate — why it lost the tournament.
+ * Informs training signal for "what to avoid".
+ */
+export interface RejectedAnalysis {
+  /** Mental model that led to the rejected candidate */
+  whyRejected: string;
+  /** Observable caution triggers that were missed or ignored */
+  warningSignals: string[];
+  /** Correct reasoning path that should have been seen */
+  correctiveThinking: string;
+}
+
+/**
+ * Justification for the chosen candidate — why it won the tournament.
+ * Informs training signal for "what to do".
+ */
+export interface ChosenJustification {
+  /** Why this candidate was selected over others */
+  whyChosen: string;
+  /** 1-3 transferable insights from this decision */
+  keyInsights: string[];
+  /** When this approach does NOT apply */
+  limitations: string[];
+}
+
+/**
+ * Contrastive analysis: key differences between chosen and rejected paths.
+ * Synthesizes the core lesson from the tournament.
+ */
+export interface ContrastiveAnalysis {
+  /** ONE key insight distinguishing chosen from rejected */
+  criticalDifference: string;
+  /** Pattern: "When X, do Y" */
+  decisionTrigger: string;
+  /** How to systematically avoid the rejected path */
+  preventionStrategy: string;
+}
+
+/**
+ * Telemetry about Trinity chain execution.
+ */
+export interface TrinityTelemetry {
+  chainMode: 'trinity' | 'single-reflector';
+  usedStubs: boolean;
+  dreamerPassed: boolean;
+  philosopherPassed: boolean;
+  scribePassed: boolean;
+  candidateCount: number;
+  selectedCandidateIndex: number;
+  stageFailures: string[];
+  tournamentTrace?: TournamentTraceEntry[];
+  winnerAggregateScore?: number;
+  winnerThresholdPassed?: boolean;
+  eligibleCandidateCount?: number;
+  diversityCheckPassed?: boolean;
+  candidateRiskLevels?: string[];
+  philosopher6D?: {
+    avgScores: {
+      principleAlignment: number;
+      specificity: number;
+      actionability: number;
+      executability: number;
+      safetyImpact: number;
+      uxImpact: number;
+    };
+    highRiskCount: number;
+  };
+}
+
+/**
+ * Validation failure for a Trinity stage.
+ */
+export interface TrinityStageFailure {
+  stage: 'dreamer' | 'philosopher' | 'scribe';
+  reason: string;
+}
+
+/**
+ * Result of Trinity chain execution.
+ */
+export interface TrinityResult {
+  success: boolean;
+  artifact?: TrinityDraftArtifact;
+  telemetry: TrinityTelemetry;
+  failures: TrinityStageFailure[];
+  fallbackOccurred: boolean;
+  artificerContext?: TrinityArtificerContext;
+}
+
+/**
+ * Scribe output — final structured artifact draft.
+ */
+export interface TrinityDraftArtifact {
+  selectedCandidateIndex: number;
+  badDecision: string;
+  betterDecision: string;
+  rationale: string;
+  sessionId: string;
+  principleId: string;
+  sourceSnapshotRef: string;
+  telemetry: TrinityTelemetry;
+  thinkingModelDelta?: number;
+  planningRatioGain?: number;
+  artificerContext?: TrinityArtificerContext;
+  contrastiveAnalysis?: ContrastiveAnalysis;
+  rejectedAnalysis?: RejectedAnalysis;
+  chosenJustification?: ChosenJustification;
+}

package/src/core/session-tracker.ts

@@ -166,6 +166,7 @@ function schedulePersistence(state: SessionState): void {
         persistSession(state);
         persistTimers.delete(state.sessionId);
     }, 1000);  // 1 second debounce
+    timer.unref(); // Don't keep process alive for persistence
     persistTimers.set(state.sessionId, timer);
 }
 

package/src/core/training-program.ts

@@ -362,6 +362,7 @@ export async function executeTrainer(
         proc.kill();
         reject(new Error(`Trainer timed out after ${timeoutMs}ms`));
       }, timeoutMs);
+      timer.unref(); // Don't keep process alive for timeout
 
       proc.on('close', (code) => {
         clearTimeout(timer);

package/src/hooks/gate-block-helper.ts

@@ -210,5 +210,5 @@ function scheduleTrajectoryGateBlockRetry(
       logWarn(`[PD_GATE] Retrying trajectory gate block persistence (attempt ${attempt + 1}): ${String(error)}`);
       scheduleTrajectoryGateBlockRetry(wctx, payload, attempt + 1, logWarn, logError);
     }
-  }, TRAJECTORY_GATE_BLOCK_RETRY_DELAY_MS * attempt);
+  }, TRAJECTORY_GATE_BLOCK_RETRY_DELAY_MS * attempt).unref();
 }

package/src/index.ts

@@ -87,7 +87,7 @@ const plugin = {
 
     // ── Startup Health Check: Verify workspaceDir resolution ──
     // Catches OpenClaw context bugs early (e.g., missing workspaceDir in tool hooks)
-    setTimeout(() => {
+    const healthCheckTimer = setTimeout(() => {
       const testCtx = { agentId: 'main' };
       const toolWorkspaceDir = resolveToolHookWorkspaceDirSafe(testCtx, api, 'startup.health_check');
       const toolIssue = validateWorkspaceDir(toolWorkspaceDir);
@@ -98,6 +98,7 @@ const plugin = {
         api.logger.info(`[PD:health] Tool hook workspaceDir OK: "${toolWorkspaceDir}"`);
       }
     }, 1000);
+    healthCheckTimer.unref(); // Don't keep process alive for health check
 
     const language = (api.pluginConfig?.language as string) || 'en';
 

package/src/service/central-sync-service.ts

@@ -57,6 +57,8 @@ export const CentralSyncService: OpenClawPluginService = {
 
     // Schedule periodic sync
     syncInterval = setInterval(runSyncCycle, intervalMs);
+    // Don't keep the process alive just for this timer
+    syncInterval.unref();
     
     logger?.info?.(`[PD:CentralSync] Service started, syncing every ${intervalMs / 1000}s`);
   },

package/src/service/evolution-dedup.ts

@@ -0,0 +1,74 @@
+/**
+ * Evolution Queue Deduplication Utilities
+ *
+ * Dedup logic for preventing duplicate pain tasks and redundant reflections.
+ * Extracted from evolution-worker.ts.
+ */
+
+import type { EvolutionQueueItem } from './evolution-queue-migration.js';
+
+/**
+ * Dedup window for pain queue tasks (30 minutes).
+ */
+export const PAIN_QUEUE_DEDUP_WINDOW_MS = 30 * 60 * 1000;
+
+/**
+ * Maximum length for dedup key components to prevent memory/performance issues
+ * from extremely long source or preview strings during queue scanning.
+ */
+const MAX_DEDUP_KEY_COMPONENT_LENGTH = 200;
+
+function normalizePainDedupKey(source: string, preview: string, reason?: string): string {
+    const truncate = (s: string) => s.slice(0, MAX_DEDUP_KEY_COMPONENT_LENGTH);
+    const normalizedReason = (reason || '').trim().toLowerCase().slice(0, 50);
+    return `${truncate(source.trim().toLowerCase())}::${truncate(preview.trim().toLowerCase())}::${normalizedReason}`;
+}
+
+export function findRecentDuplicateTask(
+    queue: EvolutionQueueItem[],
+    source: string,
+    preview: string,
+    now: number,
+    reason?: string
+): EvolutionQueueItem | undefined {
+    const key = normalizePainDedupKey(source, preview, reason);
+    return queue.find((task) => {
+        if (task.status === 'completed') return false;
+        const taskTime = new Date(task.enqueued_at || task.timestamp).getTime();
+        if (!Number.isFinite(taskTime) || (now - taskTime) > PAIN_QUEUE_DEDUP_WINDOW_MS) return false;
+        return normalizePainDedupKey(task.source, task.trigger_text_preview || '', task.reason) === key;
+    });
+}
+
+/**
+ * Check if a similar pain task was enqueued recently.
+ */
+export function hasRecentDuplicateTask(
+    queue: EvolutionQueueItem[],
+    source: string,
+    preview: string,
+    now: number,
+    reason?: string
+): boolean {
+    return !!findRecentDuplicateTask(queue, source, preview, now, reason);
+}
+
+/**
+ * Check if a phrase matches an active promoted rule.
+ */
+export function hasEquivalentPromotedRule(
+    dictionary: { getAllRules(): Record<string, { type: string; phrases?: string[]; pattern?: string; status: string; }> },
+    phrase: string
+): boolean {
+    const normalizedPhrase = phrase.trim().toLowerCase();
+    return Object.values(dictionary.getAllRules()).some((rule) => {
+        if (rule.status !== 'active') return false;
+        if (rule.type === 'exact_match' && Array.isArray(rule.phrases)) {
+            return rule.phrases.some((candidate) => candidate.trim().toLowerCase() === normalizedPhrase);
+        }
+        if (rule.type === 'regex' && typeof rule.pattern === 'string') {
+            return rule.pattern.trim().toLowerCase() === normalizedPhrase;
+        }
+        return false;
+    });
+}

package/src/service/evolution-pain-context.ts

@@ -0,0 +1,79 @@
+/**
+ * Evolution Pain Context Reader
+ *
+ * Reads and processes pain signal context for task enrichment.
+ * Extracted from evolution-worker.ts.
+ */
+
+import type { WorkspaceContext } from '../core/workspace-context.js';
+import { readPainFlagContract } from '../core/pain.js';
+import type { EvolutionQueueItem } from './evolution-queue-migration.js';
+import type { RecentPainContext } from './evolution-queue-migration.js';
+
+/**
+ * Read recent pain context from PAIN_FLAG file.
+ * Extracts session_id to link to trajectory DB.
+ * Returns structured pain metadata for attaching to sleep_reflection tasks.
+ * Returns null if no pain flag exists.
+ */
+export function readRecentPainContext(wctx: WorkspaceContext): RecentPainContext {
+    const contract = readPainFlagContract(wctx.workspaceDir);
+    if (contract.status !== 'valid') {
+        return { mostRecent: null, recentPainCount: 0, recentMaxPainScore: 0 };
+    }
+
+    try {
+        const score = parseInt(contract.data.score ?? '0', 10) || 0;
+        const source = contract.data.source ?? '';
+        const reason = contract.data.reason ?? '';
+        const timestamp = contract.data.time ?? '';
+        const sessionId = contract.data.session_id ?? '';
+
+        if (score > 0) {
+            return {
+                mostRecent: { score, source, reason, timestamp, sessionId },
+                recentPainCount: 1,
+                recentMaxPainScore: score,
+            };
+        }
+    } catch {
+        // Best effort — non-fatal
+    }
+
+    return { mostRecent: null, recentPainCount: 0, recentMaxPainScore: 0 };
+}
+
+/**
+ * Build a dedup key from pain context.
+ * Returns null when no pain context is available (bypasses dedup).
+ */
+export function buildPainSourceKey(
+    painCtx: ReturnType<typeof readRecentPainContext>,
+): string | null {
+    if (!painCtx.mostRecent) return null;
+    return `${painCtx.mostRecent.source}::${painCtx.mostRecent.reason?.slice(0, 50) ?? ''}`;
+}
+
+/**
+ * Check whether a similar sleep_reflection task completed recently.
+ * Phase 3c: Prevents redundant reflections of the same underlying issue.
+ */
+export function hasRecentSimilarReflection(
+    queue: EvolutionQueueItem[],
+    painSourceKey: string,
+    now: number,
+): EvolutionQueueItem | null {
+    const DEDUP_WINDOW_MS = 4 * 60 * 60 * 1000; // 4 hours
+    return queue.find((t) => {
+        if (t.taskKind !== 'sleep_reflection') return false;
+        // Only match completed tasks (exclude failed to allow retries)
+        if (t.status !== 'completed') return false;
+        if (!t.completed_at) return false;
+        const age = now - new Date(t.completed_at).getTime();
+        if (age > DEDUP_WINDOW_MS) return false;
+        const taskPainKey = buildPainSourceKey(t.recentPainContext ?? { mostRecent: null, recentPainCount: 0, recentMaxPainScore: 0 });
+        // If either side has no pain context, they don't match
+        if (!taskPainKey) return false;
+        return taskPainKey === painSourceKey;
+    }) ?? null;
+}

package/src/service/evolution-queue-lock.ts

@@ -0,0 +1,47 @@
+/**
+ * Evolution Queue Lock Utilities
+ *
+ * File locking for safe concurrent queue access.
+ * Extracted from evolution-worker.ts.
+ */
+
+import { acquireLockAsync, releaseLock as releaseImportedLock, type LockContext } from '../utils/file-lock.js';
+import { LockUnavailableError } from '../config/index.js';
+
+export const EVOLUTION_QUEUE_LOCK_SUFFIX = '.lock';
+export const LOCK_MAX_RETRIES = 50;
+export const LOCK_RETRY_DELAY_MS = 50;
+export const LOCK_STALE_MS = 30_000;
+
+export async function acquireQueueLock(
+    resourcePath: string,
+    logger: { warn?: (message: string) => void; info?: (message: string) => void } | undefined,
+    lockSuffix: string = EVOLUTION_QUEUE_LOCK_SUFFIX,
+): Promise<() => void> {
+    try {
+        const ctx: LockContext = await acquireLockAsync(resourcePath, {
+            lockSuffix,
+            maxRetries: LOCK_MAX_RETRIES,
+            baseRetryDelayMs: LOCK_RETRY_DELAY_MS,
+            lockStaleMs: LOCK_STALE_MS,
+        });
+        return () => releaseImportedLock(ctx);
+    } catch (error: unknown) {
+        const warn = logger?.warn;
+        warn?.(`[PD:EvolutionWorker] Failed to acquire lock for ${resourcePath}: ${String(error)}`);
+        throw error;
+    }
+}
+
+export async function requireQueueLock(
+    resourcePath: string,
+    logger: { warn?: (message: string) => void; info?: (message: string) => void } | undefined,
+    scope: string,
+    lockSuffix: string = EVOLUTION_QUEUE_LOCK_SUFFIX,
+): Promise<() => void> {
+    try {
+        return await acquireQueueLock(resourcePath, logger, lockSuffix);
+    } catch (err) {
+        throw new LockUnavailableError(resourcePath, scope, { cause: err });
+    }
+}

package/src/service/evolution-queue-migration.ts

@@ -0,0 +1,173 @@
+/**
+ * Evolution Queue Migration — V1 to V2 Schema
+ *
+ * Pure transformation functions and shared queue types.
+ */
+
+import type { TaskKind, TaskPriority } from '../core/trajectory-types.js';
+
+// Re-export TaskKind and TaskPriority for convenience
+export type { TaskKind, TaskPriority } from '../core/trajectory-types.js';
+
+/**
+ * Queue item status values.
+ */
+export type QueueStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'canceled';
+
+/**
+ * Task resolution strings.
+ */
+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';
+
+/**
+ * Recent pain context for sleep_reflection tasks.
+ * Attached to queue items to provide pain signal context.
+ */
+export interface RecentPainContext {
+    mostRecent: { score: number; source: string; reason: string; timestamp: string; sessionId: string } | null;
+    recentPainCount: number;
+    recentMaxPainScore: number;
+}
+
+/**
+ * Default values for new V2 fields when migrating legacy items.
+ */
+export const DEFAULT_TASK_KIND: TaskKind = 'pain_diagnosis';
+export const DEFAULT_PRIORITY: TaskPriority = 'medium';
+export const DEFAULT_MAX_RETRIES = 3;
+
+/**
+ * Legacy (pre-V2) queue item schema.
+ */
+export interface LegacyEvolutionQueueItem {
+    id: string;
+    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?: string;
+    resolution?: string;
+    session_id?: string;
+    agent_id?: string;
+    taskKind?: string;
+    priority?: string;
+    retryCount?: number;
+    maxRetries?: number;
+    lastError?: string;
+    resultRef?: string;
+}
+
+/**
+ * V2 queue item schema.
+ */
+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;
+    recentPainContext?: RecentPainContext;
+}
+
+export type RawQueueItem = Record<string, unknown>;
+
+/**
+ * Migrate a legacy queue item to V2 schema.
+ * Old items without taskKind are assumed to be pain_diagnosis for backward compatibility.
+ */
+export function migrateToV2(item: LegacyEvolutionQueueItem): {
+    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;
+} {
+    return {
+        id: item.id,
+        taskKind: (item.taskKind as TaskKind) || DEFAULT_TASK_KIND,
+        priority: (item.priority as TaskPriority) || DEFAULT_PRIORITY,
+        source: item.source,
+        traceId: item.traceId,
+        task: item.task,
+        score: item.score,
+        reason: item.reason,
+        timestamp: item.timestamp,
+        enqueued_at: item.enqueued_at,
+        started_at: item.started_at,
+        completed_at: item.completed_at,
+        assigned_session_key: item.assigned_session_key,
+        trigger_text_preview: item.trigger_text_preview,
+        status: (item.status as QueueStatus) || 'pending',
+        resolution: item.resolution as TaskResolution | undefined,
+        session_id: item.session_id,
+        agent_id: item.agent_id,
+        retryCount: item.retryCount || 0,
+        maxRetries: item.maxRetries || DEFAULT_MAX_RETRIES,
+        lastError: item.lastError,
+        resultRef: item.resultRef,
+    };
+}
+
+/**
+ * Check if an item is a legacy (pre-V2) queue item.
+ */
+export function isLegacyQueueItem(item: RawQueueItem): boolean {
+    return item && typeof item === 'object' && !('taskKind' in item);
+}
+
+/**
+ * Migrate entire queue to V2 schema if needed.
+ */
+export function migrateQueueToV2(queue: RawQueueItem[]): ReturnType<typeof migrateToV2>[] {
+    return queue.map(item => isLegacyQueueItem(item) ? migrateToV2(item as unknown as LegacyEvolutionQueueItem) : item as unknown as ReturnType<typeof migrateToV2>);
+}

package/src/service/evolution-worker.ts

@@ -2563,6 +2563,7 @@ export const EvolutionWorkerService: ExtendedEvolutionWorkerService = {
             }
 
             timeoutId = setTimeout(runCycle, interval);
+            timeoutId.unref();
         }
 
         timeoutId = setTimeout(() => {
@@ -2578,11 +2579,14 @@ export const EvolutionWorkerService: ExtendedEvolutionWorkerService = {
                 }
                 // processPromotion removed (D-06)
                 timeoutId = setTimeout(runCycle, interval);
+                timeoutId.unref();
             })().catch((err) => {
                 if (logger) logger.error(`[PD:EvolutionWorker] Startup worker cycle failed: ${String(err)}`);
                 timeoutId = setTimeout(runCycle, interval);
+                timeoutId.unref();
             });
         }, initialDelay);
+        timeoutId.unref();
     },
 
     stop(ctx: OpenClawPluginServiceContext): void {

package/src/service/subagent-workflow/workflow-manager-base.ts

@@ -303,6 +303,7 @@ export abstract class WorkflowManagerBase implements WorkflowManager {
                 await this.notifyWaitResult(workflowId, 'error', errMsg);
             }
         }, 100);
+        timeout.unref(); // Don't keep process alive for wait poll
 
         this.activeWorkflows.set(workflowId, timeout);
     }