principles-disciple 1.49.0 → 1.51.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.49.0",
+  "version": "1.51.0",
   "skills": [
     "./skills"
   ],

package/package.json

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

package/src/config/defaults/runtime.ts

@@ -79,9 +79,6 @@ export const EVOLUTION_WORKER_POLL_INTERVAL_MS = 15 * ONE_MINUTE_MS;
 /** Evolution queue batch size */
 export const EVOLUTION_QUEUE_BATCH_SIZE = 10;
 
-/** Pain queue dedup window (30 minutes) */
-export const PAIN_QUEUE_DEDUP_WINDOW_MS = 30 * ONE_MINUTE_MS;
-
 // ── Session Tracker Settings ───────────────────────────────────────────────────
 
 export const SESSION_TOKEN_WARNING_THRESHOLD = 8000;
@@ -90,7 +87,7 @@ export const SESSION_MAX_IDLE_MS = 30 * ONE_MINUTE_MS;
 // ── Event Log Buffer Settings ───────────────────────────────────────────────────
 
 export const EVENT_LOG_BUFFER_SIZE = 20;
-export const EVENT_LOG_FLUSH_INTERVAL_MS = 30 * ONE_MINUTE_MS;
+export const EVENT_LOG_FLUSH_INTERVAL_MS = 30 * MS_PER_SECOND;
 
 // ── Default Busy Timeout ───────────────────────────────────────────────────────
 

package/src/core/correction-cue-learner.ts

@@ -21,7 +21,7 @@ import {
   CORRECTION_SEED_KEYWORDS,
   MAX_CORRECTION_KEYWORDS,
 } from './correction-types.js';
-import { checkCooldown } from '../service/nocturnal-runtime.js';
+import { checkKeywordOptCooldown, recordKeywordOptRun } from '../service/nocturnal-runtime.js';
 import { atomicWriteFileSync } from '../utils/io.js';
 
 const KEYWORD_STORE_FILE = 'correction_keywords.json';
