principles-disciple 1.35.0 → 1.36.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.36.0",
   "skills": [
     "./skills"
   ],

package/package.json

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

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/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/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/service/evolution-worker.ts

@@ -16,11 +16,10 @@ import { getEvolutionLogger } from '../core/evolution-logger.js';
 import type { TaskKind, TaskPriority } from '../core/trajectory-types.js';
 export type { TaskKind, TaskPriority } from '../core/trajectory-types.js';
 import { LockUnavailableError } from '../config/index.js';
-import { PAIN_QUEUE_DEDUP_WINDOW_MS } from '../config/defaults/runtime.js';
 import { checkWorkspaceIdle, checkCooldown } from './nocturnal-runtime.js';
 import { loadNocturnalConfig } from './nocturnal-config.js';
 import { WorkflowStore } from './subagent-workflow/workflow-store.js';
-import type { WorkflowRow, RecentPainContext } from './subagent-workflow/types.js';
+import type { WorkflowRow } from './subagent-workflow/types.js';
 import { EmpathyObserverWorkflowManager } from './subagent-workflow/empathy-observer-workflow-manager.js';
 import { DeepReflectWorkflowManager } from './subagent-workflow/deep-reflect-workflow-manager.js';
 import { NocturnalWorkflowManager, nocturnalWorkflowSpec } from './subagent-workflow/nocturnal-workflow-manager.js';
@@ -32,22 +31,14 @@ import {
 import { validateNocturnalSnapshotIngress } from '../core/nocturnal-snapshot-contract.js';
 import { isExpectedSubagentError } from './subagent-workflow/subagent-error-utils.js';
 import { readPainFlagContract } from '../core/pain.js';
-import { CorrectionObserverWorkflowManager, correctionObserverWorkflowSpec } from './correction-observer-workflow-manager.js';
-import type { CorrectionObserverPayload } from './correction-observer-types.js';
+import { CorrectionObserverWorkflowManager, correctionObserverWorkflowSpec } from './subagent-workflow/correction-observer-workflow-manager.js';
+import type { CorrectionObserverPayload } from './subagent-workflow/correction-observer-types.js';
 import { KeywordOptimizationService } from './keyword-optimization-service.js';
 import { TrajectoryRegistry } from '../core/trajectory.js';
 import { CorrectionCueLearner } from '../core/correction-cue-learner.js';
-import { WORKFLOW_TTL_MS } from '../config/defaults/runtime.js';
-import { OpenClawTrinityRuntimeAdapter } from '../core/nocturnal-trinity.js';
 
-/**
- * Atomic file write — write to temp then rename to prevent partial writes on crash.
- */
-function atomicWriteFileSync(filePath: string, data: string): void {
-  const tmpPath = filePath + '.tmp';
-  fs.writeFileSync(tmpPath, data, 'utf8');
-  fs.renameSync(tmpPath, filePath);
-}
+const WORKFLOW_TTL_MS = 5 * 60 * 1000; // 5 minutes default TTL for helper workflows
+import { OpenClawTrinityRuntimeAdapter } from '../core/nocturnal-trinity.js';
 
 // ── Workflow Watchdog ────────────────────────────────────────────────────────
 // Detects stale/orphaned workflows, invalid results, and cleanup failures.
@@ -209,6 +200,27 @@ let timeoutId: NodeJS.Timeout | null = null;
 export type QueueStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'canceled';
 export type TaskResolution = 'marker_detected' | 'auto_completed_timeout' | 'failed_max_retries' | 'runtime_unavailable' | 'canceled' | 'late_marker_principle_created' | 'late_marker_no_principle' | 'stub_fallback' | 'skipped_thin_violation';
 
+/**
+ * Recent pain context attached to sleep_reflection tasks.
+ * Carries explicit recent pain signal metadata without being a separate task kind.
+ * Used by NocturnalTargetSelector for ranking bias and context enrichment.
+ */
+export interface RecentPainContext {
+  /** Most recent unresolved pain event */
+  mostRecent: {
+    score: number;
+    source: string;
+    reason: string;
+    timestamp: string;
+    /** Session ID where the pain occurred */
+    sessionId: string;
+  } | null;
+  /** Count of pain events in the recent window (for signal strength) */
+  recentPainCount: number;
+  /** Highest pain score in the recent window */
+  recentMaxPainScore: number;
+}
+
 export interface EvolutionQueueItem {
     // Core identity
     id: string;
@@ -414,6 +426,7 @@ function buildFallbackNocturnalSnapshot(
     };
 }
 
+const PAIN_QUEUE_DEDUP_WINDOW_MS = 30 * 60 * 1000;
 
 // P0 fix: File lock constants and helper for queue operations (prevents TOCTOU race)
 export const EVOLUTION_QUEUE_LOCK_SUFFIX = '.lock';
@@ -711,7 +724,7 @@ function enqueueNewSleepReflectionTask(
         recentPainContext,
     });
 
