principles-disciple 1.35.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.35.0",
+  "version": "1.37.0",
   "skills": [
     "./skills"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "principles-disciple",
-  "version": "1.35.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/correction-cue-learner.ts

@@ -21,10 +21,17 @@ import {
   CORRECTION_SEED_KEYWORDS,
   MAX_CORRECTION_KEYWORDS,
 } from './correction-types.js';
-import { checkCooldown, recordCooldown } from '../service/nocturnal-runtime.js';
+import { checkCooldown } from '../service/nocturnal-runtime.js';
 
 const KEYWORD_STORE_FILE = 'correction_keywords.json';
 
+// CORR-08: Daily optimization throttle (uses checkCooldown in nocturnal-runtime.ts)
+// Note: throttle state is stored in nocturnal-runtime.json, not a separate file.
+
+// Weight bounds for correction keywords (D-39-03, D-39-15)
+const MIN_KEYWORD_WEIGHT = 0.1;
+const MAX_KEYWORD_WEIGHT = 0.9;
+
 // =========================================================================
 // Module-level cache (D-04, D-05)
 // =========================================================================
@@ -112,6 +119,8 @@ export function saveCorrectionKeywordStore(
   _correctionCueCache = null;
 }
 
+// =========================================================================
+// Throttle helpers (CORR-08)
 // =========================================================================
 // Singleton state
 // =========================================================================
@@ -217,7 +226,7 @@ export class CorrectionCueLearner {
     keyword.hitCount = (keyword.hitCount ?? 0) + 1;
 
     // D-39-15: Multiplicative weight decay x0.8 on confirmed FP
-    keyword.weight = Math.max(0.1, keyword.weight * 0.8);
+    keyword.weight = Math.max(MIN_KEYWORD_WEIGHT, keyword.weight * 0.8);
     keyword.lastHitAt = new Date().toISOString();
 
     this.flush();
@@ -238,10 +247,10 @@ export class CorrectionCueLearner {
 
   /**
    * Records that an optimization was performed.
-   * Increments the daily throttle counter and updates lastOptimizedAt.
+   * Updates lastOptimizedAt for the store. Throttle state is managed
+   * by checkCooldown() — no separate throttle file needed (CORR-08).
    */
-  async recordOptimizationPerformed(): Promise<void> {
-    await recordCooldown(this.stateDir, 24 * 60 * 60 * 1000);
+  recordOptimizationPerformed(): void {
     this.store.lastOptimizedAt = new Date().toISOString();
     this.flush();
   }
@@ -270,14 +279,20 @@ export class CorrectionCueLearner {
    * Throws if keyword not found.
    */
   updateWeight(term: string, weight: number): void {
-    const idx = this.store.keywords.findIndex(
+    const keyword = this.store.keywords.find(
       k => k.term.toLowerCase() === term.toLowerCase()
     );
-    if (idx < 0) {
+    if (!keyword) {
       throw new Error(`Keyword not found: ${term}`);
     }
 
-    this.store.keywords[idx].weight = Math.max(0.1, Math.min(0.9, weight));
+    keyword.weight = Math.max(MIN_KEYWORD_WEIGHT, Math.min(MAX_KEYWORD_WEIGHT, weight)); // Clamp to MIN-MAX_KEYWORD_WEIGHT
+    const idx = this.store.keywords.findIndex(
+      k => k.term.toLowerCase() === term.toLowerCase()
+    );
+    if (idx >= 0) {
+      this.store.keywords[idx] = { ...keyword };
+    }
     this.flush();
   }
 

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/init.ts

@@ -46,7 +46,7 @@ export function ensureWorkspaceTemplates(api: OpenClawPluginApi, workspaceDir: s
         if (fs.existsSync(commonTemplatesDir)) {
             api.logger.info(`[PD] Syncing workspace templates: ${workspaceDir}...`);
              
-            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+             
             copyRecursiveSync(commonTemplatesDir, workspaceDir, api);
         }
 
@@ -89,7 +89,7 @@ export function ensureWorkspaceTemplates(api: OpenClawPluginApi, workspaceDir: s
                 fs.mkdirSync(painDestDir, { recursive: true });
             }
              
-            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+             
             copyRecursiveSync(painTemplatesDir, painDestDir, api);
         }
 

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/hooks/prompt.ts

@@ -368,7 +368,7 @@ export async function handleBeforePromptBuild(
   // prependContext: Only short dynamic directives: evolutionDirective + heartbeat
 
    
-  // eslint-disable-next-line @typescript-eslint/init-declarations
+   
   let prependSystemContext: string;
   let prependContext = '';
   let appendSystemContext = '';
@@ -684,7 +684,7 @@ ${taskBlocks}${processingNote}
 
   // ──── 6. Dynamic Attitude Matrix (based on GFI) ────
    
-  // eslint-disable-next-line @typescript-eslint/init-declarations
+   
   let attitudeDirective: string;
   const currentGfi = session?.currentGfi || 0;
   
@@ -910,7 +910,7 @@ ${taskBlocks}${processingNote}
         const toolMatches = toolPatterns.flatMap(({ pattern, tool }) => {
           const matches: string[] = [];
            
-          // eslint-disable-next-line @typescript-eslint/init-declarations
+           
           let _m;
           const r = new RegExp(pattern.source, pattern.flags);
            

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 });
+    }
+}