principles-disciple 1.27.0 → 1.28.1

package/src/core/pain-context-extractor.ts

@@ -235,11 +235,9 @@ export async function extractRecentConversation(
 /**
  * Extracts failed tool call context with argument correlation.
  */
-  // Reason: breaking API change - default param must precede required params for type inference compatibility
- 
 export async function extractFailedToolContext(
   sessionId: string,
-  agentId = 'main',
+  agentId: string,
   toolName: string,
   filePath?: string,
 ): Promise<string> {

package/src/core/principle-tree-migration.ts

@@ -9,8 +9,6 @@
  *   - Or run manually: node scripts/migrate-principle-tree.mjs <workspace-dir>
  */
 
-import * as fs from 'fs';
-import * as path from 'path';
 import {
   loadLedger,
   saveLedger,
@@ -23,11 +21,11 @@ export interface PrincipleTreeMigrationResult {
   migratedCount: number;
   skippedCount: number;
   errorCount: number;
-  details: Array<{
+  details: {
     principleId: string;
     status: 'migrated' | 'skipped' | 'error';
     reason?: string;
-  }>;
+  }[];
 }
 
 /**

package/src/core/thinking-os-parser.ts

@@ -45,10 +45,10 @@ export function parseThinkingOsMd(content: string): ThinkingOsDirective[] {
   // Match all <directive ...> ... </directive> blocks
   const directiveRegex = /<directive\s+([^>]*)>([\s\S]*?)<\/directive>/gi;
    
-  let match: RegExpExecArray | null = null;
+  let _match: RegExpExecArray | null = null;
 
-  while ((match = directiveRegex.exec(content)) !== null) {
-    const [, attrs, body] = match;
+  while ((_match = directiveRegex.exec(content)) !== null) {
+    const [, attrs, body] = _match;
 
     const idMatch = /id="([^"]+)"/i.exec(attrs);
     const nameMatch = /name="([^"]+)"/i.exec(attrs);

package/src/hooks/bash-risk.ts

@@ -66,7 +66,7 @@ export function analyzeBashCommand(
   // - Word joiner (U+2060)
   // - Zero-width invisible separator (U+FEFF)
    
-  const ZERO_WIDTH_CHARS = /[\u200B\u200C\u200D\u2060\uFEFF]/g;
+  const ZERO_WIDTH_CHARS = /\u200B|\u200C|\u200D|\u2060|\uFEFF/g;
   if (ZERO_WIDTH_CHARS.test(command)) {
     logger?.warn?.(`[PD_GATE] Bash command contains zero-width characters — blocking as dangerous`);
     return 'dangerous'; // Fail-closed: zero-width chars are suspicious

package/src/hooks/gfi-gate.ts

@@ -65,7 +65,7 @@ function block(
     sessionId,
     blockSource: 'gfi-gate',
   }, logger ||  
-  { warn: () => {}, error: () => {} } as const);
+  { warn: () => { /* no-op */ }, error: () => { /* no-op */ } } as const);
 }
 
  

package/src/hooks/pain.ts