-    atomicWriteFileSync(queuePath, JSON.stringify(queue, null, 2));
+    fs.writeFileSync(queuePath, JSON.stringify(queue, null, 2), 'utf8');
     logger?.info?.(`[PD:EvolutionWorker] Enqueued sleep_reflection task ${taskId}`);
 }
 
@@ -856,7 +869,7 @@ async function doEnqueuePainTask(
             retryCount: 0, maxRetries: 3,
         });
 
-        atomicWriteFileSync(queuePath, JSON.stringify(queue, null, 2));
+        fs.writeFileSync(queuePath, JSON.stringify(queue, null, 2), 'utf8');
         fs.appendFileSync(painFlagPath, `\nstatus: queued\ntask_id: ${taskId}\n`, 'utf8');
         result.enqueued = true;
 
@@ -1645,7 +1658,7 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
 
             // Write claimed state (includes any pain changes from above) and release lock
             if (queueChanged) {
-                atomicWriteFileSync(queuePath, JSON.stringify(queue, null, 2));
+                fs.writeFileSync(queuePath, JSON.stringify(queue, null, 2), 'utf8');
             }
             releaseLock();
             for (const sleepTask of sleepReflectionTasks) {
@@ -1899,7 +1912,7 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
                             freshQueue[idx] = sleepTask;
                         }
                     }
-                    atomicWriteFileSync(queuePath, JSON.stringify(freshQueue, null, 2));
+                    fs.writeFileSync(queuePath, JSON.stringify(freshQueue, null, 2), 'utf8');
 
                     // Log completions to EvolutionLogger
                     for (const sleepTask of sleepReflectionTasks) {
@@ -1992,14 +2005,10 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
                     };
 
                     // Dispatch LLM subagent via CorrectionObserverWorkflowManager
-                    const subagent = api?.runtime?.subagent;
-                    if (!subagent) {
-                        throw new Error('[PD:EvolutionWorker] subagent runtime not available for keyword_optimization');
-                    }
                     const manager = new CorrectionObserverWorkflowManager({
                         workspaceDir: wctx.workspaceDir,
                         logger,
-                        subagent,
+                        subagent: api?.runtime?.subagent!,
                         agentSession: api?.runtime?.agent?.session,
                     });
 
@@ -2013,11 +2022,7 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
                         workflowId = handle.workflowId;
                         koTask.resultRef = workflowId;
                     } else {
-                        // isPolling implies resultRef exists (checked above)
-                        workflowId = koTask.resultRef;
-                        if (!workflowId) {
-                            throw new Error(`[PD:EvolutionWorker] keyword_optimization task ${koTask.id} has no resultRef in polling mode`);
-                        }
+                        workflowId = koTask.resultRef!;
                     }
 
                     // Poll workflow state
@@ -2029,7 +2034,7 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
 
                             if (parsedResult?.updated) {
                                 koService.applyResult(parsedResult);
-                                await learner.recordOptimizationPerformed();
+                                learner.recordOptimizationPerformed();
                                 logger?.info?.(`[PD:EvolutionWorker] keyword_optimization applied mutations: ${parsedResult.summary}`);
                             } else {
                                 logger?.info?.(`[PD:EvolutionWorker] keyword_optimization completed with no updates`);
@@ -2082,7 +2087,7 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
                         freshQueue.push(koTask);
                     }
                 }
-                fs.writeFileSync(queuePath, JSON.stringify(freshQueue, null, 2));
+                fs.writeFileSync(queuePath, JSON.stringify(freshQueue, null, 2), 'utf8');
             } catch (koResultErr) {
                 logger?.warn?.(`[PD:EvolutionWorker] Failed to write keyword_optimization results: ${String(koResultErr)}`);
             } finally {
@@ -2092,7 +2097,7 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
         }
 
         if (queueChanged) {
-            atomicWriteFileSync(queuePath, JSON.stringify(queue, null, 2));
+            fs.writeFileSync(queuePath, JSON.stringify(queue, null, 2), 'utf8');
         }
 
         // Pipeline observability: log stage-level summary at end of cycle
