principles-disciple 1.27.0 → 1.28.0

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) {
@@ -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/tools/write-pain-flag.ts

@@ -0,0 +1,191 @@
+import type { OpenClawPluginApi } from '../openclaw-sdk.js';
+import { Type } from '@sinclair/typebox';
+import { buildPainFlag, writePainFlag } from '../core/pain.js';
+import { resolveWorkspaceDirFromApi } from '../core/path-resolver.js';
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Pain flag contract required fields
+const PAIN_FLAG_REQUIRED_FIELDS = ['source', 'score', 'time', 'reason'] as const;
+
+/**
+ * Atomic file write: write to temp file then rename.
+ * Prevents corruption if process crashes mid-write.
+ */
+function writePainFlagAtomic(filePath: string, content: string): void {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    const tmpPath = `${filePath}.tmp.${Date.now()}.${process.pid}`;
+    fs.writeFileSync(tmpPath, content, 'utf-8');
+    fs.renameSync(tmpPath, filePath);
+}
+
+/**
+ * Creates the `write_pain_flag` tool.
+ *
+ * This tool allows the agent to record a pain signal when it recognizes
+ * that it made a mistake, violated a principle, or needs to flag an issue
+ * for later reflection.
+ *
+ * The tool wraps `buildPainFlag` + atomic `writePainFlag` to ensure:
+ * - Correct KV format serialization (never [object Object] corruption)
+ * - Atomic writes (temp file + rename, crash-safe)
+ * - Full contract compliance (source, score, time, reason)
+ *
+ * The agent should NEVER write to .pain_flag directly.
+ */
+export function createWritePainFlagTool(api: OpenClawPluginApi) {
+    return {
+        name: 'write_pain_flag',
+        description:
+            'Record a pain signal to flag mistakes, principle violations, or issues for later reflection. ' +
+            'Use this tool INSTEAD of writing .pain_flag directly. ' +
+            'Pain signals are processed by the evolution system on the next heartbeat cycle.',
+        parameters: Type.Object({
+            reason: Type.String({
+                description:
+                    'Describe specifically what went wrong. ' +
+                    'Include the error, the violated principle, or the issue. ' +
+                    'Be concrete: "I edited config.ts without reading it first, breaking the export" ' +
+                    'is better than "I made a mistake".',
+            }),
+            score: Type.Optional(Type.Number({
+                description:
+                    'Pain severity score (0-100). Default: 80. ' +
+                    'Guidelines: 30-50 (minor issue), 50-70 (moderate error), ' +
+                    '70-100 (severe principle violation or data loss risk).',
+                minimum: 0,
+                maximum: 100,
+            })),
+            source: Type.Optional(Type.String({
+                description:
+                    'Source of the pain signal. ' +
+                    'Values: manual (user flagged), tool_failure (tool error), ' +
+                    'user_empathy (user frustration), principle_violation (principle broken), ' +
+                    'human_intervention (user manually intervened). ' +
+                    'Default: manual.',
+            })),
+            session_id: Type.Optional(Type.String({
+                description:
+                    'Session ID where the pain occurred. ' +
+                    'If not provided, the system will use the current session.',
+            })),
+            is_risky: Type.Optional(Type.Boolean({
+                description:
+                    'Whether this involves a high-risk operation (e.g., writing to sensitive files). ' +
+                    'Default: false.',
+            })),
+        }),
+
+        async execute(
+            _toolCallId: string,
+            rawParams: Record<string, unknown>
+        ): Promise<{ content: { type: string; text: string }[] }> {
+            const reason = typeof rawParams.reason === 'string' ? rawParams.reason.trim() : '';
+            const score = typeof rawParams.score === 'number' ? Math.max(0, Math.min(100, Math.round(rawParams.score))) : 80;
+            const source = typeof rawParams.source === 'string' && rawParams.source.trim() ? rawParams.source.trim() : 'manual';
+            const sessionId = typeof rawParams.session_id === 'string' ? rawParams.session_id.trim() : '';
+            const isRisky = rawParams.is_risky === true;
+
+            // ── Validate required fields ──
+            if (!reason) {
+                api.logger?.warn?.('[PD:write_pain_flag] Missing required field: reason');
+                return {
+                    content: [{
+                        type: 'text',
+                        text: '❌ Error: The `reason` parameter is required.\n' +
+                            'Describe specifically what went wrong. Example:\n' +
+                            '"I edited config.ts without reading it first, breaking the export"',
+                    }],
+                };
+            }
+
+            // ── Resolve workspace ──
+            const workspaceDir = resolveWorkspaceDirFromApi(api);
+            if (!workspaceDir) {
+                api.logger?.error?.('[PD:write_pain_flag] Cannot resolve workspace directory');
+                return {
+                    content: [{
+                        type: 'text',
+                        text: '❌ Error: Cannot determine the workspace directory. ' +
+                            'Please ensure you are in an active workspace.',
+                    }],
+                };
+            }
+
+            try {
+                // ── Build pain flag data (KV format) ──
+                const painData = buildPainFlag({
+                    source,
+                    score: String(score),
+                    reason,
+                    session_id: sessionId,
+                    is_risky: isRisky,
+                });
+
+                // ── Validate contract compliance ──
+                const missingFields: string[] = [];
+                for (const field of PAIN_FLAG_REQUIRED_FIELDS) {
+                    if (!painData[field] || painData[field].trim() === '') {
+                        missingFields.push(field);
+                    }
+                }
+                if (missingFields.length > 0) {
+                    api.logger?.error?.(`[PD:write_pain_flag] Pain flag missing required fields: ${missingFields.join(', ')}`);
+                    return {
+                        content: [{
+                            type: 'text',
+                            text: `❌ Error: Pain flag is missing required fields: ${missingFields.join(', ')}. ` +
+                                'This is an internal error — please report it.',
+                        }],
+                    };
+                }
+
+                // ── Atomic write (temp file + rename) ──
+                const painFlagPath = path.join(workspaceDir, '.state', '.pain_flag');
+                const { serializeKvLines } = await import('../utils/io.js');
+                const content = serializeKvLines(painData);
+                writePainFlagAtomic(painFlagPath, content);
+
+                // ── Log success ──
+                api.logger?.info?.(
+                    `[PD:write_pain_flag] Pain signal recorded: source=${source}, score=${score}, ` +
+                    `reason="${reason.slice(0, 80)}"${reason.length > 80 ? '...' : ''}"`
+                );
+
+                // ── Agent feedback ──
+                return {
+                    content: [{
+                        type: 'text',
+                        text: `✅ Pain signal recorded successfully.\n\n` +
+                            `- **Reason**: ${reason}\n` +
+                            `- **Score**: ${score}/100\n` +
+                            `- **Source**: ${source}\n` +
+                            `- **Risk**: ${isRisky ? 'Yes' : 'No'}\n` +
+                            `- **Session**: ${sessionId || '(current)'}\n\n` +
+                            `The evolution system will process this signal on the next heartbeat cycle ` +
+                            `(typically within 60 seconds).`,
+                    }],
+                };
+            } catch (err) {
+                // ── Log failure with stack trace ──
+                const errorMsg = err instanceof Error ? err.message : String(err);
+                const stack = err instanceof Error ? err.stack?.split('\n').slice(0, 3).join(' → ') : '';
+                api.logger?.error?.(
+                    `[PD:write_pain_flag] Failed to write pain flag: ${errorMsg}` +
+                    (stack ? `\n  Stack: ${stack}` : '')
+                );
+
+                return {
+                    content: [{
+                        type: 'text',
+                        text: `❌ Failed to record pain signal: ${errorMsg}\n\n` +
+                            'The error has been logged. Please try again or report this issue.',
+                    }],
+                };
+            }
+        },
+    };
+}

package/templates/langs/en/skills/pd-pain-signal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pd-pain-signal
-description: Manually inject a pain signal into the evolution system by writing to .state/.pain_flag. TRIGGER CONDITIONS: (1) User reports agent stuck/looping/unresponsive (2) User says "record this issue", "force reflection", "trigger pain" (3) Tool failure with no follow-up action (4) User provides human intervention feedback.
+description: Manually inject a pain signal into the evolution system. TRIGGER CONDITIONS: (1) User reports agent stuck/looping/unresponsive (2) User says "record this issue", "force reflection", "trigger pain" (3) Tool failure with no follow-up action (4) User provides human intervention feedback.
 disable-model-invocation: true
 ---
 
@@ -9,30 +9,44 @@ disable-model-invocation: true
 You are now the "Manual Intervention Pain" component.
 
 **Task**:
-1. Write the user's feedback `$ARGUMENTS` as a **high-priority** pain signal to `.state/.pain_flag`.
+1. Record the user's feedback `$ARGUMENTS` as a **high-priority** pain signal.
 2. Inform the user that the signal has been injected, and suggest waiting for the next Hook trigger (e.g., Stop or PreCompact) or manually running `/reflection-log`.
 
-**Write Format** (must use this KV format, fields sorted alphabetically):
+**⚠️ Write Rules (MUST follow)**
+
+**The ONLY correct way**: Use the `write_pain_flag` tool.
 
 ```
-agent_id: <current agent ID, e.g., main/builder/diagnostician>
-is_risky: false
-reason: <user's feedback verbatim>
-score: 80
-session_id: <current session ID>
-source: human_intervention
-time: <ISO 8601 timestamp>
+write_pain_flag({
+  reason: "User feedback or error description",
+  score: 80,
+  source: "human_intervention",
+  is_risky: false
+})
 ```
 
-**Required fields** (4):
-- `source`: Fixed as `human_intervention`
-- `score`: Default `80` for manual intervention (high priority)
-- `time`: ISO 8601 timestamp
-- `reason`: User's feedback verbatim
+**Absolutely forbidden**:
+- ❌ Writing to `.state/.pain_flag` directly (any method)
+- ❌ Using bash heredoc (`cat <<EOF > .pain_flag`)
+- ❌ Using `echo "..." > .pain_flag`
+- ❌ Using `node -e` to call `writePainFlag` or `buildPainFlag`
+- ❌ Any method that `toString()` a JavaScript object to the file
+
+**Why use the tool?**
+The `write_pain_flag` tool encapsulates correct KV-format serialization, ensuring `.pain_flag` is never corrupted. Historically, direct file writes caused `[object Object]` corruption multiple times.
 
-**Optional fields** (auto-filled by system, but must be provided for manual injection):
-- `agent_id`: Current agent ID (e.g., main/builder/diagnostician)
-- `session_id`: Current session ID (from context)
-- `is_risky`: Fixed as `false`
+**Parameters**:
+- `reason` (required): The reason for the pain signal — describe what went wrong
+- `score` (optional): Pain score 0-100, default 80 (manual intervention)
+- `source` (optional): Source, default `human_intervention`
+- `is_risky` (optional): Whether this is a high-risk action, default false
 
-**Note**: `trace_id` and `trigger_text_preview` are auto-generated by the system — do NOT include them when manually injecting pain signals.
+**Example**:
+```
+write_pain_flag({
+  reason: "Agent edited a file without reading it first, breaking existing logic",
+  score: 85,
+  source: "human_intervention",
+  is_risky: false
+})
+```

package/templates/langs/zh/skills/pd-pain-signal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pd-pain-signal
-description: 手动注入痛苦信号到进化系统，写入 .state/.pain_flag。TRIGGER CONDITIONS: (1) 用户报告 agent 卡住/循环/无响应 (2) 用户说"记录这个问题"、"强制反思"、"触发痛觉" (3) 工具失败后 agent 没有后续动作 (4) 用户提供人工干预反馈。
+description: 手动注入痛苦信号到进化系统。TRIGGER CONDITIONS: (1) 用户报告 agent 卡住/循环/无响应 (2) 用户说"记录这个问题"、"强制反思"、"触发痛觉" (3) 工具失败后 agent 没有后续动作 (4) 用户提供人工干预反馈。
 disable-model-invocation: true
 ---
 
@@ -9,30 +9,44 @@ disable-model-invocation: true
 你现在是"人工干预痛觉"组件。
 
 **任务**:
-1. 将用户的反馈 `$ARGUMENTS` 作为一条**高优先级**的痛苦信号，写入 `.state/.pain_flag`。
+1. 将用户的反馈 `$ARGUMENTS` 作为一条**高优先级**的痛苦信号记录下来。
 2. 告知用户信号已注入，并建议其等待下一个 Hook 触发（如 Stop 或 PreCompact）或手动运行 `/reflection-log`。
 
-**写入格式**（必须使用以下 KV 格式，字段按字母排序）:
+**⚠️ 写入规则（必须遵守）**
+
+**唯一正确的方式**: 使用 `write_pain_flag` 工具。
 
 ```
-agent_id: <当前 agent ID，如 main/builder/diagnostician>
-is_risky: false
-reason: <用户反馈的原文>
-score: 80
-session_id: <当前 session ID>
-source: human_intervention
-time: <ISO 8601 时间>
+write_pain_flag({
+  reason: "用户反馈原文或错误描述",
+  score: 80,
+  source: "human_intervention",
+  is_risky: false
+})
 ```
 
-**必填字段**（4 个）:
-- `source`: 固定为 `human_intervention`
-- `score`: 人工干预信号默认设为 `80`（高优先级）
-- `time`: ISO 8601 时间戳
-- `reason`: 用户反馈的原文
+**绝对禁止**:
+- ❌ 直接写 `.state/.pain_flag` 文件（任何方式都不行）
+- ❌ 使用 bash heredoc（`cat <<EOF > .pain_flag`）
+- ❌ 使用 `echo "..." > .pain_flag`
+- ❌ 使用 `node -e` 调用 `writePainFlag` 或 `buildPainFlag`
+- ❌ 任何将 JavaScript 对象 `toString()` 写入文件的方式
+
+**为什么必须用工具？**
+`write_pain_flag` 工具封装了正确的序列化逻辑（KV 格式），确保 `.pain_flag` 文件不会被写坏。历史上多次因为直接写文件导致 `[object Object]` 损坏。
 
-**可选字段**（自动写入时由系统填充，人工注入时必须填写）:
-- `agent_id`: 当前智能体 ID（如 main/builder/diagnostician）
-- `session_id`: 当前会话 ID（从上下文中获取）
-- `is_risky`: 固定为 `false`
+**参数说明**:
+- `reason` (必填): 痛苦的原因，描述具体发生了什么
+- `score` (可选): 痛苦分数 0-100，默认 80（人工干预）
+- `source` (可选): 来源，默认 `human_intervention`
+- `is_risky` (可选): 是否高风险，默认 false
 
-**注意**: `trace_id` 和 `trigger_text_preview` 由系统自动生成，人工注入时**不需要**写这两个字段。
+**示例**:
+```
+write_pain_flag({
+  reason: "Agent 没有读取文件就直接编辑，导致现有逻辑被破坏",
+  score: 85,
+  source: "human_intervention",
+  is_risky: false
+})
+```