@@ -266,21 +266,24 @@ export class CorrectionCueLearner {
    */
   canRunKeywordOptimization(): boolean {
     // D-39-12, D-39-13: Per-workspace throttle, 4 calls/day
-    const cooldown = checkCooldown(this.stateDir, 'keyword_optimization', {
+    // Uses dedicated keywordOptRunTimestamps array to avoid pollution from regular nocturnal runs (#321)
+    const cooldown = checkKeywordOptCooldown(this.stateDir, {
       maxRunsPerWindow: 4,
       quotaWindowMs: 24 * 60 * 60 * 1000,
     });
-    return !cooldown.globalCooldownActive && !cooldown.quotaExhausted;
+    return !cooldown.quotaExhausted;
   }
 
   /**
    * Records that an optimization was performed.
-   * Updates lastOptimizedAt for the store. Throttle state is managed
-   * by checkCooldown() — no separate throttle file needed (CORR-08).
+   * Updates lastOptimizedAt for the store and records the run in the
+   * keyword-optimization quota (dedicated from regular nocturnal quota).
+   * @throws Error if quota recording fails — caller should propagate
    */
-  recordOptimizationPerformed(): void {
+  async recordOptimizationPerformed(): Promise<void> {
     this.store.lastOptimizedAt = new Date().toISOString();
     this.flush();
+    await recordKeywordOptRun(this.stateDir);
   }
 
   /**

package/src/core/init.ts

@@ -6,6 +6,7 @@ import { PD_DIRS } from './paths.js';
 import { defaultContextConfig } from '../types.js';
 import { loadStore, setPrincipleState, type PrincipleTrainingState } from './principle-training-state.js';
 import { atomicWriteFileSync } from '../utils/io.js';
+import { createDefaultKeywordStore, saveKeywordStore } from './empathy-keyword-matcher.js';
 
 /**
  * Default PROFILE.json content
@@ -245,6 +246,17 @@ export function ensureStateTemplates(ctx: { logger: PluginLogger }, stateDir: st
             fs.copyFileSync(dictTemplate, dictDest);
             ctx.logger.info(`[PD] Initialized pain dictionary in stateDir: ${dictDest} (Lang: ${language})`);
         }
+
+        // 3. Initialize empathy keyword store for new users
+        // loadKeywordStore() creates the file if missing, but we call it explicitly
+        // here so the file exists before any agent/workflow tries to read it
+        const empathyFile = path.join(stateDir, 'empathy_keywords.json');
+        if (!fs.existsSync(empathyFile)) {
+            const lang = language === 'zh' || language === 'en' ? language : 'en';
+            const store = createDefaultKeywordStore(lang);
+            saveKeywordStore(stateDir, store);
+            ctx.logger.info(`[PD] Initialized empathy keyword store in stateDir: ${empathyFile}`);
+        }
     } catch (err) {
         ctx.logger.error(`[PD] Failed to initialize state templates: ${String(err)}`);
     }

package/src/core/nocturnal-arbiter.ts

@@ -128,19 +128,24 @@ function containsPlaceholder(val: string): boolean {
 
 /**
  * Check if a string contains raw/private content patterns.
- * This is a heuristic check — not foolproof.
+ * Only matches actual code syntax or credential literals — not
+ * incidental words that happen to appear in code context.
  */
 function containsRawContent(val: string): boolean {
-  // Detect file paths with actual code (not just path shapes)
-  const rawPatterns = [
-    /function\s+\w+\s*\(/,           // function definitions
-    /class\s+\w+/,                   // class definitions
-    /const\s+\w+\s*=/,              // variable declarations
-    /import\s+.*from/,              // import statements
-    /export\s+(default\s+)?/,        // export statements
-    /api_key|secret|password|token/, // credential patterns (case insensitive)
+  // Actual code syntax — these are unambiguous and won't appear in normal decision text
+  const codePatterns = [
+    /function\s+\w+\s*\(/,           // function definitions: "function foo("
+    /class\s+\w+/,                   // class definitions: "class Foo"
+    /const\s+\w+\s*=/,              // const declarations: "const x ="
+    /let\s+\w+\s*=/,                // let declarations: "let x ="
+    /import\s+.+\s+from/,           // import statements: "import ... from"
+    /export\s+(default\s+)?/,       // export statements
+    /\bapi[_-]?key\s*=\s*\S+/i,    // api_key= or api-key= with a value
+    /\bpassword\s*=\s*\S+/i,       // password= with a value
+    /\bsecret\s*=\s*\S+/i,          // secret= with a value
+    /\btoken\s*=\s*\S+/i,           // token= with a value
   ];
-  return rawPatterns.some((p) => p.test(val));
+  return codePatterns.some((p) => p.test(val));
 }
 
 // ---------------------------------------------------------------------------

package/src/core/nocturnal-trinity.ts

@@ -704,6 +704,10 @@ export class OpenClawTrinityRuntimeAdapter implements TrinityRuntimeAdapter {
     return /timeout/i.test(detail) ? 'runtime_timeout' : 'runtime_run_failed';
   }
 
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
   async invokeDreamer(
     snapshot: NocturnalSessionSnapshot,
     principleId: string,
@@ -808,45 +812,60 @@ export class OpenClawTrinityRuntimeAdapter implements TrinityRuntimeAdapter {
     _config: TrinityConfig
   ): Promise<TrinityDraftArtifact | null> {
     this.lastFailureReason = null;
-    const runId = `scribe-${randomUUID()}`;
-    const sessionFile = this.createSessionFile('scribe');
     const prompt = this.buildScribePrompt(dreamerOutput, philosopherOutput, snapshot, principleId);
     const model = this.resolveModel();
 
-    try {
-      const result = await this.api.runtime.agent.runEmbeddedPiAgent({
-        sessionId: runId,
-        sessionFile,
-        prompt,
-        extraSystemPrompt: NOCTURNAL_SCRIBE_PROMPT,
-        config: this.loadFullConfig(),
-        provider: model.provider,
-        model: model.model,
-        timeoutMs: this.stageTimeoutMs,
-        runId,
-        disableTools: true,
-      });
+    // Retry up to 2 times on JSON parse / missing-field errors (common LLM output issues)
+    const maxAttempts = 3;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      const runId = `scribe-${randomUUID()}`;
+      const sessionFile = this.createSessionFile('scribe');
 
-      const outputText = this.extractPayloadText(result);
-      if (!outputText) {
-        this.recordFailure('runtime_session_read_failed', 'Scribe returned empty response');
-        return null;
-      }
+      try {
+        const result = await this.api.runtime.agent.runEmbeddedPiAgent({
+          sessionId: runId,
+          sessionFile,
+          prompt,
+          extraSystemPrompt: NOCTURNAL_SCRIBE_PROMPT,
+          config: this.loadFullConfig(),
+          provider: model.provider,
+          model: model.model,
+          timeoutMs: this.stageTimeoutMs,
+          runId,
+          disableTools: true,
+        });
+
+        const outputText = this.extractPayloadText(result);
+        if (!outputText) {
+          this.recordFailure('runtime_session_read_failed', 'Scribe returned empty response');
+          if (attempt < maxAttempts) { await this.sleep(1000); continue; }
+          return null;
+        }
 
-      // DEBUG: Log Scribe's actual output
-      this.api.logger?.info(`[Trinity:Scribe] Output preview: ${outputText.slice(0, 800)}`);
+        // DEBUG: Log Scribe's actual output
+        this.api.logger?.info(`[Trinity:Scribe] Output preview (attempt ${attempt}): ${outputText.slice(0, 800)}`);
 
-      return this.parseScribeOutput(outputText, snapshot, principleId, telemetry);
-    } catch (err) {
-      this.recordFailure(this.classifyRuntimeError(err), err);
-      return null;
-    } finally {
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      try { fs.unlinkSync(sessionFile); } catch (err) { this.api.logger?.warn?.(`[Trinity] Failed to delete session file: ${sessionFile}`); }
+        const artifact = this.parseScribeOutput(outputText, snapshot, principleId, telemetry);
+        if (artifact) return artifact;
+
+        // JSON parse or missing-field error — retry
+        if (attempt < maxAttempts) {
+          await this.sleep(1500);
+          continue;
+        }
+        return null;
+      } catch (err) {
+        this.recordFailure(this.classifyRuntimeError(err), err);
+        if (attempt < maxAttempts) { await this.sleep(2000); continue; }
+        return null;
+      } finally {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        try { fs.unlinkSync(sessionFile); } catch (err) { this.api.logger?.warn?.(`[Trinity] Failed to delete session file: ${sessionFile}`); }
+      }
     }
+    return null;
   }
 
-
   async close(): Promise<void> {
     // Clean up temp directory
     try {
@@ -857,7 +876,9 @@ export class OpenClawTrinityRuntimeAdapter implements TrinityRuntimeAdapter {
         }
         fs.rmSync(this.tempDir, { recursive: true, force: true });
       }
-    } catch { /* ignore cleanup errors */ }
+    } catch (err) {
+      this.api.logger?.warn?.(`[Trinity] Session cleanup failed: ${String(err)}`);
+    }
   }
 
   // ---------------------------------------------------------------------------

package/src/core/pain.ts

@@ -162,6 +162,62 @@ export function writePainFlag(projectDir: string, painData: PainFlagData): void
   atomicWriteFileSync(painFlagPath, serializeKvLines(painData));
 }
 
+/**
+ * Combined trajectory record + pain flag write.
+ *
+ * Records the pain event to trajectory first to get the AUTOINCREMENT ID,
+ * then builds and writes the pain flag with that ID embedded.
+ * This guarantees the pain→principle→compile chain has the exact matching ID.
+ *
+ * Error handling: if trajectory write fails, continues without pain_event_id.
+ * If flag write fails, the error propagates to the caller.
+ */
+export function recordAndWritePainFlag(
+  wctx: {
+    trajectory?: { recordPainEvent(input: { sessionId: string; source: string; score: number; reason?: string | null; severity?: string | null; origin?: string | null; confidence?: number | null; text?: string }): number } | null;
+    workspaceDir: string;
+  },
+  trajectoryParams: {
+    sessionId: string;
+    source: string;
+    score: number;
+    reason?: string | null;
+    severity?: string | null;
+    origin?: string | null;
+    confidence?: number | null;
+    text?: string;
+  },
+  painFlagParams: {
+    source: string;
+    score: string;
+    reason: string;
+    session_id?: string;
+    agent_id?: string;
+    is_risky?: boolean;
+    trace_id?: string;
+    trigger_text_preview?: string;
+  }
+): void {
+  const trajectoryPainId = wctx.trajectory?.recordPainEvent({
+    sessionId: trajectoryParams.sessionId,
+    source: trajectoryParams.source,
+    score: trajectoryParams.score,
+    reason: trajectoryParams.reason ?? null,
+    severity: trajectoryParams.severity ?? null,
+    origin: trajectoryParams.origin ?? null,
+    confidence: trajectoryParams.confidence ?? null,
+    text: trajectoryParams.text,
+  });
+
+  const painData = buildPainFlag({
+    ...painFlagParams,
+    pain_event_id:
+      trajectoryPainId !== undefined && trajectoryPainId >= 0 ? String(trajectoryPainId) : undefined,
+  });
+
+  writePainFlag(wctx.workspaceDir, painData);
+}
+
 /**
  * Converts a JSON pain flag object to KV format.
  */

package/src/core/principle-compiler/ledger-registrar.ts

@@ -3,7 +3,7 @@
  *
  * Registers a compiled rule into the principle tree ledger:
  * 1. Creates a LedgerRule with type 'gate', enforcement 'block', status 'proposed'
- * 2. Creates an Implementation with type 'code', lifecycleState 'candidate'
+ * 2. Creates an Implementation with type 'code', lifecycleState 'active'
  *
  * IDEMPOTENCY: If the rule already exists, returns existing registration.
  * ROLLBACK: If implementation creation fails after rule creation, attempts cleanup.

package/src/core/thinking-models.ts

@@ -64,91 +64,134 @@ const BUILTIN_PATTERNS: BuiltinPatternEntry[] = [
   {
     id: 'T-01',
     patterns: [
+      // Thinking process language (AI reasoning output)
       /let me (first )?(understand|map|outline|survey|review the (structure|architecture|dependencies))/i,
       /before (changing|editing|touching) anything/i,
       /让我先(梳理|理解|看看|盘点).*(结构|架构|依赖|全貌)/i,
       /在执行任何.*/i,
+      // Decision directive language (nocturnal artifact betterDecision)
+      /review (the |)(docs|architecture|structure|requirements|constraints|dependencies|authorization)/i,
+      /read (the |)(docs|architecture|requirements|constraints|logs?|error|stack)/i,
+      /check (the |)(docs|architecture|source|authorization|requirements|error)/i,
+      /understand (the |)(structure|architecture|requirements|constraints|full (context|picture))/i,
+      /first (to|and|,) (verify|check|review|read|understand|confirm|diagnose)/i,
+      /(verify|check|review|read|confirm) .+ first/i,
     ],
     baselineScenarios: ['exploration', 'discovery'],
   },
   {
     id: 'T-02',
     patterns: [
+      // Thinking process language
       /(type|test|contract|schema|interface) (constraint|requirement|check|validation)/i,
       /(必须|需要).*(遵守|符合|满足).*(类型|测试|契约|接口|规范)/i,
+      // Decision directive language
+      /(trust|follow|respect|adhere to|meet) (the |)(constraint|requirement|contract|interface|specification|schema|type)/i,
+      /(check|verify|validate|ensure) (the |)(constraint|requirement|contract|interface|specification|type|schema)/i,
     ],
     baselineScenarios: ['constraint-check', 'contract-verification'],
   },
   {
     id: 'T-03',
     patterns: [
+      // Thinking process language
       /based on (the |this )?(evidence|logs?|output|error|stack trace|test result)/i,
       /let me (check|verify|confirm|read|look at) (the |)(actual|source|code|file|log)/i,
       /根据(日志|证据|输出|报错|堆栈|测试结果)/i,
+      // Decision directive language (evidence-based decision)
+      /(verify|check|confirm) (the |)(error|error code|error message|actual|evidence|logs?|output|stack)/i,
+      /(error|failure) (logs?|output|stack trace|message|code) (before|then)/i,
+      /(look at|read) (the |)(error|logs?|output|stack|actual|evidence|file|code)/i,
     ],
     baselineScenarios: ['evidence-gathering', 'verification'],
   },
   {
     id: 'T-04',
     patterns: [
+      // Thinking process language
       /this (is|would be) (irreversible|destructive|permanent|not easily undone)/i,
       /(reversible|can be undone|safely roll back)/i,
       /(不可逆|破坏性|无法回滚|可以回滚|安全撤销)/i,
+      // Decision directive language
+      /(irreversible|destructive|permanent|high impact) (action|change|operation)/i,
+      /(must be|need to be|should be) (reviewed|confirmed|verified|checked) (first|before)/i,
+      /(get|obtain|ask for) (confirmation|authorization|approval|permission) (first|before)/i,
     ],
     baselineScenarios: ['risk-management', 'reversibility'],
   },
   {
     id: 'T-05',
     patterns: [
+      // Thinking process language
       /we (must|should) (not|never|avoid|prevent|ensure we don't)/i,
       /(critical|important) (not to|that we don't|to avoid)/i,
       /(绝不能|必须避免|不可|禁止|确保不会)/i,
+      // Decision directive language
+      /(must|should|need to) (not |never |avoid )?(check|verify|review|read|confirm|ask)/i,
+      /(safety|safe) (check|gate|checklist|guard)/i,
     ],
     baselineScenarios: ['guardrails', 'safety-rails'],
   },
   {
     id: 'T-06',
     patterns: [
+      // Thinking process language
       /(simpl(er|est|ify)|minimal|straightforward|lean) (approach|solution|fix|implementation)/i,
       /(simple is better|keep it simple|no need to over)/i,
       /(最简|更简单|精简|没必要过度设计)/i,
+      // Decision directive language
+      /(minimal|smallest|narrowest) (change|modification|impact|approach)/i,
+      /(only|just) (change|modify|touch|edit|affect) (the |what)/i,
     ],
     baselineScenarios: ['simplification', 'pragmatism'],
   },
   {
     id: 'T-07',
     patterns: [
+      // Thinking process language
       /(minimal|smallest|narrowest|least) (change|diff|modification|impact)/i,
       /only (change|modify|touch|edit) (the |what)/i,
       /(最小改动|最小变更|只改|只动必要部分)/i,
+      // Decision directive language
+      /(limit|narrow) (the |)(change|impact|scope|blast radius)/i,
     ],
     baselineScenarios: ['minimal-diff', 'blast-radius-control'],
   },
   {
     id: 'T-08',
     patterns: [
+      // Thinking process language
       /this (error|failure|issue) (tells us|indicates|signals|suggests|means)/i,
       /let me (stop|pause|step back|reconsider|rethink)/i,
       /这个(错误|失败|问题).*(说明|意味着|提示)/i,
       /让我(停下|暂停|退一步|重新考虑|重新审视)/i,
+      // Decision directive language
+      /(diagnose|analyze|investigate) (the |)(root |)(cause|reason|error|failure) (first|before)/i,
+      /(understand|diagnose|analyze) (the |)(error|failure|issue|problem) (first|before)/i,
     ],
     baselineScenarios: ['reflection', 'pain-response'],
   },
   {
     id: 'T-09',
     patterns: [
+      // Thinking process language
       /(break|split|decompose|divide) (this |the task |it )?(into|down)/i,
       /(step 1|first,? (we|i|let's)|phase 1)/i,
       /(拆分|分解|分步|分阶段|第一步)/i,
+      // Decision directive language
+      /(break|split|decompose|divide) (the |)(task|problem|action) (into|into steps)/i,
     ],
     baselineScenarios: ['decomposition', 'phased-execution'],
   },
   {
     id: 'T-10',
     patterns: [
+      // Thinking process language
       /let me (write|save|record|note down|document)/i,
       /memory.*scratchpad|write.*plan\.md|write.*memory|memory.*persist/i,
       /(让我.*写入|写入.*memory|记录.*scratchpad)/i,
+      // Decision directive language
+      /(write|save|record|note) (the |)(conclusion|decision|plan|next step) (to|in) (file|plan\.md|scratchpad)/i,
     ],
     baselineScenarios: ['memory-persistence', 'state-externalization'],
   },

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

@@ -105,7 +105,7 @@ export function recordGateBlockAndReturn(
   if (sessionId) {
     const GATE_BLOCK_PAIN_SCORE = 30; // Moderate — not a failure but a blocked intent
     try {
-      wctx.trajectory?.recordPainEvent?.({
+      const trajectoryPainId = wctx.trajectory?.recordPainEvent?.({
         sessionId,
         source: 'gate_blocked',
         score: GATE_BLOCK_PAIN_SCORE,
@@ -135,6 +135,7 @@ export function recordGateBlockAndReturn(
             session_id: sessionId,
             agent_id: 'main',
             is_risky: false,
+            pain_event_id: trajectoryPainId !== undefined && trajectoryPainId >= 0 ? String(trajectoryPainId) : undefined,
           });
           writePainFlag(workspaceDir, flag);
         }

package/src/hooks/lifecycle.ts

@@ -1,7 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as readline from 'readline';
-import { buildPainFlag, writePainFlag } from '../core/pain.js';
+import { recordAndWritePainFlag } from '../core/pain.js';
 import { atomicWriteFileSync } from '../utils/io.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 import { PD_DIRS } from '../core/paths.js';
@@ -154,7 +154,14 @@ export async function extractPainFromSessionFile(sessionFile: string, ctx: Plugi
 
       const hasFatal = painPoints.some(p => p.includes('[FATAL INTERCEPT]'));
       if (hasFatal) {
-        writePainFlag(workspaceDir, buildPainFlag({
+        recordAndWritePainFlag(wctx, {
+          sessionId: ctx.sessionId || 'unknown',
+          source: 'intercept_extraction',
+          score: 100,
+          reason: 'Hard intercept detected in session history compaction.',
+          severity: 'severe',
+          origin: 'system_infer',
+        }, {
           source: 'intercept_extraction',
           score: '100',
           reason: 'Hard intercept detected in session history compaction.',
@@ -162,7 +169,7 @@ export async function extractPainFromSessionFile(sessionFile: string, ctx: Plugi
           trigger_text_preview: painPoints.find(p => p.includes('[FATAL INTERCEPT]'))?.substring(0, 150) || 'Fatal intercept',
           session_id: ctx.sessionId || '',
           agent_id: ctx.agentId || '',
-        }));
+        });
       }
     } catch (err) {
       ctx.logger?.error?.(`[PD:Lifecycle] Failed to write pain signals: ${String(err)}`);

package/src/hooks/llm.ts

@@ -2,7 +2,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import type { PluginHookLlmOutputEvent, PluginHookAgentContext } from '../openclaw-sdk.js';
 import { trackLlmOutput, recordThinkingCheckpoint, resetFriction } from '../core/session-tracker.js';
-import { buildPainFlag, writePainFlag } from '../core/pain.js';
+import { recordAndWritePainFlag } from '../core/pain.js';
 import { normalizeSeverity } from '../core/empathy-types.js';
 import { ControlUiDatabase } from '../core/control-ui-db.js';
 import { DetectionService } from '../core/detection-service.js';
@@ -234,7 +234,14 @@ export function handleLlmOutput(
         const snippet = text.length > 200 ? text.substring(0, 100) + '...' + text.substring(text.length - 100) : text;
 
         try {
-            writePainFlag(ctx.workspaceDir, buildPainFlag({
+            recordAndWritePainFlag(wctx, {
+                sessionId: ctx.sessionId || 'unknown',
+                source,
+                score: painScore,
+                reason: matchedReason,
+                severity: painScore >= 70 ? 'severe' : painScore >= 40 ? 'moderate' : 'mild',
+                origin: 'system_infer',
+            }, {
                 source,
                 score: String(painScore),
                 reason: matchedReason,
@@ -242,7 +249,7 @@ export function handleLlmOutput(
                 trigger_text_preview: snippet,
                 session_id: ctx.sessionId || '',
                 agent_id: ctx.agentId || '',
-            }));
+            });
         } catch (e) {
             ctx.logger?.warn?.(`[PD:LLM] Failed to write pain flag: ${String(e)}`);
         }

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

@@ -9,6 +9,7 @@ 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';
+import { SLEEP_REFLECTION_DEDUP_WINDOW_MS } from './queue-io.js';
 
 /**
  * Read recent pain context from PAIN_FLAG file.
@@ -63,14 +64,13 @@ export function hasRecentSimilarReflection(
     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;
+        if (age > SLEEP_REFLECTION_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;

package/src/service/evolution-worker.ts

@@ -7,7 +7,7 @@ import * as path from 'path';
 import type { OpenClawPluginServiceContext, OpenClawPluginApi, PluginLogger } from '../openclaw-sdk.js';
 import { DictionaryService } from '../core/dictionary-service.js';
 import { DetectionService } from '../core/detection-service.js';
-import { ensureStateTemplates } from '../core/init.js';
+import { ensureStateTemplates, ensureCorePrinciples } from '../core/init.js';
 import { SystemLogger } from '../core/system-logger.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 import type { EventLog } from '../core/event-log.js';
@@ -1747,7 +1747,7 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
 
                             if (parsedResult?.updated) {
                                 koService.applyResult(parsedResult);
-                                learner.recordOptimizationPerformed();
+                                await learner.recordOptimizationPerformed();
                                 logger?.info?.(`[PD:EvolutionWorker] keyword_optimization applied mutations: ${parsedResult.summary}`);
                             } else {
                                 logger?.info?.(`[PD:EvolutionWorker] keyword_optimization completed with no updates`);
@@ -2080,6 +2080,7 @@ export const EvolutionWorkerService: ExtendedEvolutionWorkerService = {
         const {config} = wctx;
         const language = config.get('language') || 'en';
         ensureStateTemplates({ logger }, wctx.stateDir, language);
+        ensureCorePrinciples(wctx.stateDir, logger);
 
         const initialDelay = 5000;
         const interval = config.get('intervals.worker_poll_ms') || (15 * 60 * 1000);

package/src/service/keyword-optimization-service.ts

@@ -92,7 +92,7 @@ export class KeywordOptimizationService {
           learner.recordFalsePositive(term);
           this.logger?.info?.(`[KeywordOptimizationService] FP recorded for term="${term}" (weight x0.8)`);
         } catch (fpErr) {
-          this.logger?.warn?.(`[KeywordOptimizationService} recordFalsePositive failed for term="${term}": ${String(fpErr)}`);
+          this.logger?.warn?.(`[KeywordOptimizationService] recordFalsePositive failed for term="${term}": ${String(fpErr)}`);
         }
       }
     }

package/src/service/nocturnal-runtime.ts

@@ -24,6 +24,7 @@ import type { SessionState } from '../core/session-tracker.js';
 import { listSessions } from '../core/session-tracker.js';
 import { withLockAsync } from '../utils/file-lock.js';
 import { atomicWriteFileSync } from '../utils/io.js';
+import { DEFAULT_IDLE_THRESHOLD_MS, DEFAULT_QUOTA_WINDOW_MS } from '../config/defaults/runtime.js';
 
 // ---------------------------------------------------------------------------
 // System Session Detection
@@ -86,9 +87,6 @@ function isSystemSession(state: SessionState): boolean {
 /** File name for nocturnal runtime bookkeeping */
 export const NOCTURNAL_RUNTIME_FILE = 'nocturnal-runtime.json';
 
-/** Default idle threshold: workspace is considered idle if no activity for this duration (ms) */
-export const DEFAULT_IDLE_THRESHOLD_MS = 30 * 60 * 1000; // 30 minutes
-
 /** Default cooldown between nocturnal runs (ms) */
 export const DEFAULT_GLOBAL_COOLDOWN_MS = 60 * 60 * 1000; // 1 hour
 
@@ -98,9 +96,6 @@ export const DEFAULT_PRINCIPLE_COOLDOWN_MS = 6 * 60 * 60 * 1000; // 6 hours
 /** Default maximum nocturnal runs per quota window */
 export const DEFAULT_MAX_RUNS_PER_WINDOW = 3;
 
-/** Default quota window size (ms) */
-export const DEFAULT_QUOTA_WINDOW_MS = 24 * 60 * 60 * 1000; // 24 hours
-
 /** Abandoned session threshold: sessions inactive for longer than this are ignored (ms) */
 export const DEFAULT_ABANDONED_THRESHOLD_MS = 2 * 60 * 60 * 1000; // 2 hours
 
@@ -144,6 +139,12 @@ export interface NocturnalRuntimeState {
      */
     recentRunTimestamps: string[];
 
+    /**
+     * Sliding window of keyword optimization run timestamps.
+     * Separate from regular nocturnal runs to avoid quota pollution (fixes #321).
+     */
+    keywordOptRunTimestamps: string[];
+
     /** Metadata about last run (for debugging) */
     lastRunMeta?: {
         targetPrincipleId?: string;
@@ -206,6 +207,7 @@ function createDefaultState(): NocturnalRuntimeState {
     return {
         principleCooldowns: {},
         recentRunTimestamps: [],
+        keywordOptRunTimestamps: [],
     };
 }
 
@@ -225,6 +227,7 @@ export async function readState(stateDir: string): Promise<NocturnalRuntimeState
         return {
             principleCooldowns: parsed.principleCooldowns ?? {},
             recentRunTimestamps: parsed.recentRunTimestamps ?? [],
+            keywordOptRunTimestamps: parsed.keywordOptRunTimestamps ?? [],
             lastRunAt: parsed.lastRunAt,
             lastSuccessfulRunAt: parsed.lastSuccessfulRunAt,
             globalCooldownUntil: parsed.globalCooldownUntil,
@@ -248,6 +251,7 @@ export function readStateSync(stateDir: string): NocturnalRuntimeState {
         return {
             principleCooldowns: parsed.principleCooldowns ?? {},
             recentRunTimestamps: parsed.recentRunTimestamps ?? [],
+            keywordOptRunTimestamps: parsed.keywordOptRunTimestamps ?? [],
             lastRunAt: parsed.lastRunAt,
             lastSuccessfulRunAt: parsed.lastSuccessfulRunAt,
             globalCooldownUntil: parsed.globalCooldownUntil,
@@ -447,6 +451,81 @@ export function checkCooldown(
     };
 }
 
+/**
+ * Check keyword optimization cooldown using its dedicated timestamp array.
+ * Fixes #321: keyword optimization quota must not be polluted by regular nocturnal runs.
+ *
+ * @param stateDir - State directory
+ * @param options - Quota options (default: 4 runs per 24 hours)
+ */
+export function checkKeywordOptCooldown(
+    stateDir: string,
+    options: {
+        maxRunsPerWindow?: number;
+        quotaWindowMs?: number;
+    } = {}
+): CooldownCheckResult {
+    const {
+        maxRunsPerWindow = 4,
+        quotaWindowMs = 24 * 60 * 60 * 1000,
+    } = options;
+
+    const now = Date.now();
+    const state = readStateSync(stateDir);
+
+    const windowStart = now - quotaWindowMs;
+    const recentKeywordOpts: number[] = [];
+    for (const ts of state.keywordOptRunTimestamps) {
+        const parsed = new Date(ts).getTime();
+        if (Number.isNaN(parsed)) {
+            console.warn(`[NocturnalRuntime] Malformed timestamp in keywordOptRunTimestamps: "${ts}"`);
+            continue;
+        }
+        if (parsed > windowStart) {
+            recentKeywordOpts.push(parsed);
+        }
+    }
+
+    // Keyword optimization uses a dedicated quota (keywordOptRunTimestamps)
+    // separate from the regular nocturnal run quota (runStartTimestamps).
+    // Global/principle cooldowns from regular nocturnal runs do NOT apply here.
+    return {
+        globalCooldownActive: false,
+        globalCooldownUntil: null,
+        globalCooldownRemainingMs: 0,
+        principleCooldownActive: false,
+        principleCooldownUntil: null,
+        principleCooldownRemainingMs: 0,
+        quotaExhausted: recentKeywordOpts.length >= maxRunsPerWindow,
+        runsRemaining: Math.max(0, maxRunsPerWindow - recentKeywordOpts.length),
+    };
+}
+
+/**
+ * Record a keyword optimization run in its dedicated timestamp array.
+ * Does NOT affect regular nocturnal quota tracking.
+ *
+ * @param stateDir - State directory
+ * @param quotaWindowMs - Window size in ms (default: 24 hours)
+ */
+export async function recordKeywordOptRun(
+    stateDir: string,
+    quotaWindowMs: number = 24 * 60 * 60 * 1000
+): Promise<void> {
+    const state = await readState(stateDir);
+    const now = new Date().toISOString();
+
+    state.keywordOptRunTimestamps.push(now);
+
+    const windowStart = Date.now() - quotaWindowMs;
+    state.keywordOptRunTimestamps = state.keywordOptRunTimestamps
+        .map(ts => new Date(ts).getTime())
+        .filter(ts => ts > windowStart)
+        .map(ts => new Date(ts).toISOString());
+
+    await writeState(stateDir, state);
+}
+
 /**
  * Records a cooldown event for quota tracking (keyword_optimization etc.).
  * Adds a timestamp to recentRunTimestamps and prunes entries outside the window.
@@ -567,6 +646,7 @@ export async function clearAllCooldowns(stateDir: string): Promise<void> {
     state.globalCooldownUntil = undefined;
     state.principleCooldowns = {};
     state.recentRunTimestamps = [];
+    state.keywordOptRunTimestamps = [];
     state.lastRunMeta = undefined;
     await writeState(stateDir, state);
 }

package/src/service/nocturnal-target-selector.ts

@@ -47,9 +47,9 @@ import {
 import {
   checkWorkspaceIdle,
   checkCooldown,
-  DEFAULT_IDLE_THRESHOLD_MS,
   type IdleCheckResult,
 } from './nocturnal-runtime.js';
+import { DEFAULT_IDLE_THRESHOLD_MS } from '../config/defaults/runtime.js';
 import { detectViolation } from '../core/nocturnal-compliance.js';
 
 // ---------------------------------------------------------------------------

package/src/service/queue-io.ts

@@ -34,7 +34,7 @@ export const LOCK_MAX_RETRIES = 50;
 export const LOCK_RETRY_DELAY_MS = 50;
 export const LOCK_STALE_MS = 30_000;
 
-export const PAIN_QUEUE_DEDUP_WINDOW_MS = 4 * 60 * 60 * 1000; // 4 hours
+export const SLEEP_REFLECTION_DEDUP_WINDOW_MS = 4 * 60 * 60 * 1000; // 4 hours
 
 // ---------------------------------------------------------------------------
 // requireQueueLock — thin wrapper that adds LockUnavailableError
@@ -129,7 +129,7 @@ function hasRecentSimilarReflection(
         if (t.status !== 'completed') return false;
         if (!t.completed_at) return false;
         const age = now - new Date(t.completed_at).getTime();
-        if (age > PAIN_QUEUE_DEDUP_WINDOW_MS) return false;
+        if (age > SLEEP_REFLECTION_DEDUP_WINDOW_MS) return false;
         const taskPainKey = buildPainSourceKey(t.recentPainContext ?? { mostRecent: null, recentPainCount: 0, recentMaxPainScore: 0 });
         if (!taskPainKey) return false;
         return taskPainKey === painSourceKey;

package/tests/core/nocturnal-arbiter.test.ts

@@ -349,13 +349,21 @@ describe('Nocturnal Arbiter', () => {
       expect(result.failures.some(f => f.reason.includes('raw/private content'))).toBe(true);
     });
 
-    it('rejects betterDecision containing credential pattern', () => {
-      const artifact = makeValidArtifact({ betterDecision: 'Check the api_key before proceeding' });
+    it('rejects betterDecision containing credential assignment pattern', () => {
+      // api_key= with an actual value is a credential leak
+      const artifact = makeValidArtifact({ betterDecision: 'Check the api_key=ABC123 before proceeding' });
       const result = validateArtifact(artifact);
       expect(result.passed).toBe(false);
       expect(result.failures.some(f => f.reason.includes('raw/private content'))).toBe(true);
     });
 
+    it('accepts credential-like words without assignment (not raw content)', () => {
+      // "api_key" as a word in natural decision text is not a credential leak
+      const artifact = makeValidArtifact({ betterDecision: 'Check the api_key before proceeding' });
+      const result = validateArtifact(artifact);
+      expect(result.passed).toBe(true);
+    });
+
     it('accepts text without raw content patterns', () => {
       const artifact = makeValidArtifact({
         badDecision: 'Proceeded with editing without reading the file first',

package/tests/tools/write-pain-flag.test.ts

@@ -1,9 +1,28 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { createWritePainFlagTool } from '../../src/tools/write-pain-flag.js';
 
+// ─── Mock state shared between isolated tests ────────────────────────────────
+type MockFn = (...args: unknown[]) => unknown;
+let mockRecordPainEventFn: MockFn | undefined;
+let mockRecordPainEventThrows = false;
+
+function makeTrajectoryMock() {
+  const fn = vi.fn((...args: unknown[]) => {
+    if (mockRecordPainEventThrows) throw new Error('trajectory DB write error');
+    return mockRecordPainEventFn ? mockRecordPainEventFn(...args) : 1;
+  });
+  return { recordPainEvent: fn };
+}
+
+vi.mock('../../src/core/trajectory.js', () => ({
+  TrajectoryRegistry: {
+    get: vi.fn(() => makeTrajectoryMock()),
+  },
+}));
+
 function safeRmDir(dir: string): void {
   try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
 }
@@ -106,6 +125,8 @@ describe('write_pain_flag tool', () => {
     expect(fields.score).toBe('85');
     expect(fields.reason).toBe('Agent forgot to read file before editing');
     expect(fields.time).toBeDefined();
+    expect(fields.pain_event_id).toBeDefined();
+    expect(fields.pain_event_id).toMatch(/^\d+$/);
   });
 
   // ─────────────────────────────────────────────────────────
@@ -253,4 +274,85 @@ describe('write_pain_flag tool', () => {
     expect(text).toContain('manual'); // default source
     expect(text).toContain('No'); // default is_risky
   });
+
+  // ─────────────────────────────────────────────────────────
+  // Graceful degradation: trajectory write failure still writes flag
+  // ─────────────────────────────────────────────────────────
+  it('writes pain flag even when recordPainEvent throws', async () => {
+    // Configure the module-level mock to throw
+    mockRecordPainEventThrows = true;
+
+    const api = createMockApi(workspaceDir) as any;
+    const tool = createWritePainFlagTool(api);
+
+    const result = await tool.execute('test-degradation', {
+      reason: 'Pain signal with failing trajectory',
+      score: 60,
+      source: 'user_empathy',
+    });
+
+    // Should still succeed (graceful degradation)
+    expect(result.content[0].text).toContain('✅');
+    expect(result.content[0].text).toContain('60');
+
+    // Flag file should still exist
+    const painFlagPath = path.join(stateDir, '.pain_flag');
+    expect(fs.existsSync(painFlagPath)).toBe(true);
+    const content = fs.readFileSync(painFlagPath, 'utf-8');
+    expect(content).toContain('Pain signal with failing trajectory');
+
+    // pain_event_id should NOT be present since trajectory failed
+    expect(content).not.toContain('pain_event_id:');
+
+    // Should have logged a warning
+    expect(api._logs.some((l: any) => l.level === 'warn')).toBe(true);
+
+    // Reset for next test
+    mockRecordPainEventThrows = false;
+  });
+
+  // ─────────────────────────────────────────────────────────
+  // recordPainEvent called with correct arguments
+  // ─────────────────────────────────────────────────────────
+  it('calls recordPainEvent with correct arguments from tool params', async () => {
+    // Set up the spy result via the module-level mock factory
+    mockRecordPainEventFn = vi.fn(() => 42);
+
+    const api = createMockApi(workspaceDir) as any;
+    const tool = createWritePainFlagTool(api);
+
+    await tool.execute('test-spy', {
+      reason: 'Spy test reason',
+      score: 55,
+      source: 'tool_failure',
+      session_id: 'session-spy-001',
+      is_risky: true,
+    });
+
+    // Access the spy through the TrajectoryRegistry.get mock
+    const { TrajectoryRegistry } = await import('../../src/core/trajectory.js');
+    const mockGet = TrajectoryRegistry.get as ReturnType<typeof vi.fn>;
+    const mockTraj = mockGet.mock.results.at(-1)!.value as { recordPainEvent: ReturnType<typeof vi.fn> };
+
+    expect(mockTraj.recordPainEvent).toHaveBeenCalledOnce();
+    expect(mockTraj.recordPainEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        sessionId: 'session-spy-001',
+        source: 'tool_failure',
+        score: 55,
+        reason: 'Spy test reason',
+        severity: null,
+        origin: 'manual',
+        confidence: null,
+      })
+    );
+
+    // Also verify pain_event_id: 42 appears in the flag file
+    const painFlagPath = path.join(stateDir, '.pain_flag');
+    const content = fs.readFileSync(painFlagPath, 'utf-8');
+    expect(content).toContain('pain_event_id: 42');
+
+    // Reset for next test
+    mockRecordPainEventFn = undefined;
+  });
 });