@@ -2210,7 +2215,7 @@ export async function registerEvolutionTaskSession(
         if (!task.started_at) {
             task.started_at = new Date().toISOString();
         }
-        atomicWriteFileSync(queuePath, JSON.stringify(queue, null, 2));
+        fs.writeFileSync(queuePath, JSON.stringify(queue, null, 2), 'utf8');
         return true;
     } finally {
         releaseLock();
@@ -2250,7 +2255,7 @@ interface WorkerStatusReport {
 function writeWorkerStatus(stateDir: string, report: WorkerStatusReport): void {
     try {
         const statusPath = path.join(stateDir, 'worker-status.json');
-        atomicWriteFileSync(statusPath, JSON.stringify(report, null, 2));
+        fs.writeFileSync(statusPath, JSON.stringify(report, null, 2), 'utf8');
     } catch (statusErr) {
         // Non-critical: worker-status.json is for monitoring, failure is acceptable
         // (no logger available in this standalone helper)
@@ -2281,7 +2286,7 @@ async function processEvolutionQueueWithResult(
         const purgeResult = purgeStaleFailedTasks(queue, logger);
         if (purgeResult.purged > 0) {
             // Write back the cleaned queue
-            atomicWriteFileSync(queuePath, JSON.stringify(queue, null, 2));
+            fs.writeFileSync(queuePath, JSON.stringify(queue, null, 2), 'utf8');
         }
 
         queueResult.total = queue.length;

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

@@ -7,7 +7,7 @@
  */
 
 import { CorrectionCueLearner } from '../core/correction-cue-learner.js';
-import type { CorrectionObserverResult } from './correction-observer-types.js';
+import type { CorrectionObserverResult } from './subagent-workflow/correction-observer-types.js';
 import type { PluginLogger } from '../openclaw-sdk.js';
 import { TrajectoryRegistry } from '../core/trajectory.js';
 
@@ -137,4 +137,4 @@ export type TrajectoryHistoryEntry = {
 };
 
 /** Re-export CorrectionObserverPayload for convenience */
-export type { CorrectionObserverPayload } from './correction-observer-types.js';
+export type { CorrectionObserverPayload } from './subagent-workflow/correction-observer-types.js';

package/src/service/subagent-workflow/correction-observer-types.ts

@@ -0,0 +1,69 @@
+/**
+ * Correction Observer Workflow - Type Definitions
+ *
+ * Types for the correction observer LLM optimization workflow.
+ * This workflow dispatches an LLM subagent to analyze keyword performance
+ * and recommend ADD/UPDATE/REMOVE actions for the correction keyword store.
+ */
+
+import type { SubagentWorkflowSpec } from './types.js';
+
+/**
+ * Input passed to the correction observer subagent.
+ */
+export interface CorrectionObserverPayload {
+  /** Parent session that triggered the optimization */
+  parentSessionId: string;
+  /** Workspace directory */
+  workspaceDir: string;
+  /** Current keyword store summary for context */
+  keywordStoreSummary: {
+    totalKeywords: number;
+    terms: Array<{
+      term: string;
+      weight: number;
+      hitCount: number;
+      truePositiveCount: number;
+      falsePositiveCount: number;
+    }>;
+  };
+  /** Recent user messages for pattern analysis */
+  recentMessages: string[];
+
+  /**
+   * Trajectory history: user turns where correctionDetected=true (D-40-08).
+   * Includes term matched, timestamp, sessionId for FPR trend analysis.
+   */
+  trajectoryHistory: Array<{
+    sessionId: string;
+    timestamp: string;
+    term: string;
+    userMessage: string;
+  }>;
+}
+
+/**
+ * Result from the correction observer subagent.
+ */
+export interface CorrectionObserverResult {
+  /** Whether any changes were made */
+  updated: boolean;
+  /** The optimization decisions returned by the LLM */
+  updates: Record<string, {
+    action: 'add' | 'update' | 'remove';
+    weight?: number;
+    falsePositiveRate?: number;
+    reasoning: string;
+  }>;
+  /** Human-readable summary */
+  summary: string;
+}
+
+/**
+ * Workflow spec for the correction observer optimization workflow.
+ */
+export interface CorrectionObserverWorkflowSpec extends SubagentWorkflowSpec<CorrectionObserverResult> {
+  workflowType: 'correction_observer';
+  payload: CorrectionObserverPayload;
+  result?: CorrectionObserverResult;
+}

package/src/service/subagent-workflow/correction-observer-workflow-manager.ts

@@ -0,0 +1,246 @@
+/**
+ * CorrectionObserverWorkflowManager
+ *
+ * Workflow manager that dispatches an LLM subagent to optimize correction
+ * keywords based on recent match performance data and user feedback.
+ *
+ * Follows the established WorkflowManagerBase pattern from EmpathyObserverWorkflowManager.
+ */
+
+import type { PluginLogger } from '../../openclaw-sdk.js';
+import type {
+    SubagentWorkflowSpec,
+    WorkflowMetadata,
+    WorkflowResultContext,
+    WorkflowPersistContext,
+    WorkflowHandle,
+} from './types.js';
+import type { RuntimeDirectDriver } from './runtime-direct-driver.js';
+import { WorkflowManagerBase } from './workflow-manager-base.js';
+import { isSubagentRuntimeAvailable } from '../../utils/subagent-probe.js';
+import type {
+    CorrectionObserverPayload,
+    CorrectionObserverResult,
+} from './correction-observer-types.js';
+
+const WORKFLOW_SESSION_PREFIX = 'agent:main:subagent:workflow-correction-';
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+
+// Prompt formatting constants
+const MAX_TRAJECTORY_MESSAGE_LENGTH = 80;
+
+// ── Options ─────────────────────────────────────────────────────────────────
+
+export interface CorrectionObserverWorkflowOptions {
+    workspaceDir: string;
+    logger: PluginLogger;
+    subagent: RuntimeDirectDriver['subagent'];
+    /** Pass api.runtime.agent.session to enable heartbeat-safe cleanup (#188) */
+    agentSession?: RuntimeDirectDriver['agentSession'];
+}
+
+// ── Helper Functions ─────────────────────────────────────────────────────────
+
+/**
+ * Extract raw assistant text from messages or assistantTexts array.
+ */
+function extractAssistantTextForSpec(messages: unknown[], assistantTexts?: string[]): string {
+    if (assistantTexts && assistantTexts.length > 0) {
+        return assistantTexts[assistantTexts.length - 1] || '';
+    }
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i] as { role?: string; content?: unknown };
+        if (msg?.role !== 'assistant') continue;
+        if (typeof msg.content === 'string') return msg.content;
+        if (Array.isArray(msg.content)) {
+            const txt = msg.content
+                .filter((part: unknown) => part && typeof part === 'object' && (part as { type?: string }).type === 'text' && typeof (part as { text?: unknown }).text === 'string')
+                .map((part: unknown) => (part as { text: string }).text)
+                .join('\n');
+            if (txt) return txt;
+        }
+    }
+    return '';
+}
+
+/**
+ * Parse correction observer JSON payload from raw text.
+ */
+function parseCorrectionObserverPayload(rawText: string): CorrectionObserverResult | null {
+    if (!rawText?.trim()) return null;
+    try {
+        return JSON.parse(rawText.trim()) as CorrectionObserverResult;
+    } catch {
+        const match = /\{[\s\S]*\}/.exec(rawText);
+        if (!match) return null;
+        try {
+            return JSON.parse(match[0]) as CorrectionObserverResult;
+        } catch {
+            return null;
+        }
+    }
+}
+
+// ── Workflow Spec ─────────────────────────────────────────────────────────────
+
+export const correctionObserverWorkflowSpec: SubagentWorkflowSpec<CorrectionObserverResult> = {
+    workflowType: 'correction_observer',
+    transport: 'runtime_direct',
+    timeoutMs: 30_000,
+    ttlMs: 300_000,
+    shouldDeleteSessionAfterFinalize: true,
+
+    buildPrompt(taskInput: unknown, _metadata: WorkflowMetadata): string {
+        const payload = taskInput as CorrectionObserverPayload;
+        const { keywordStoreSummary, recentMessages, trajectoryHistory } = payload;
+
+        const termsList = keywordStoreSummary.terms
+            .map(t => `  - term="${t.term}", weight=${t.weight}, hits=${t.hitCount}, TP=${t.truePositiveCount}, FP=${t.falsePositiveCount}`)
+            .join('\n');
+
+        const messages = recentMessages.length > 0
+            ? recentMessages.map(m => `  - ${JSON.stringify(m)}`).join('\n')
+            : '  (none)';
+
+        const trajectory = trajectoryHistory.length > 0
+            ? trajectoryHistory.map(t => `  - [${t.sessionId}] ${t.term} (${t.timestamp}): ${t.userMessage.substring(0, MAX_TRAJECTORY_MESSAGE_LENGTH)}`)
+              .join('\n')
+            : '  (none)';
+
+        return [
+            'You are a correction keyword optimizer.',
+            '',
+            '## TASK',
+            'Analyze the current correction keyword store and recent user messages.',
+            'Recommend ADD/UPDATE/REMOVE actions to improve correction cue accuracy.',
+            '',
+            '## Current Keyword Store (' + keywordStoreSummary.totalKeywords + ' terms):',
+            termsList,
+            '',
+            '## Recent User Messages (' + recentMessages.length + ' messages):',
+            messages,
+            '',
+            '## Correction Trajectory (recent confirmed corrections, D-40-08):',
+            trajectory,
+            '',
+            '## Rules:',
+            '- ADD: If a correction pattern is detected in messages but not in store',
+            '- UPDATE: If a term\'s weight should change based on TP/FP ratio',
+            '- REMOVE: If a term has 0 hits after many uses AND high false positive rate (>0.3)',
+            '- Keep reasoning concise (max 100 chars)',
+            '- Weight range: 0.1-0.9',
+            '',
+            'Return strict JSON (no markdown):',
+            '{"updated": boolean, "updates": {...}, "summary": string}',
+        ].join('\n');
+    },
+
+    async parseResult(ctx: WorkflowResultContext): Promise<CorrectionObserverResult | null> {
+        const rawText = extractAssistantTextForSpec(ctx.messages, ctx.assistantTexts);
+        return parseCorrectionObserverPayload(rawText);
+    },
+
+    async persistResult(_ctx: WorkflowPersistContext<CorrectionObserverResult>): Promise<void> {
+        // Result persistence is handled by the caller (evolution-worker.ts)
+        // which reads the result and applies keyword store updates.
+        // This spec handles only the LLM dispatch and result parsing.
+    },
+
+    shouldFinalizeOnWaitStatus(status: 'ok' | 'error' | 'timeout'): boolean {
+        return status === 'ok';
+    },
+};
+
+// ── Manager Class ─────────────────────────────────────────────────────────────
+
+export class CorrectionObserverWorkflowManager extends WorkflowManagerBase {
+    constructor(opts: CorrectionObserverWorkflowOptions) {
+        super({
+            workspaceDir: opts.workspaceDir,
+            logger: opts.logger,
+            subagent: opts.subagent,
+            agentSession: opts.agentSession,
+            workflowType: 'correction_observer',
+            sessionPrefix: WORKFLOW_SESSION_PREFIX,
+            defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
+            defaultTtlMs: DEFAULT_TTL_MS,
+        });
+    }
+
+    async startWorkflow<TResult>(
+        spec: SubagentWorkflowSpec<TResult>,
+        options: {
+            parentSessionId: string;
+            workspaceDir?: string;
+            taskInput: unknown;
+            metadata?: Record<string, unknown>;
+        }
+    ): Promise<WorkflowHandle> {
+        // Surface degrade: skip boot sessions
+        if (options.parentSessionId.startsWith('boot-')) {
+            this.logger.info(`[PD:CorrectionObserver] Skipping workflow: boot session`);
+            throw new Error(`CorrectionObserverWorkflowManager: cannot start workflow for boot session`);
+        }
+
+        // Surface degrade: check subagent runtime availability
+        if (!isSubagentRuntimeAvailable(this.driver.getSubagent())) {
+            this.logger.info(`[PD:CorrectionObserver] Skipping workflow: subagent runtime unavailable`);
+            throw new Error(`CorrectionObserverWorkflowManager: subagent runtime unavailable`);
+        }
+
+        if (spec.transport !== 'runtime_direct') {
+            throw new Error(`CorrectionObserverWorkflowManager only supports runtime_direct transport`);
+        }
+
+        return super.startWorkflow(spec, options);
+    }
+
+    /**
+     * Get the parsed workflow result for a completed workflow.
+     * Used by callers (evolution-worker.ts) to retrieve LLM optimization results
+     * after the workflow completes, so mutations can be applied to the keyword store.
+     */
+    async getWorkflowResult(workflowId: string): Promise<CorrectionObserverResult | null> {
+        const workflow = this.store.getWorkflow(workflowId);
+        if (!workflow) return null;
+
+        const result = await this.driver.getResult({ sessionKey: workflow.child_session_key, limit: 20 });
+        return correctionObserverWorkflowSpec.parseResult({
+            messages: result.messages,
+            assistantTexts: result.assistantTexts,
+            metadata: JSON.parse(workflow.metadata_json) as WorkflowMetadata,
+            waitStatus: 'ok',
+        });
+    }
+
+    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+    protected override createWorkflowMetadata<TResult>(
+        spec: SubagentWorkflowSpec<TResult>,
+        options: {
+            parentSessionId: string;
+            workspaceDir?: string;
+            taskInput: unknown;
+            metadata?: Record<string, unknown>;
+        },
+        now: number
+    ): WorkflowMetadata {
+        return {
+            parentSessionId: options.parentSessionId,
+            workspaceDir: options.workspaceDir,
+            taskInput: options.taskInput,
+            startedAt: now,
+            workflowType: spec.workflowType,
+            ...options.metadata,
+        };
+    }
+}
+
+// ── Factory ─────────────────────────────────────────────────────────────────
+
+export function createCorrectionObserverWorkflowManager(
+    opts: CorrectionObserverWorkflowOptions
+): CorrectionObserverWorkflowManager {
+    return new CorrectionObserverWorkflowManager(opts);
+}

package/src/service/subagent-workflow/index.ts

@@ -65,3 +65,16 @@ export type {
     WorkflowEventRow,
     WorkflowDebugSummary,
 } from './types.js';
+
+export {
+    CorrectionObserverWorkflowManager,
+    createCorrectionObserverWorkflowManager,
+    correctionObserverWorkflowSpec,
+    type CorrectionObserverWorkflowOptions,
+} from './correction-observer-workflow-manager.js';
+
+export type {
+    CorrectionObserverPayload,
+    CorrectionObserverResult,
+    CorrectionObserverWorkflowSpec,
+} from './correction-observer-types.js';

package/tests/core/correction-cue-learner.test.ts

@@ -0,0 +1,345 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import * as path from 'path';
+import * as os from 'os';
+import {
+  CorrectionCueLearner,
+  loadCorrectionKeywordStore,
+  saveCorrectionKeywordStore,
+  _resetCorrectionCueCache,
+  _resetCorrectionCueLearnerInstance,
+} from '../../src/core/correction-cue-learner.js';
+import {
+  CORRECTION_SEED_KEYWORDS,
+  MAX_CORRECTION_KEYWORDS,
+} from '../../src/core/correction-types.js';
+
+// ── Mock fs (hoisted — vi.mock runs before imports) ──────────────────────────
+
+vi.mock('fs', () => ({
+  existsSync: vi.fn(() => false),
+  readFileSync: vi.fn(() => ''),
+  writeFileSync: vi.fn(),
+  renameSync: vi.fn(),
+  mkdirSync: vi.fn(),
+}));
+
+import * as fs from 'fs';
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function tempDir(): string {
+  return path.join(os.tmpdir(), `correction-cue-test-${Date.now()}-${Math.random()}`);
+}
+
+// ── Test setup: reset module-level cache and singleton between tests ─────────
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  _resetCorrectionCueCache();
+  _resetCorrectionCueLearnerInstance();
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CORR-01: Seed keywords
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe('CORR-01: Seed keywords', () => {
+  it('should create store with 16 seed keywords on first load', () => {
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+    const dir = tempDir();
+    const store = loadCorrectionKeywordStore(dir);
+    expect(store.keywords).toHaveLength(16);
+    expect(store.version).toBe(1);
+  });
+
+  it('should set source=seed and non-empty addedAt for all seed keywords', () => {
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+    const dir = tempDir();
+    const store = loadCorrectionKeywordStore(dir);
+    for (const kw of store.keywords) {
+      expect(kw.source).toBe('seed');
+      expect(kw.addedAt).not.toBe('');
+      expect(kw.addedAt).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
+    }
+  });
+
+  it('should have all 16 exact terms from CORRECTION_SEED_KEYWORDS', () => {
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+    const dir = tempDir();
+    const store = loadCorrectionKeywordStore(dir);
+    const terms = store.keywords.map((k) => k.term);
+    for (const seed of CORRECTION_SEED_KEYWORDS) {
+      expect(terms).toContain(seed.term);
+    }
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CORR-03: Atomic write
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe('CORR-03: Atomic write', () => {
+  it('should write to .tmp file before rename', () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ keywords: CORRECTION_SEED_KEYWORDS.map((k) => ({ ...k, addedAt: '2026-01-01T00:00:00Z' })), version: 1 })
+    );
+
+    const dir = tempDir();
+    const store = {
+      keywords: CORRECTION_SEED_KEYWORDS.map((k) => ({ ...k, addedAt: '2026-01-01T00:00:00Z' })),
+      version: 1,
+      lastOptimizedAt: '2026-01-01T00:00:00Z',
+    };
+    saveCorrectionKeywordStore(dir, store);
+
+    const writeCall = vi.mocked(fs.writeFileSync).mock.calls[0];
+    const tmpPath = writeCall[0] as string;
+    expect(tmpPath).toMatch(/\.tmp$/);
+  });
+
+  it('should rename from tmp path to final path after write', () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ keywords: CORRECTION_SEED_KEYWORDS.map((k) => ({ ...k, addedAt: '2026-01-01T00:00:00Z' })), version: 1 })
+    );
+
+    const dir = tempDir();
+    const store = {
+      keywords: CORRECTION_SEED_KEYWORDS.map((k) => ({ ...k, addedAt: '2026-01-01T00:00:00Z' })),
+      version: 1,
+      lastOptimizedAt: '2026-01-01T00:00:00Z',
+    };
+    saveCorrectionKeywordStore(dir, store);
+
+    const renameCalls = vi.mocked(fs.renameSync).mock.calls;
+    expect(renameCalls).toHaveLength(1);
+    const [from, to] = renameCalls[0];
+    expect(from).toMatch(/\.tmp$/);
+    expect(to).not.toMatch(/\.tmp$/);
+  });
+
+  it('should call mkdirSync with recursive:true before writing', () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ keywords: CORRECTION_SEED_KEYWORDS.map((k) => ({ ...k, addedAt: '2026-01-01T00:00:00Z' })), version: 1 })
+    );
+
+    const dir = tempDir();
+    const store = {
+      keywords: CORRECTION_SEED_KEYWORDS.map((k) => ({ ...k, addedAt: '2026-01-01T00:00:00Z' })),
+      version: 1,
+      lastOptimizedAt: '2026-01-01T00:00:00Z',
+    };
+    saveCorrectionKeywordStore(dir, store);
+
+    expect(vi.mocked(fs.mkdirSync)).toHaveBeenCalledWith(dir, { recursive: true });
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CORR-04: Cache invalidation
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe('CORR-04: Cache invalidation', () => {
+  it('should invalidate cache after save so next load re-reads from disk', () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({
+        keywords: CORRECTION_SEED_KEYWORDS.map((k) => ({ ...k, addedAt: '2026-01-01T00:00:00Z' })),
+        version: 1,
+      })
+    );
+
+    const dir = tempDir();
+    loadCorrectionKeywordStore(dir);
+    expect(vi.mocked(fs.readFileSync)).toHaveBeenCalled();
+
+    const store = loadCorrectionKeywordStore(dir);
+    saveCorrectionKeywordStore(dir, store);
+
+    // After save, cache is null — next load must re-read. Verify by changing
+    // the mock return and confirming the new data is picked up.
+    vi.mocked(fs.readFileSync).mockClear();
+    vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({ keywords: [], version: 1 }));
+
+    const store2 = loadCorrectionKeywordStore(dir);
+    expect(vi.mocked(fs.readFileSync)).toHaveBeenCalled();
+    expect(store2.keywords).toHaveLength(0); // proves re-read happened
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CORR-05: 200-term limit
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe('CORR-05: 200-term limit', () => {
+  it('should throw when adding keyword beyond 200 terms', () => {
+    const keywords = Array.from({ length: 200 }, (_, i) => ({
+      term: `keyword-${i}`,
+      weight: 0.5,
+      source: 'seed' as const,
+      addedAt: '2026-01-01T00:00:00Z',
+    }));
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({ keywords, version: 1 }));
+
+    const dir = tempDir();
+    const learner = new CorrectionCueLearner(dir);
+    expect(learner.getStore().keywords).toHaveLength(200);
+
+    expect(() => learner.add({ term: 'new-keyword', weight: 0.5, source: 'user' })).toThrow(
+      'Correction keyword store limit reached (200 terms)'
+    );
+  });
+
+  it('should allow add when at 199 terms', () => {
+    const keywords = Array.from({ length: 199 }, (_, i) => ({
+      term: `keyword-${i}`,
+      weight: 0.5,
+      source: 'seed' as const,
+      addedAt: '2026-01-01T00:00:00Z',
+    }));
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({ keywords, version: 1 }));
+
+    const dir = tempDir();
+    const learner = new CorrectionCueLearner(dir);
+    expect(learner.getStore().keywords).toHaveLength(199);
+
+    expect(() => learner.add({ term: 'new-keyword', weight: 0.5, source: 'user' })).not.toThrow();
+  });
+
+  it('should not modify store when add fails due to limit', () => {
+    const keywords = Array.from({ length: 200 }, (_, i) => ({
+      term: `keyword-${i}`,
+      weight: 0.5,
+      source: 'seed' as const,
+      addedAt: '2026-01-01T00:00:00Z',
+    }));
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({ keywords, version: 1 }));
+
+    const dir = tempDir();
+    const learner = new CorrectionCueLearner(dir);
+    try {
+      learner.add({ term: 'new-keyword', weight: 0.5, source: 'user' });
+    } catch {
+      // expected
+    }
+
+    expect(learner.getStore().keywords).toHaveLength(200);
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CORR-11: Equivalence to detectCorrectionCue
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe('CORR-11: Equivalence to detectCorrectionCue', () => {
+  beforeEach(() => {
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+  });
+
+  /**
+   * Reference implementation using find() — first match wins (same as detectCorrectionCue).
+   */
+  function detectCorrectionCueLegacy(text: string): string | null {
+    const normalized = text.trim().toLowerCase().replace(/[.,!?;:，。！？；：]/g, '');
+    const cues = CORRECTION_SEED_KEYWORDS.map((k) => k.term);
+    return cues.find((cue) => normalized.includes(cue)) ?? null;
+  }
+
+  /**
+   * Tests using first-match semantics: find() returns the FIRST keyword in the
+   * array whose term appears in the normalized text, not the longest match.
+   *
+   * Order of CORRECTION_SEED_KEYWORDS array (first 8 Chinese):
+   *   '不是这个', '不对', '错了', '搞错了', '理解错了', '你理解错了', '重新来', '再试一次'
+   *
+   * So "我搞错了" → "错了" is found first (index 2) before "搞错了" (index 3).
+   * "你理解错了" → "错了" is found first (index 2) before "理解错了" (index 4) and "你理解错了" (index 5).
+   */
+  it.each([
+    // Chinese cases — note: first match wins
+    ['不是这个', '不是这个'],       // exact match
+    ['你不对啊', '不对'],          // first match is '不对' (index 1)
+    ['错了！', '错了'],            // exact match (index 2)
+    ['我搞错了', '错了'],          // '错了' appears first in array (index 2 < index 3)
+    ['你理解错了', '错了'],         // '错了' appears first in array (index 2 < index 4)
+    ['重新来一遍', '重新来'],       // exact match
+    ['再试一次行不行', '再试一次'],  // exact match
+    // English cases
+    ['you are wrong', 'you are wrong'],  // exact match
+    ['wrong file', 'wrong file'],        // exact match
+    ['not this one', 'not this'],        // exact match
+    ['redo it', 'redo'],                 // exact match (index 11)
+    ['try again', 'try again'],           // exact match (index 12)
+    ['do it again', 'again'],             // 'again' is index 13
+    ['please redo', 'redo'],              // 'redo' found first (index 11 < index 14)
+    ['please try again', 'try again'],    // 'try again' found first (index 12 < index 15)
+  ])('should match "%s" → "%s"', (text, expected) => {
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+    const dir = tempDir();
+    const learner = new CorrectionCueLearner(dir);
+    const result = learner.match(text);
+    expect(result.matched).toBe(true);
+    expect(result.matchedTerms).toContain(expected);
+    expect(result.score).toBeGreaterThan(0);
+  });
+
+  it('should produce same result as legacy detectCorrectionCue for varied inputs', () => {
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+    const dir = tempDir();
+    const learner = new CorrectionCueLearner(dir);
+
+    const cases = [
+      '这个可以，没问题',
+      '不对，应该是这样',
+      '你再试试这个方法',
+      'nothing wrong here',
+      'please be careful',
+      'can you try again?',
+      'I think you are wrong about this',
+    ];
+
+    for (const text of cases) {
+      const legacyResult = detectCorrectionCueLegacy(text);
+      const learnerResult = learner.match(text);
+
+      if (legacyResult !== null) {
+        expect(learnerResult.matched).toBe(true);
+        expect(learnerResult.matchedTerms).toContain(legacyResult);
+        expect(learnerResult.score).toBeGreaterThan(0);
+      } else {
+        expect(learnerResult.matched).toBe(false);
+        expect(learnerResult.matchedTerms).toEqual([]);
+      }
+    }
+  });
+
+  it('should match regardless of surrounding punctuation', () => {
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+    const dir = tempDir();
+    const learner = new CorrectionCueLearner(dir);
+
+    const variations = ['不对', '不对!', '不对?', '。不对', '不对。', '  不对  ', '不对啊'];
+    for (const text of variations) {
+      const result = learner.match(text);
+      expect(result.matched).toBe(true);
+      expect(result.matchedTerms).toContain('不对');
+    }
+  });
+
+  it('should return positive score when matched, 0 when not matched', () => {
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+    const dir = tempDir();
+    const learner = new CorrectionCueLearner(dir);
+    expect(learner.match('不是这个').score).toBeGreaterThan(0);
+    expect(learner.match('这个可以').score).toBe(0);
+  });
+
+  it('should export MAX_CORRECTION_KEYWORDS = 200', () => {
+    expect(MAX_CORRECTION_KEYWORDS).toBe(200);
+  });
+});