@@ -191,7 +191,7 @@ export function handleAfterToolCall(
     // Only reduce tool_failure source GFI by 50%, preserve user_empathy and other sources
     // This prevents "read file success" from wiping user frustration signals
     const session = getSession(sessionId);
-    const toolFailureGfi = session?.gfiBySource?.['tool_failure'] || 0;
+    const toolFailureGfi = session?.gfiBySource?.tool_failure || 0;
     
     let resetState: SessionState;
     if (toolFailureGfi > 0) {

package/src/hooks/prompt.ts

@@ -10,6 +10,7 @@ import { extractSummary, getHistoryVersions, parseWorkingMemorySection, workingM
 import { EmpathyObserverWorkflowManager, empathyObserverWorkflowSpec, isExpectedSubagentError } from '../service/subagent-workflow/index.js';
 import { PathResolver } from '../core/path-resolver.js';
 import { isSubagentRuntimeAvailable } from '../utils/subagent-probe.js';
+import { getPendingDiagnosticianTasks } from '../core/diagnostician-task-store.js';
 import {
   matchEmpathyKeywords,
   loadKeywordStore,
@@ -366,7 +367,7 @@ export async function handleBeforePromptBuild(
   // prependContext: Only short dynamic directives: evolutionDirective + heartbeat
 
    
-  let prependSystemContext = '';
+  let prependSystemContext: string;
   let prependContext = '';
   let appendSystemContext = '';
 
@@ -644,11 +645,44 @@ ACTION: Run self-audit. If stable, reply ONLY with "HEARTBEAT_OK".
         logger?.error(`[PD:Prompt] Failed to read HEARTBEAT: ${String(e)}`);
       }
     }
+
+    // ──── 4b. Inject pending diagnostician tasks ────
+    // FIX (#283): The evolution worker writes pain diagnosis tasks to
+    // diagnostician_tasks.json. The heartbeat prompt hook must read and inject
+    // them so the LLM (acting as diagnostician) can process them.
+    try {
+      const pendingTasks = getPendingDiagnosticianTasks(wctx.stateDir);
+      if (pendingTasks.length > 0) {
+        const taskBlocks = pendingTasks
+          .slice(0, 3)
+          .map(({ id, task }) => `<diagnostician_task id="${id}">\n${task.prompt}\n</diagnostician_task>`)
+          .join('\n\n');
+
+        const pendingCount = pendingTasks.length;
+        const processingNote = pendingCount > 3
+          ? `\n\nNOTE: ${pendingCount - 3} more tasks are queued. Process these 3 first; remaining tasks will be handled on subsequent heartbeats.`
+          : '';
+
+        prependContext += `<diagnostician_tasks pending="${pendingCount}">
+You are acting as a **Pain Diagnostician**. Process the following task(s) by:
+1. Analyzing the pain signal and its context
+2. Identifying the root cause and violated principles
+3. Writing a completion marker file: .evolution_complete_<TASK_ID>
+4. Writing a diagnostic report: .diagnostician_report_<TASK_ID>.json
+
+${taskBlocks}${processingNote}
+</diagnostician_tasks>\n`;
+
+        logger?.info?.(`[PD:Prompt] Injected ${Math.min(pendingCount, 3)}/${pendingCount} pending diagnostician task(s) into heartbeat prompt`);
+      }
+    } catch (e) {
+      logger?.warn?.(`[PD:Prompt] Failed to read diagnostician tasks: ${String(e)}`);
+    }
   }
 
   // ──── 6. Dynamic Attitude Matrix (based on GFI) ────
    
-  let attitudeDirective = '';
+  let attitudeDirective: string;
   const currentGfi = session?.currentGfi || 0;
   
   if (currentGfi >= 70) {

package/src/hooks/subagent.ts

@@ -25,7 +25,7 @@ function createWorkflowManagerForType(
         warn: (m: string) => logger.warn(String(m)),
         error: (m: string) => logger.error(String(m)),
          
-        debug: () => {},
+        debug: () => { /* no-op */ },
     } as unknown as PluginLogger;
 
     switch (workflowType) {

package/src/index.ts

@@ -57,6 +57,7 @@ import { ensureWorkspaceTemplates } from './core/init.js';
 import { migrateDirectoryStructure } from './core/migration.js';
 import { SystemLogger } from './core/system-logger.js';
 import { createDeepReflectTool } from './tools/deep-reflect.js';
+import { createWritePainFlagTool } from './tools/write-pain-flag.js';
 import { PathResolver, resolveWorkspaceDirFromApi } from './core/path-resolver.js';
 import { validateWorkspaceDir } from './core/workspace-dir-validation.js';
 import { resolveRequiredWorkspaceDir, resolveWorkspaceDir, type WorkspaceResolutionContext } from './core/workspace-dir-service.js';
@@ -117,7 +118,7 @@ function computeRuntimeShadowTaskFingerprint(event: PluginHookSubagentSpawningEv
   return crypto.createHash('sha256').update(JSON.stringify(payload)).digest('hex').slice(0, 16);
 }
 
-function resolveCommandWorkspaceDirStrict(
+function _resolveCommandWorkspaceDirStrict(
   api: OpenClawPluginApi,
   ctx: WorkspaceResolutionContext,
 ): string {
@@ -773,6 +774,7 @@ const plugin = {
     });
 
     api.registerTool(createDeepReflectTool(api));
+    api.registerTool(createWritePainFlagTool(api));
   }
 };
 

package/src/service/evolution-worker.ts

@@ -356,7 +356,8 @@ function isSessionAtOrBeforeTriggerTime(
 
 function buildFallbackNocturnalSnapshot(
     sleepTask: EvolutionQueueItem,
-    extractor?: ReturnType<typeof createNocturnalTrajectoryExtractor> | null
+    extractor?: ReturnType<typeof createNocturnalTrajectoryExtractor> | null,
+    logger?: { warn?: (message: string) => void }
 ): NocturnalSessionSnapshot | null {
     const painContext = sleepTask.recentPainContext;
     if (!painContext) {
@@ -381,7 +382,7 @@ function buildFallbackNocturnalSnapshot(
             // #246-fix: Use minToolCalls=0 to avoid filtering out sessions with 0 tool calls.
             // The pain-triggering session may have no tool calls but still be worth tracking.
             const summaries = extractor.listRecentNocturnalCandidateSessions({ limit: 300, minToolCalls: 0 });
-            const match = summaries.find(s => s.sessionId === painContext.mostRecent!.sessionId);
+            const match = summaries.find(s => s.sessionId === painContext.mostRecent?.sessionId);
             if (match) {
                 realStats = {
                     totalAssistantTurns: match.assistantTurnCount,
@@ -390,8 +391,10 @@ function buildFallbackNocturnalSnapshot(
                     totalGateBlocks: match.gateBlockCount,
                 };
             }
-        } catch {
-            // Best effort — non-fatal
+        } catch (err) {
+            // #260: Log extraction failures — silent swallowing makes debugging impossible
+            // and can mask systemic trajectory DB issues.
+            logger?.warn?.(`[PD:EvolutionWorker] Failed to extract real stats for session ${painContext.mostRecent?.sessionId} (falling back to zeros): ${String(err)}`);
         }
     }
 
@@ -590,63 +593,154 @@ export function readRecentPainContext(wctx: WorkspaceContext): RecentPainContext
     return { mostRecent: null, recentPainCount: 0, recentMaxPainScore: 0 };
 }
 
+/**
+ * Build a dedup key from pain context.
+ * Returns null when no pain context is available (bypasses dedup).
+ */
+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.
+ */
+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;
+}
+
+/**
+ * Check whether a specific task kind has a pending or in-progress entry.
+ */
+function hasPendingTask(queue: EvolutionQueueItem[], taskKind: string): boolean {
+    return queue.some(
+        (t) => t.taskKind === taskKind && (t.status === 'pending' || t.status === 'in_progress'),
+    );
+}
+
+/**
+ * Decide whether to skip enqueuing due to a recent similar reflection.
+ * Returns true if skipped (with log), false if should proceed.
+ */
+function shouldSkipForDedup(
+    queue: EvolutionQueueItem[],
+    wctx: WorkspaceContext,
+    logger: PluginLogger,
+): boolean {
+    const recentPainContext = readRecentPainContext(wctx);
+    const painSourceKey = buildPainSourceKey(recentPainContext);
+
+    // Bypass dedup when there is no pain context — general idle reflections
+    // should not be throttled by the 'no_pain_context' sentinel.
+    if (!painSourceKey) return false;
+
+    const now = Date.now();
+    const recentSimilarReflection = hasRecentSimilarReflection(queue, painSourceKey, now);
+
+    if (recentSimilarReflection) {
+        const completedTime = new Date(recentSimilarReflection.completed_at!).getTime();
+        logger?.debug?.(`[PD:EvolutionWorker] Skipping sleep_reflection — similar reflection completed ${Math.round((now - completedTime) / 60000)}min ago (same pain pattern: ${painSourceKey})`);
+        return true;
+    }
+    return false;
+}
+
+/**
+ * Load and migrate the evolution queue. Returns empty array if file doesn't exist.
+ */
+function loadEvolutionQueue(queuePath: string): EvolutionQueueItem[] {
+    let rawQueue: RawQueueItem[] = [];
+    try {
+        rawQueue = JSON.parse(fs.readFileSync(queuePath, 'utf8'));
+    } catch {
+        // Queue doesn't exist yet - create empty array
+        rawQueue = [];
+    }
+    return migrateQueueToV2(rawQueue);
+}
+
+/**
+ * Build and persist a new sleep_reflection task.
+ */
+function enqueueNewSleepReflectionTask(
+    queue: EvolutionQueueItem[],
+    recentPainContext: ReturnType<typeof readRecentPainContext>,
+    queuePath: string,
+    logger: PluginLogger,
+): void {
+    const taskId = createEvolutionTaskId('nocturnal', 50, 'idle workspace', 'Sleep-mode reflection', Date.now());
+    const nowIso = new Date().toISOString();
+
+    queue.push({
+        id: taskId,
+        taskKind: 'sleep_reflection',
+        priority: 'medium',
+        score: 50,
+        source: 'nocturnal',
+        reason: 'Sleep-mode reflection triggered by idle workspace',
+        trigger_text_preview: 'Idle workspace detected',
+        timestamp: nowIso,
+        enqueued_at: nowIso,
+        status: 'pending',
+        traceId: taskId,
+        retryCount: 0,
+        maxRetries: 1, // sleep_reflection doesn't retry
+        recentPainContext,
+    });
+
+    fs.writeFileSync(queuePath, JSON.stringify(queue, null, 2), 'utf8');
+    logger?.info?.(`[PD:EvolutionWorker] Enqueued sleep_reflection task ${taskId}`);
+}
+
 /**
  * Enqueue a sleep_reflection task if one is not already pending.
  * Phase 2.4: Called when workspace is idle to trigger nocturnal reflection.
+ * Phase 3c: Dedup checks recent sleep_reflection tasks by pain source pattern
+ * to prevent redundant reflections of the same underlying issue.
  */
 async function enqueueSleepReflectionTask(
     wctx: WorkspaceContext,
-    logger: PluginLogger
+    logger: PluginLogger,
 ): Promise<void> {
     const queuePath = wctx.resolve('EVOLUTION_QUEUE');
     const releaseLock = await requireQueueLock(queuePath, logger, 'enqueueSleepReflection', EVOLUTION_QUEUE_LOCK_SUFFIX);
 
     try {
-        let rawQueue: RawQueueItem[] = [];
-        try {
-            rawQueue = JSON.parse(fs.readFileSync(queuePath, 'utf8'));
-        } catch {
-            // Queue doesn't exist yet - create empty array
-            rawQueue = [];
-        }
-
-        const queue: EvolutionQueueItem[] = migrateQueueToV2(rawQueue);
+        const queue = loadEvolutionQueue(queuePath);
 
-        // Check if a sleep_reflection task is already pending
-        const hasPendingSleepReflection = queue.some(
-            t => t.taskKind === 'sleep_reflection' && (t.status === 'pending' || t.status === 'in_progress')
-        );
-        if (hasPendingSleepReflection) {
+        // Guard 1: Skip if a sleep_reflection task is already pending/in-progress
+        if (hasPendingTask(queue, 'sleep_reflection')) {
             logger?.debug?.('[PD:EvolutionWorker] sleep_reflection task already pending/in-progress, skipping');
             return;
         }
 
-        const now = Date.now();
-        const taskId = createEvolutionTaskId('nocturnal', 50, 'idle workspace', 'Sleep-mode reflection', now);
-        const nowIso = new Date(now).toISOString();
+        // Guard 2: Dedup — skip if similar reflection completed recently
+        if (shouldSkipForDedup(queue, wctx, logger)) {
+            return;
+        }
 
-        // Attach recent pain context if available
+        // Enqueue the new task
         const recentPainContext = readRecentPainContext(wctx);
-
-        queue.push({
-            id: taskId,
-            taskKind: 'sleep_reflection',
-            priority: 'medium',
-            score: 50,
-            source: 'nocturnal',
-            reason: 'Sleep-mode reflection triggered by idle workspace',
-            trigger_text_preview: 'Idle workspace detected',
-            timestamp: nowIso,
-            enqueued_at: nowIso,
-            status: 'pending',
-            traceId: taskId,
-            retryCount: 0,
-            maxRetries: 1, // sleep_reflection doesn't retry
-            recentPainContext,
-        });
-
-        fs.writeFileSync(queuePath, JSON.stringify(queue, null, 2), 'utf8');
-        logger?.info?.(`[PD:EvolutionWorker] Enqueued sleep_reflection task ${taskId}`);
+        enqueueNewSleepReflectionTask(queue, recentPainContext, queuePath, logger);
     } finally {
         releaseLock();
     }
@@ -1565,7 +1659,7 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
                         // Phase 2: If no trajectory data, try pain-context fallback
                         if (!snapshotData && sleepTask.recentPainContext) {
                             logger?.warn?.(`[PD:EvolutionWorker] Using pain-context fallback for ${sleepTask.id}: trajectory snapshot unavailable, will try session summary from extractor`);
-                            snapshotData = buildFallbackNocturnalSnapshot(sleepTask, extractor) ?? undefined;
+                            snapshotData = buildFallbackNocturnalSnapshot(sleepTask, extractor, logger) ?? undefined;
                         }
 
                         const snapshotValidation = validateNocturnalSnapshotIngress(snapshotData);

package/src/service/health-query-service.ts

@@ -553,8 +553,8 @@ export class HealthQueryService {
     const streamPath = resolvePdPath(this.workspaceDir, 'EVOLUTION_STREAM');
     if (!fs.existsSync(streamPath)) return [];
 
-     
-    let lines: string[] = [];
+    // eslint-disable-next-line @typescript-eslint/init-declarations
+    let lines: string[];
     try {
       const raw = fs.readFileSync(streamPath, 'utf8').trim();
       if (!raw) return [];
@@ -565,8 +565,9 @@ export class HealthQueryService {
 
     const records: RecentPrincipleChange[] = [];
     for (const line of lines) {
-       
-      let event: EvolutionStreamRecord | null = null;
+
+      // eslint-disable-next-line @typescript-eslint/init-declarations
+      let event: EvolutionStreamRecord | null;
       try {
         event = JSON.parse(line) as EvolutionStreamRecord;
       } catch {
@@ -784,6 +785,7 @@ export class HealthQueryService {
   }
 
    
+  // eslint-disable-next-line @typescript-eslint/class-methods-use-this
   private getEventDedupKey(entry: EventLogEntry): string {
     const eventId = typeof entry.data?.eventId === 'string' ? entry.data.eventId : null;
     if (eventId) {
@@ -854,6 +856,7 @@ export class HealthQueryService {
   }
 
    
+  // eslint-disable-next-line @typescript-eslint/class-methods-use-this
   private resolveGateType(row: GateBlockRow): string {
     if (typeof row.gate_type === 'string' && row.gate_type.trim().length > 0) {
       return row.gate_type;
@@ -878,6 +881,7 @@ export class HealthQueryService {
   }
 
    
+  // eslint-disable-next-line @typescript-eslint/class-methods-use-this
   private scoreToStatus(score: number): string {
     if (score >= 70) return 'healthy';
     if (score >= 40) return 'warning';
@@ -885,6 +889,7 @@ export class HealthQueryService {
   }
 
    
+  // eslint-disable-next-line @typescript-eslint/class-methods-use-this
   private evolutionToStatus(tier: string, points: number): string {
     const lower = tier.toLowerCase();
     if (lower === 'forest' || lower === 'tree') return 'healthy';
@@ -893,6 +898,7 @@ export class HealthQueryService {
   }
 
    
+  // eslint-disable-next-line @typescript-eslint/class-methods-use-this
   private safeListFiles(dirPath: string, predicate: (_name: string) => boolean): string[] {
     if (!fs.existsSync(dirPath)) return [];
     try {
@@ -905,6 +911,7 @@ export class HealthQueryService {
   }
 
    
+  // eslint-disable-next-line @typescript-eslint/class-methods-use-this
   private readJsonFile<T>(filePath: string, fallback: T): T {
     if (!fs.existsSync(filePath)) return fallback;
     try {
@@ -915,11 +922,13 @@ export class HealthQueryService {
   }
 
    
+  // eslint-disable-next-line @typescript-eslint/class-methods-use-this
   private asNumber(value: unknown, fallback: number): number {
     return Number.isFinite(value) ? Number(value) : fallback;
   }
 
    
+  // eslint-disable-next-line @typescript-eslint/class-methods-use-this
   private asNullableNumber(value: unknown): number | null {
     if (Number.isFinite(value)) return Number(value);
     if (typeof value === 'string' && value.trim().length > 0) {
@@ -954,7 +963,7 @@ export class HealthQueryService {
         dailyGfiPeak,
         today,
       );
-    } catch (err) {
+    } catch {
       // Non-critical: GFI sync failure should not block queries
     }
   }
@@ -1015,7 +1024,7 @@ export class HealthQueryService {
       }
 
       return latest;
-    } catch (err) {
+    } catch {
       // Non-critical: failure to read session files should not crash the service
       return null;
     }

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

@@ -36,7 +36,6 @@ import {
 } from '../nocturnal-service.js';
 import { type TrinityStageFailure, type TrinityResult } from '../../core/nocturnal-trinity.js';
 import type { TrinityRuntimeAdapter } from '../../core/nocturnal-trinity.js';
-import type { NocturnalSessionSnapshot } from '../../core/nocturnal-trajectory-extractor.js';
 import type { RecentPainContext } from '../evolution-worker.js';
 import * as fs from 'fs';
 import * as path from 'path';