principles-disciple 1.28.3 → 1.30.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.28.3",
+  "version": "1.30.0",
   "skills": [
     "./skills"
   ],

package/package.json

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

package/scripts/acceptance-test.mjs

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+
+/**
+ * Nocturnal Pipeline — End-to-End Acceptance Test
+ *
+ * Verifies that all components of the Nocturnal reflection pipeline
+ * work correctly in a real environment (not unit tests).
+ *
+ * Usage:
+ *   node scripts/acceptance-test.mjs --workspace /path/to/workspace
+ *
+ * Output: Pass/Fail for each checkpoint with detailed diagnostics.
+ */
+
+import { existsSync, readFileSync, writeFileSync, rmSync, mkdirSync, readdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { execFileSync } from 'child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ─── Helpers ───
+let passCount = 0;
+let failCount = 0;
+let warnCount = 0;
+
+function assert(condition, testName, detail = '') {
+  if (condition) {
+    console.log(`  ✅ ${testName}`);
+    passCount++;
+  } else {
+    console.log(`  ❌ ${testName}${detail ? ` — ${detail}` : ''}`);
+    failCount++;
+  }
+}
+
+function warn(testName, detail = '') {
+  console.log(`  ⚠️  ${testName}${detail ? ` — ${detail}` : ''}`);
+  warnCount++;
+}
+
+function runSql(dbPath, sql) {
+  return execFileSync('sqlite3', [dbPath, sql], {
+    encoding: 'utf-8',
+    timeout: 5000,
+  }).trim();
+}
+
+// ─── Parse workspace ───
+function parseArgs() {
+  const argv = process.argv.slice(2);
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--workspace' && argv[i + 1]) return argv[++i];
+  }
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf-8' }).trim();
+  } catch {
+    return process.cwd();
+  }
+}
+
+// ─── Main ───
+function main() {
+  const workspaceDir = parseArgs();
+  const stateDir = join(workspaceDir, '.state');
+  const dbPath = join(stateDir, 'trajectory.db');
+
+  if (!existsSync(dbPath)) {
+    console.error('❌ trajectory.db not found. Run seed script first.');
+    process.exit(1);
+  }
+
+  console.log('\n🧪 Nocturnal Pipeline Acceptance Test');
+  console.log('═'.repeat(55));
+  console.log(`Workspace: ${workspaceDir}`);
+  console.log(`Database:  ${dbPath}\n`);
+
+  // ═══════════════════════════════════════════════
+  // SECTION 1: Seed Scenario Data Integrity
+  // ═══════════════════════════════════════════════
+  console.log('── 1. Seed Scenario Data Integrity ──');
+
+  // 1.1 Count seed sessions
+  const sessionCount = parseInt(runSql(dbPath, "SELECT COUNT(*) FROM sessions WHERE session_id LIKE 'seed-%';"));
+  assert(sessionCount === 10, '10 seed sessions exist', `found ${sessionCount}`);
+
+  // 1.2 Count seed pain events
+  const painCount = parseInt(runSql(dbPath, "SELECT COUNT(*) FROM pain_events WHERE session_id LIKE 'seed-%';"));
+  assert(painCount >= 10, 'Pain events exist for seed sessions', `found ${painCount}`);
+
+  // 1.3 Verify signal diversity
+  const sources = runSql(dbPath, "SELECT DISTINCT source FROM pain_events WHERE session_id LIKE 'seed-%';").split('\n');
+  assert(sources.includes('tool_failure'), 'tool_failure signal present');
+  assert(sources.includes('user_empathy'), 'user_empathy signal present');
+
+  // 1.4 Verify pain event scores are in valid range
+  const invalidScores = runSql(dbPath, "SELECT COUNT(*) FROM pain_events WHERE session_id LIKE 'seed-%' AND (score < 0 OR score > 100);");
+  assert(parseInt(invalidScores) === 0, 'All pain scores in 0-100 range', `${invalidScores} invalid`);
+
+  // 1.5 Verify correction cues exist
+  const correctionCount = parseInt(runSql(dbPath, "SELECT COUNT(*) FROM user_turns WHERE session_id LIKE 'seed-%' AND correction_detected = 1;"));
+  assert(correctionCount >= 5, 'Multiple correction cues present', `found ${correctionCount}`);
+
+  // 1.6 Verify tool calls (both success and failure)
+  const failureCalls = parseInt(runSql(dbPath, "SELECT COUNT(*) FROM tool_calls WHERE session_id LIKE 'seed-%' AND outcome = 'failure';"));
+  const successCalls = parseInt(runSql(dbPath, "SELECT COUNT(*) FROM tool_calls WHERE session_id LIKE 'seed-%' AND outcome = 'success';"));
+  assert(failureCalls > 0, 'Failed tool calls in seed data', `found ${failureCalls}`);
+  assert(successCalls > 0, 'Successful tool calls in seed data', `found ${successCalls}`);
+
+  // 1.7 Verify scenario descriptions are unique and meaningful
+  const reasons = runSql(dbPath, "SELECT DISTINCT reason FROM pain_events WHERE session_id LIKE 'seed-%' ORDER BY reason;").split('\n');
+  const uniqueReasons = new Set(reasons);
+  assert(uniqueReasons.size === reasons.length, 'All pain reasons are unique', `${uniqueReasons.size}/${reasons.length} unique`);
+
+  // ═══════════════════════════════════════════════
+  // SECTION 2: write_pain_flag Tool
+  // ═══════════════════════════════════════════════
+  console.log('\n── 2. write_pain_flag Tool ──');
+
+  // 2.1 Test tool registered in source code
+  const indexSource = join(__dirname, '..', 'src', 'index.ts');
+  if (existsSync(indexSource)) {
+    const indexContent = readFileSync(indexSource, 'utf-8');
+    const hasImport = indexContent.includes("write-pain-flag");
+    const hasRegister = indexContent.includes('createWritePainFlagTool');
+    assert(hasImport && hasRegister, 'write_pain_flag registered in index.ts');
+  } else {
+    warn('write_pain_flag tool check', 'index.ts not found');
+  }
+
+  // 2.2 Verify tool source file exists
+  const toolSource = join(__dirname, '..', 'src', 'tools', 'write-pain-flag.ts');
+  assert(existsSync(toolSource), 'write-pain-flag.ts source exists');
+
+  // 2.3 Verify atomic write function
+  const toolContent = readFileSync(toolSource, 'utf-8');
+  assert(toolContent.includes('renameSync'), 'Uses atomic write (renameSync)', 'renameSync not found');
+
+  // 2.4 Verify KV serialization
+  assert(toolContent.includes('serializeKvLines'), 'Uses serializeKvLines for KV format', 'serializeKvLines not found');
+
+  // 2.5 Verify [object Object] protection
+  assert(toolContent.includes('buildPainFlag'), 'Uses buildPainFlag factory', 'buildPainFlag not found');
+
+  // 2.6 Test actual write end-to-end
+  const testFlagPath = join(stateDir, '.pain_flag_acceptance_test');
+  const testStateDir = join(stateDir, '.state_test_' + Date.now());
+  mkdirSync(testStateDir, { recursive: true });
+  try {
+    const testPath = join(testStateDir, '.pain_flag');
+    writeFileSync(testPath + '.tmp', 'source: manual\nscore: 80\ntime: 2026-04-13T00:00:00.000Z\nreason: acceptance test\n', 'utf-8');
+    execFileSync('mv', [testPath + '.tmp', testPath]);
+    const content = readFileSync(testPath, 'utf-8');
+    assert(content.includes('source: manual'), 'Manual pain flag write works');
+    assert(!content.includes('[object Object]'), 'No [object Object] corruption');
+  } finally {
+    rmSync(testStateDir, { recursive: true, force: true });
+  }
+
+  // ═══════════════════════════════════════════════
+  // SECTION 3: Dedup Logic
+  // ═══════════════════════════════════════════════
+  console.log('\n── 3. Dedup Logic (Phase 3c) ──');
+
+  const workerSource = join(__dirname, '..', 'src', 'service', 'evolution-worker.ts');
+  if (existsSync(workerSource)) {
+    const workerContent = readFileSync(workerSource, 'utf-8');
+
+    // 3.1 Helper functions exist
+    assert(workerContent.includes('hasRecentSimilarReflection'), 'hasRecentSimilarReflection helper extracted');
+    assert(workerContent.includes('buildPainSourceKey'), 'buildPainSourceKey helper extracted');
+    assert(workerContent.includes('shouldSkipForDedup'), 'shouldSkipForDedup helper extracted');
+
+    // 3.2 Dedup window is configured
+    assert(workerContent.includes('4 * 60 * 60 * 1000') || workerContent.includes('DEDUP_WINDOW_MS'), '4-hour dedup window configured');
+
+    // 3.3 No-pain-context bypass
+    const bypassCheck = workerContent.includes('!painSourceKey') || workerContent.includes('painSourceKey === null') || 
+                        workerContent.includes('painSourceKey) return false') || workerContent.includes('if (!painSourceKey) return false');
+    assert(bypassCheck, 'no_pain_context bypasses dedup', 'bypass pattern not found');
+
+    // 3.4 Only completed tasks are checked (not failed)
+    assert(workerContent.includes("status !== 'completed'") || workerContent.includes("status === 'completed'"), 'Only completed tasks matched for dedup');
+  } else {
+    fail('Dedup logic check', 'evolution-worker.ts not found');
+  }
+
+  // ═══════════════════════════════════════════════
+  // SECTION 4: Correction Rejected Pain Event
+  // ═══════════════════════════════════════════════
+  console.log('\n── 4. Correction Rejected Pain Signal ──');
+
+  const trajectorySource = join(__dirname, '..', 'src', 'core', 'trajectory.ts');
+  if (existsSync(trajectorySource)) {
+    const trajContent = readFileSync(trajectorySource, 'utf-8');
+
+    // 4.1 Method exists
+    assert(trajContent.includes('recordCorrectionRejectedPain'), 'recordCorrectionRejectedPain method exists');
+
+    // 4.2 Called on rejected status
+    assert(trajContent.includes("status === 'rejected'"), 'Pain event created on rejected status');
+
+    // 4.3 Uses correct source
+    assert(trajContent.includes("'correction_rejected'"), 'Uses correction_rejected source');
+
+    // 4.4 Score is clamped
+    assert(trajContent.includes('Math.max(0') && trajContent.includes('Math.min(100'), 'Score clamped 0-100');
+  } else {
+    fail('Correction rejected check', 'trajectory.ts not found');
+  }
+
+  // ═══════════════════════════════════════════════
+  // SECTION 5: Shell Injection Safety
+  // ═══════════════════════════════════════════════
+  console.log('\n── 5. Shell Injection Safety ──');
+
+  const seedScript = join(__dirname, '..', 'scripts', 'seed-nocturnal-scenarios.mjs');
+  const diagnoseScript = join(__dirname, '..', 'scripts', 'diagnose-nocturnal.mjs');
+
+  if (existsSync(seedScript)) {
+    const seedContent = readFileSync(seedScript, 'utf-8');
+    const execSyncCalls = (seedContent.match(/execSync\s*\(/g) || []).length;
+    const execFileCalls = (seedContent.match(/execFileSync\s*\(/g) || []).length;
+    assert(execSyncCalls === 0 || seedContent.includes("execSync('git") || seedContent.includes('execSync("git'), 
+           'Seed script: no sqlite3 in execSync', 
+           `found ${execSyncCalls} execSync calls`);
+    assert(execFileCalls > 0, 'Seed script: uses execFileSync', `found ${execFileCalls} calls`);
+    
+    // 5.1 Pre-flight check
+    assert(seedContent.includes('ensureSqlite3') || seedContent.includes('sqlite3 --version'), 'Seed script: sqlite3 pre-flight check');
+  }
+
+  if (existsSync(diagnoseScript)) {
+    const diagContent = readFileSync(diagnoseScript, 'utf-8');
+    // 5.2 Diagnose script uses execFileSync for sqlite3
+    const diagExecFileCalls = (diagContent.match(/execFileSync\s*\(\s*['"]sqlite3/g) || []).length;
+    assert(diagExecFileCalls > 0, 'Diagnose script: uses execFileSync for sqlite3', `found ${diagExecFileCalls} calls`);
+
+    // 5.3 No shell-interpolated sqlite3 calls
+    const shellSqliteCalls = (diagContent.match(/execSync\s*\(\s*['"]sqlite3/g) || []).length;
+    assert(shellSqliteCalls === 0, 'Diagnose script: no sqlite3 in execSync', `found ${shellSqliteCalls} unsafe calls`);
+  }
+
+  // ═══════════════════════════════════════════════
+  // SECTION 6: Pending Review Warning Fix
+  // ═══════════════════════════════════════════════
+  console.log('\n── 6. Pending Review Warning Fix ──');
+
+  if (existsSync(diagnoseScript)) {
+    const diagContent = readFileSync(diagnoseScript, 'utf-8');
+    // 6.1 Pending case returns warn object
+    const pendingWarnPattern = /if\s*\(\s*pending\s*>\s*0\s*\)\s*\{[\s\S]*?status:\s*['"]warn['"]/;
+    assert(pendingWarnPattern.test(diagContent), 'Pending review returns {status:"warn"} object');
+  }
+
+  // ═══════════════════════════════════════════════
+  // SECTION 7: Path Resolver Fallback
+  // ═══════════════════════════════════════════════
+  console.log('\n── 7. Path Resolver Fallback ──');
+
+  const pathResolverSource = join(__dirname, '..', 'src', 'core', 'path-resolver.ts');
+  if (existsSync(pathResolverSource)) {
+    const prContent = readFileSync(pathResolverSource, 'utf-8');
+    // 7.1 resolveWorkspaceDirFromApi checks config.workspaceDir
+    assert(prContent.includes('config.workspaceDir') || prContent.includes('cfgWorkspaceDir'), 
+           'resolveWorkspaceDirFromApi checks config.workspaceDir');
+  }
+
+  // ═══════════════════════════════════════════════
+  // SECTION 8: Seed Scenario Quality (Manual Review)
+  // ═══════════════════════════════════════════════
+  console.log('\n── 8. Seed Scenario Quality ──');
+
+  // 8.1 Verify pain score distribution
+  const avgScore = parseFloat(runSql(dbPath, "SELECT ROUND(AVG(score), 1) FROM pain_events WHERE session_id LIKE 'seed-%';"));
+  assert(avgScore > 50 && avgScore < 100, 'Average pain score reasonable (50-100)', `avg=${avgScore}`);
+
+  // 8.2 Verify severity levels are set
+  const nullSeverity = parseInt(runSql(dbPath, "SELECT COUNT(*) FROM pain_events WHERE session_id LIKE 'seed-%' AND severity IS NULL;"));
+  assert(nullSeverity === 0, 'All seed pain events have severity', `${nullSeverity} null`);
+
+  // 8.3 Verify origin is set
+  const nullOrigin = parseInt(runSql(dbPath, "SELECT COUNT(*) FROM pain_events WHERE session_id LIKE 'seed-%' AND origin IS NULL;"));
+  assert(nullOrigin === 0, 'All seed pain events have origin', `${nullOrigin} null`);
+
+  // 8.4 Verify all 10 scenario IDs follow naming convention
+  const seedSessions = runSql(dbPath, "SELECT session_id FROM sessions WHERE session_id LIKE 'seed-%' ORDER BY session_id;").split('\n');
+  const validPattern = /^seed-[a-z-]+-\d{3}$/;
+  const allValid = seedSessions.every(s => validPattern.test(s));
+  assert(allValid, 'All session IDs follow naming convention', `${seedSessions.filter(s => !validPattern.test(s)).length} invalid`);
+
+  // ═══════════════════════════════════════════════
+  // SUMMARY
+  // ═══════════════════════════════════════════════
+  console.log('\n' + '═'.repeat(55));
+  console.log(`  Acceptance Test Summary`);
+  console.log('═'.repeat(55));
+  console.log(`  ✅ Passed:  ${passCount}`);
+  console.log(`  ❌ Failed:  ${failCount}`);
+  console.log(`  ⚠️  Warnings: ${warnCount}`);
+  console.log(`  Total:    ${passCount + failCount + warnCount}`);
+  console.log('═'.repeat(55));
+
+  if (failCount === 0) {
+    console.log('\n🎉 All acceptance tests passed!');
+    process.exit(0);
+  } else {
+    console.log(`\n❌ ${failCount} test(s) failed. Review details above.`);
+    process.exit(1);
+  }
+}
+
+main();

package/scripts/seed-nocturnal-scenarios.mjs

@@ -299,12 +299,11 @@ function main() {
   for (const s of scenarios) {
     const createdAt = daysAgo(s.days);
 
-    // Check if scenario already exists with complete data (pain_events, not just sessions)
-    // This prevents partial data if the script was interrupted mid-insert
+    // Check if scenario already exists (check sessions table first since that's inserted first)
     try {
-      const existing = runSql(dbPath, `SELECT COUNT(*) FROM pain_events WHERE session_id = '${esc(s.sessionId)}';`);
+      const existing = runSql(dbPath, `SELECT COUNT(*) FROM sessions WHERE session_id = '${esc(s.sessionId)}';`);
       if (parseInt(existing) > 0) {
-        console.log(`  ⏭️  Skipping ${s.sessionId} (already exists with ${existing} pain events)`);
+        console.log(`  ⏭️  Skipping ${s.sessionId} (already exists)`);
         skipped++;
         continue;
       }
@@ -336,12 +335,12 @@ VALUES ('${esc(s.sessionId)}', '${esc(tc.toolName)}', '${esc(tc.outcome)}', ${tc
 
     // 4. Pain events
     for (const pe of s.painEvents) {
-      sql.push(`INSERT INTO pain_events (session_id, source, score, reason, severity, origin, confidence, text, created_at)
-VALUES ('${esc(s.sessionId)}', '${esc(pe.source)}', ${pe.score}, '${esc(pe.reason)}', '${esc(pe.severity)}', '${esc(pe.origin)}', ${pe.confidence !== undefined ? pe.confidence : 'NULL'}, ${pe.text ? `'${esc(pe.text)}'` : 'NULL'}, '${createdAt}');`);
+      sql.push(`INSERT INTO pain_events (session_id, source, score, reason, severity, origin, confidence, created_at)
+VALUES ('${esc(s.sessionId)}', '${esc(pe.source)}', ${pe.score}, '${esc(pe.reason)}', '${esc(pe.severity)}', '${esc(pe.origin)}', ${pe.confidence !== undefined ? pe.confidence : 'NULL'}, '${createdAt}');`);
     }
 
     // Execute all SQL in one transaction via stdin piping
-    const fullSql = `BEGIN TRANSACTION;\n${sql.join('\n')}\nCOMMIT;`;
+    const fullSql = `.bail on\nBEGIN TRANSACTION;\n${sql.join('\n')}\nCOMMIT;`;
     try {
       execFileSync('sqlite3', [dbPath], {
         input: fullSql,
@@ -362,11 +361,19 @@ VALUES ('${esc(s.sessionId)}', '${esc(pe.source)}', ${pe.score}, '${esc(pe.reaso
 
   // Print signal diversity report
   try {
-    const painSummary = runSql(dbPath, `.mode column\n.headers on\nSELECT source, COUNT(*) as count, ROUND(AVG(score), 1) as avg_score FROM pain_events WHERE session_id LIKE 'seed-%' GROUP BY source;`);
+    const painSummary = execFileSync('sqlite3', [dbPath], {
+      input: `.mode column\n.headers on\nSELECT source, COUNT(*) as count, ROUND(AVG(score), 1) as avg_score FROM pain_events WHERE session_id LIKE 'seed-%' GROUP BY source;`,
+      encoding: 'utf-8',
+      timeout: 5000,
+    });
     console.log('\n📈 Signal diversity report (seed scenarios only):');
     console.log(painSummary);
 
-    const correctionSummary = runSql(dbPath, `.mode column\n.headers on\nSELECT COUNT(*) as total, SUM(CASE WHEN correction_detected = 1 THEN 1 ELSE 0 END) as with_correction FROM user_turns WHERE session_id LIKE 'seed-%';`);
+    const correctionSummary = execFileSync('sqlite3', [dbPath], {
+      input: `.mode column\n.headers on\nSELECT COUNT(*) as total, SUM(CASE WHEN correction_detected = 1 THEN 1 ELSE 0 END) as with_correction FROM user_turns WHERE session_id LIKE 'seed-%';`,
+      encoding: 'utf-8',
+      timeout: 5000,
+    });
     console.log('📝 Correction scenarios:');
     console.log(correctionSummary);
   } catch (e) {

package/scripts/validate-live-path.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Validate Live Path Script (Phase 18)
+ * Validate Live Path Script (Phase 18) — with Data Flow Monitoring
  *
  * Validates the end-to-end nocturnal workflow path with bootstrapped principles.
  *
@@ -11,6 +11,7 @@
  * - Polls subagent_workflows.db directly for nocturnal workflows
  * - Correlates workflow to queue item via taskId
  * - Verifies state='completed' and explicit resolution (not 'expired')
+ * - Monitors data flow: queue state → workflow state → artifact persistence
  * - Outputs summary and exits 0 on success, non-zero on failure
  *
  * Usage:
@@ -36,6 +37,29 @@ const STATE_DIR = path.join(WORKSPACE_DIR, '.state');
 const QUEUE_PATH = path.join(STATE_DIR, 'EVOLUTION_QUEUE');
 const LEDGER_PATH = path.join(STATE_DIR, 'principle_training_state.json');
 const DB_PATH = path.join(STATE_DIR, 'subagent_workflows.db');
+const PAIN_FLAG_PATH = path.join(STATE_DIR, '.pain_flag');
+const SAMPLES_DIR = path.join(STATE_DIR, 'nocturnal', 'samples');
+
+// ─── Helpers ─────────────────────────────────────────────────────────────
+function timestamp(): string {
+  return new Date().toISOString();
+}
+
+function logStep(step: string, detail: string): void {
+  console.log(`[${timestamp()}] ▸ ${step}: ${detail}`);
+}
+
+function logData(label: string, data: unknown): void {
+  const display = typeof data === 'string' ? data : JSON.stringify(data).slice(0, 300);
+  console.log(`[${timestamp()}]   📦 ${label}: ${display}`);
+}
+
+function safeReadJson(filePath: string): unknown {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch { return null; }
+}
 
 // ─── Types ───────────────────────────────────────────────────────────────
 interface LedgerRule {
@@ -277,11 +301,39 @@ function verifyWorkflowCompletion(taskId: string): {
 async function main() {
   const verbose = process.argv.includes('--verbose');
 
+  console.log('╔══════════════════════════════════════════════════════════╗');
+  console.log('║     Nocturnal Live Path Validation + Data Flow Monitor  ║');
+  console.log('╚══════════════════════════════════════════════════════════╝');
+  logStep('WORKSPACE', WORKSPACE_DIR);
+
+  // 0. Baseline: snapshot current state
+  logStep('BASELINE', 'Capturing current state before validation');
+  const queueBefore = safeReadJson(QUEUE_PATH) as QueueItem[] | null;
+  logData('EVOLUTION_QUEUE (before)', queueBefore?.length ?? 0);
+  if (fs.existsSync(PAIN_FLAG_PATH)) {
+    logData('.pain_flag', 'EXISTS — ' + fs.readFileSync(PAIN_FLAG_PATH, 'utf8').slice(0, 100));
+  } else {
+    logData('.pain_flag', 'not present');
+  }
+  if (fs.existsSync(SAMPLES_DIR)) {
+    const samplesBefore = fs.readdirSync(SAMPLES_DIR).length;
+    logData('nocturnal/samples/', `${samplesBefore} files`);
+  } else {
+    logData('nocturnal/samples/', 'directory not present');
+  }
+  if (fs.existsSync(DB_PATH)) {
+    const wfCount = listNocturnalWorkflows().length;
+    logData('subagent_workflows.db', `${wfCount} nocturnal workflows`);
+  } else {
+    logData('subagent_workflows.db', 'not present');
+  }
+
   // 1. Check bootstrapped rules
   // eslint-disable-next-line @typescript-eslint/init-declarations
   let rules: LedgerRule[];
   try {
     rules = loadBootstrappedRules();
+    logStep('STEP 1', `Found ${rules.length} bootstrapped rule(s)`);
   } catch {
     console.error('FAIL: principle_training_state.json not found. Run Phase 17 bootstrap first: npm run bootstrap-rules');
     process.exit(1);
@@ -293,7 +345,6 @@ async function main() {
   }
 
   if (verbose) {
-    console.log(`Found ${rules.length} bootstrapped rule(s)`);
     for (const rule of rules) {
       console.log(`  - ${rule.id} (principleId=${rule.principleId}, action=${rule.action})`);
     }
@@ -304,33 +355,94 @@ async function main() {
 
   // 3. Build synthetic snapshot for validation
   const snapshot = buildSyntheticSnapshot(taskId);
-  if (verbose) {
-    console.log(`Created synthetic snapshot: sessionId=${snapshot.sessionId}`);
-  }
+  logStep('STEP 2', `Synthetic snapshot: sessionId=${snapshot.sessionId}`);
+  logData('snapshot.recentPain', JSON.stringify(snapshot.recentPain));
 
   // 4. Enqueue task (with lock acquisition)
   try {
     await enqueueSleepReflectionTask(taskId);
-    if (verbose) {
-      console.log(`Enqueued sleep_reflection task: ${taskId}`);
-    }
+    logStep('STEP 3', `Enqueued sleep_reflection task: ${taskId}`);
+
+    // Post-enqueue: verify queue state
+    const queueAfter = safeReadJson(QUEUE_PATH) as QueueItem[] | null;
+    const taskItem = queueAfter?.find(q => q.id === taskId);
+    logData('EVOLUTION_QUEUE (after)', `${queueAfter?.length ?? 0} tasks`);
+    logData(`task[${taskId}]`, taskItem ? JSON.stringify(taskItem) : 'NOT FOUND');
   } catch (error: unknown) {
     console.error('FAIL: Failed to enqueue sleep_reflection task:', String(error));
     process.exit(1);
   }
 
-  // 5. Poll for completion
+  // 5. Poll for completion — with data flow monitoring
   const deadline = Date.now() + POLL_TIMEOUT_MS;
-  if (verbose) {
-    console.log('Polling for workflow completion...');
-  }
+  let pollCount = 0;
+  let lastQueueStatus = 'unknown';
+  let lastWorkflowState = 'none';
+  logStep('STEP 4', `Polling for workflow completion (timeout: ${POLL_TIMEOUT_MS / 1000 / 60}min, interval: ${POLL_INTERVAL_MS / 1000}s)`);
 
   while (Date.now() < deadline) {
+    pollCount++;
     await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL_MS));
 
+    // Capture queue state
+    const queueNow = safeReadJson(QUEUE_PATH) as QueueItem[] | null;
+    const taskNow = queueNow?.find(q => q.id === taskId);
+    const currentQueueStatus = taskNow?.status ?? 'not_in_queue';
+
+    // Capture workflow DB state
+    const workflows = listNocturnalWorkflows();
+    const matchingWf = workflows.find(w => {
+      try {
+        const meta = JSON.parse(w.metadata_json);
+        return meta.taskId === taskId;
+      } catch { return false; }
+    });
+    const currentWorkflowState = matchingWf?.state ?? 'not_in_db';
+
+    // Log state changes
+    if (currentQueueStatus !== lastQueueStatus || currentWorkflowState !== lastWorkflowState) {
+      logStep(`POLL #${pollCount}`, `queue=${currentQueueStatus}, workflow=${currentWorkflowState}`);
+      if (taskNow) logData('queue item', JSON.stringify({ status: taskNow.status, resolution: taskNow.resolution }));
+      if (matchingWf) logData('workflow', JSON.stringify({ state: matchingWf.state, type: matchingWf.workflow_type }));
+      lastQueueStatus = currentQueueStatus;
+      lastWorkflowState = currentWorkflowState;
+    } else if (verbose) {
+      process.stdout.write('.');
+    }
+
+    // Check for completion
     const result = verifyWorkflowCompletion(taskId);
     if (result) {
-      console.log(`RESULT: workflow=${result.workflowId} state=${result.state} resolution=${result.resolution} taskId=${taskId}`);
+      console.log(''); // newline if dots were printed
+      logStep('STEP 5', `Workflow completed!`);
+      logData('RESULT', `workflowId=${result.workflowId} state=${result.state} resolution=${result.resolution}`);
+
+      // Check artifact persistence
+      if (fs.existsSync(SAMPLES_DIR)) {
+        const newSamples = fs.readdirSync(SAMPLES_DIR).filter(f => {
+          const stat = fs.statSync(path.join(SAMPLES_DIR, f));
+          return stat.isFile() && f.endsWith('.json') && (Date.now() - stat.mtimeMs) < 60000; // created in last minute
+        });
+        if (newSamples.length > 0) {
+          logData('new artifacts', newSamples.join(', '));
+          const firstArtifact = safeReadJson(path.join(SAMPLES_DIR, newSamples[0]));
+          if (firstArtifact) logData('artifact content (first)', JSON.stringify(firstArtifact).slice(0, 300));
+        } else {
+          logData('new artifacts', 'none created in last 60s');
+        }
+      }
+
+      // Check pain_flag cleanup
+      if (fs.existsSync(PAIN_FLAG_PATH)) {
+        const flagContent = fs.readFileSync(PAIN_FLAG_PATH, 'utf8');
+        if (flagContent.includes('[object Object]')) {
+          logStep('⚠️ WARNING', 'pain_flag is corrupted ([object Object])');
+        } else {
+          logData('.pain_flag (after)', `still exists, ${flagContent.length} bytes`);
+        }
+      } else {
+        logData('.pain_flag (after)', 'cleaned up (file removed)');
+      }
 
       if (result.resolution === 'MISSING' || result.resolution === 'expired') {
         console.error('FAIL: resolution not explicit');
@@ -340,13 +452,25 @@ async function main() {
       console.log('PASS: Live path validation successful');
       process.exit(0);
     }
+  }
 
-    if (verbose) {
-      process.stdout.write('.');
-    }
+  // Timeout — dump final state for debugging
+  console.log('');
+  logStep('TIMEOUT', `Poll timeout after ${pollCount} polls (${POLL_TIMEOUT_MS / 1000 / 60}min)`);
+  logData('FINAL queue status', lastQueueStatus);
+  logData('FINAL workflow state', lastWorkflowState);
+
+  // Dump full queue for debugging
+  const finalQueue = safeReadJson(QUEUE_PATH);
+  if (finalQueue) logData('FINAL queue dump', JSON.stringify(finalQueue).slice(0, 500));
+
+  // Dump full workflow DB for debugging
+  const finalWorkflows = listNocturnalWorkflows();
+  if (finalWorkflows.length > 0) {
+    logData('FINAL workflows', finalWorkflows.map(w => `${w.workflow_id}: state=${w.state}`).join(', '));
   }
 
-  console.error('FAIL: Poll timeout — no completed nocturnal workflow found for taskId');
+  console.error('FAIL: No completed nocturnal workflow found for taskId');
   process.exit(1);
 }
 

package/src/core/nocturnal-trajectory-extractor.ts

@@ -95,6 +95,14 @@ export interface NocturnalGateBlock {
   createdAt: string;
 }
 
+/**
+ * User correction sample for nocturnal snapshot.
+ * #268: Wire correction_samples into nocturnal pipeline.
+ */
+export interface NocturnalUserCorrection {
+  correctionCue: string | null;
+}
+
 /**
  * A structured nocturnal session snapshot.
  * Contains all information needed for a reflector to generate decision-point samples.
@@ -114,6 +122,8 @@ export interface NocturnalSessionSnapshot {
   toolCalls: NocturnalToolCall[];
   painEvents: NocturnalPainEvent[];
   gateBlocks: NocturnalGateBlock[];
+  /** #268: User corrections from correction_samples table */
+  userCorrections: NocturnalUserCorrection[];
   /**
    * Summary statistics for quick triage.
    * #246: All fields are now number (never null).
@@ -281,6 +291,8 @@ export class NocturnalTrajectoryExtractor {
     const toolCalls = this.trajectory.listToolCallsForSession(sessionId);
     const painEvents = this.trajectory.listPainEventsForSession(sessionId);
     const gateBlocks = this.trajectory.listGateBlocksForSession(sessionId);
+    // #268: Fetch correction samples for this session
+    const correctionSamples = this.trajectory.listCorrectionSamplesForSession(sessionId);
 
     // Map to sanitized structures
     // SECURITY: Only sanitizedText from assistant turns
@@ -346,6 +358,10 @@ export class NocturnalTrajectoryExtractor {
       toolCalls: nocturnalToolCalls,
       painEvents: nocturnalPainEvents,
       gateBlocks: nocturnalGateBlocks,
+      // #268: Map correction samples to nocturnal format
+      userCorrections: correctionSamples.map((cs: { correctionCue: string | null }) => ({
+        correctionCue: cs.correctionCue,
+      })),
       stats: {
         totalAssistantTurns: sanitizedAssistantTurns.length,
         totalToolCalls: nocturnalToolCalls.length,

package/src/core/path-resolver.ts

@@ -420,18 +420,24 @@ export function resolveWorkspaceDirFromApi(
     if (!api) return undefined;
 
     // 1. Official API: api.runtime.agent.resolveAgentWorkspaceDir
-     
+
     const officialAgent = (api.runtime as { agent?: { resolveAgentWorkspaceDir?: (cfg: unknown, id: string) => string } }).agent;
-     
+
     if (officialAgent?.resolveAgentWorkspaceDir) {
         try {
             return officialAgent.resolveAgentWorkspaceDir(api.config, agentId ?? 'main');
         } catch {
-            // Fall through to PathResolver
+            // Fall through to config check
         }
     }
 
-    // 2. Fallback: PathResolver (PD_WORKSPACE_DIR env, config file, default)
+    // 2. Direct config workspaceDir (for tests and programmatic usage)
+    const cfgWorkspaceDir = (api.config as { workspaceDir?: string })?.workspaceDir;
+    if (cfgWorkspaceDir && cfgWorkspaceDir.trim()) {
+        return cfgWorkspaceDir.trim();
+    }
+
+    // 3. Fallback: PathResolver (PD_WORKSPACE_DIR env, config file, default)
     try {
         const pr = new PathResolver();
         return pr.getWorkspaceDir();

package/src/core/trajectory.ts

@@ -935,6 +935,25 @@ export class TrajectoryDatabase {
     }));
   }
 
+  /**
+   * List correction samples for a specific session.
+   * Returns minimal fields for nocturnal use — correction cue only.
+   * #268: Wire correction_samples into nocturnal pipeline.
+   */
+  listCorrectionSamplesForSession(sessionId: string): { correctionCue: string | null }[] {
+    const rows = this.db.prepare(`
+      SELECT cs.sample_id, ut.correction_cue
+      FROM correction_samples cs
+      LEFT JOIN user_turns ut ON ut.id = cs.user_correction_turn_id
+      WHERE cs.session_id = ?
+      ORDER BY cs.created_at DESC
+    `).all(sessionId) as Record<string, unknown>[];
+
+    return rows.map((row) => ({
+      correctionCue: row.correction_cue ? String(row.correction_cue) : null,
+    }));
+  }
+
   reviewCorrectionSample(sampleId: string, status: Exclude<CorrectionSampleReviewStatus, 'pending'>, note?: string): CorrectionSampleRecord {
     const updatedAt = nowIso();
     const updated = this.withWrite(() => {

package/src/index.ts

@@ -17,6 +17,7 @@ import type {
   PluginHookSubagentContext,
 } from './openclaw-sdk.js';
 import * as crypto from 'crypto';
+import * as path from 'path';
 import type { WorkerProfile } from './core/model-deployment-registry.js';
 import { classifyTask } from './core/local-worker-routing.js';
 import { completeShadowObservation, recordShadowRouting } from './core/shadow-observation-registry.js';
@@ -66,6 +67,8 @@ import { extractAgentIdFromSessionKey } from './utils/session-key.js';
 
 // Track initialization to avoid repeated calls
 let workspaceInitialized = false;
+// Track started evolution workers — one per workspace
+const startedWorkspaces = new Set<string>();
 
 /**
  * Resolve workspaceDir for slash commands.
@@ -171,6 +174,23 @@ const plugin = {
             SystemLogger.log(workspaceDir, 'SYSTEM_BOOT', `Principles Disciple online. Language: ${language}`);
             workspaceInitialized = true;
           }
+
+          // ── Start EvolutionWorker for THIS workspace ──
+          // Each agent has its own heartbeat task. When before_prompt_build fires,
+          // it fires for the current agent's workspaceDir. Start one EvolutionWorker
+          // per workspace so each agent's pain signals are processed independently.
+          if (!startedWorkspaces.has(workspaceDir)) {
+            startedWorkspaces.add(workspaceDir);
+            EvolutionWorkerService.api = api;
+            EvolutionWorkerService.start({
+              config: api.config,
+              workspaceDir,
+              stateDir: path.join(workspaceDir, '.state'),
+              logger: api.logger,
+            });
+            api.logger.info(`[PD] EvolutionWorker started for workspace: ${workspaceDir}`);
+          }
+
           const result = await handleBeforePromptBuild(event, { ...ctx, api, workspaceDir });
           
           // Record success

package/src/service/evolution-worker.ts

@@ -17,6 +17,7 @@ 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 { checkWorkspaceIdle, checkCooldown } from './nocturnal-runtime.js';
+import { loadNocturnalConfig } from './nocturnal-config.js';
 import { WorkflowStore } from './subagent-workflow/workflow-store.js';
 import type { WorkflowRow } from './subagent-workflow/types.js';
 import { EmpathyObserverWorkflowManager } from './subagent-workflow/empathy-observer-workflow-manager.js';
@@ -407,6 +408,8 @@ function buildFallbackNocturnalSnapshot(
         toolCalls: [],
         painEvents: fallbackPainEvents,
         gateBlocks: [],
+        // #268: Empty corrections in fallback path (no trajectory data available)
+        userCorrections: [],
         stats: {
             totalAssistantTurns: realStats?.totalAssistantTurns ?? 0,
             totalToolCalls: realStats?.totalToolCalls ?? 0,
@@ -485,14 +488,13 @@ function findRecentDuplicateTask(
     now: number,
     reason?: string
 ): EvolutionQueueItem | undefined {
-     
     // eslint-disable-next-line @typescript-eslint/no-use-before-define
     const key = normalizePainDedupKey(source, preview, reason);
     return queue.find((task) => {
         if (task.status === 'completed') return false;
+        // eslint-disable-next-line @typescript-eslint/no-use-before-define
         const taskTime = new Date(task.enqueued_at || task.timestamp).getTime();
         if (!Number.isFinite(taskTime) || (now - taskTime) > PAIN_QUEUE_DEDUP_WINDOW_MS) return false;
-         
         // eslint-disable-next-line @typescript-eslint/no-use-before-define
         return normalizePainDedupKey(task.source, task.trigger_text_preview || '', task.reason) === key;
     });
@@ -547,6 +549,7 @@ function normalizePainDedupKey(source: string, preview: string, reason?: string)
 }
 
  
+ 
 // eslint-disable-next-line @typescript-eslint/max-params
 export function hasRecentDuplicateTask(queue: EvolutionQueueItem[], source: string, preview: string, now: number, reason?: string): boolean {
     return !!findRecentDuplicateTask(queue, source, preview, now, reason);
@@ -675,7 +678,7 @@ function shouldSkipForDedup(
  * Load and migrate the evolution queue. Returns empty array if file doesn't exist.
  */
 function loadEvolutionQueue(queuePath: string): EvolutionQueueItem[] {
-    // eslint-disable-next-line no-useless-assignment
+    // eslint-disable-next-line @typescript-eslint/init-declarations, no-useless-assignment
     let rawQueue: RawQueueItem[] = [];
     try {
         rawQueue = JSON.parse(fs.readFileSync(queuePath, 'utf8'));
@@ -689,6 +692,7 @@ function loadEvolutionQueue(queuePath: string): EvolutionQueueItem[] {
 /**
  * Build and persist a new sleep_reflection task.
  */
+ 
 // eslint-disable-next-line @typescript-eslint/max-params
 function enqueueNewSleepReflectionTask(
     queue: EvolutionQueueItem[],
@@ -1608,10 +1612,8 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
 
                     // eslint-disable-next-line @typescript-eslint/init-declarations
                     let workflowId: string | undefined;
-                     
                     // eslint-disable-next-line @typescript-eslint/init-declarations
                     let nocturnalManager: NocturnalWorkflowManager;
-                     
                     // eslint-disable-next-line @typescript-eslint/init-declarations
                     let snapshotData: NocturnalSessionSnapshot | undefined;
 
@@ -2014,6 +2016,7 @@ export async function registerEvolutionTaskSession(
 export interface ExtendedEvolutionWorkerService {
     id: string;
     api: OpenClawPluginApi | null;
+    _startedWorkspaces: Set<string>;
     start: (ctx: OpenClawPluginServiceContext) => void | Promise<void>;
     stop?: (ctx: OpenClawPluginServiceContext) => void | Promise<void>;
 }
@@ -2085,17 +2088,27 @@ async function processEvolutionQueueWithResult(
 export const EvolutionWorkerService: ExtendedEvolutionWorkerService = {
     id: 'principles-evolution-worker',
     api: null,
+    _startedWorkspaces: new Set<string>(),
 
     start(ctx: OpenClawPluginServiceContext): void {
+        const workspaceDir = ctx?.workspaceDir;
         const logger = ctx?.logger || console;
         const {api} = this;
-        const workspaceDir = ctx?.workspaceDir;
 
         if (!workspaceDir) {
             if (logger) logger.warn('[PD:EvolutionWorker] workspaceDir not found in service config. Evolution cycle disabled.');
             return;
         }
 
+        // Guard: prevent duplicate starts for the SAME workspace
+        const started = EvolutionWorkerService._startedWorkspaces;
+        if (started.has(workspaceDir)) {
+            ctx?.logger?.info?.(`[PD:EvolutionWorker] Already started for ${workspaceDir}, skipping`);
+            return;
+        }
+
+        started.add(workspaceDir);
+
         const wctx = WorkspaceContext.fromHookContext({ workspaceDir, ...ctx.config });
         if (logger) logger.info(`[PD:EvolutionWorker] Starting with workspaceDir=${wctx.workspaceDir}, stateDir=${wctx.stateDir}`);
 
@@ -2109,12 +2122,16 @@ export const EvolutionWorkerService: ExtendedEvolutionWorkerService = {
         const initialDelay = 5000;
         const interval = config.get('intervals.worker_poll_ms') || (15 * 60 * 1000);
 
+        // Periodic trigger tracking
+        let heartbeatCounter = 0;
+
         async function runCycle(): Promise<void> {
             const cycleStart = Date.now();
+            heartbeatCounter++;
 
             // ──── DEBUG: Verify subagent availability in heartbeat context ────
             const hbSubagent = api?.runtime?.subagent;
-            logger?.info?.(`[PD:DEBUG:SubagentCheck:Heartbeat] api_exists=${!!api}, subagent_exists=${!!hbSubagent}, subagent.run_exists=${!!hbSubagent?.run}`);
+            logger?.info?.(`[PD:DEBUG:SubagentCheck:Heartbeat] api_exists=${!!api}, subagent_exists=${!!hbSubagent}, subagent.run_exists=${!!hbSubagent?.run}, heartbeatCounter=${heartbeatCounter}`);
             if (hbSubagent?.run) {
                 logger?.info?.('[PD:DEBUG:SubagentCheck:Heartbeat] run entrypoint is callable');
             }
@@ -2135,18 +2152,45 @@ export const EvolutionWorkerService: ExtendedEvolutionWorkerService = {
             };
 
             try {
+                // Load config on each cycle (supports runtime updates)
+                const sleepConfig = loadNocturnalConfig(wctx.stateDir);
+
                 const idleResult = checkWorkspaceIdle(wctx.workspaceDir, {});
-                logger?.info?.(`[PD:EvolutionWorker] HEARTBEAT cycle=${new Date().toISOString()} idle=${idleResult.isIdle} idleForMs=${idleResult.idleForMs} userActiveSessions=${idleResult.userActiveSessions} abandonedSessions=${idleResult.abandonedSessionIds.length} lastActivityEpoch=${idleResult.mostRecentActivityAt}`);
-                if (idleResult.isIdle) {
-                    logger?.debug?.(`[PD:EvolutionWorker] Workspace idle (${idleResult.idleForMs}ms since last activity)`);
-                    const cooldown = checkCooldown(wctx.stateDir);
+                logger?.info?.(`[PD:EvolutionWorker] HEARTBEAT cycle=${new Date().toISOString()} idle=${idleResult.isIdle} idleForMs=${idleResult.idleForMs} userActiveSessions=${idleResult.userActiveSessions} abandonedSessions=${idleResult.abandonedSessionIds.length} lastActivityEpoch=${idleResult.mostRecentActivityAt} triggerMode=${sleepConfig.trigger_mode}`);
+
+                let shouldTrySleepReflection = false;
+
+                // Path 1: Idle-based trigger (default mode)
+                if (idleResult.isIdle && sleepConfig.trigger_mode === 'idle') {
+                    logger?.info?.(`[PD:EvolutionWorker] Workspace idle (${idleResult.idleForMs}ms since last activity)`);
+                    shouldTrySleepReflection = true;
+                }
+
+                // Path 2: Periodic trigger (bypasses idle requirement — for debugging)
+                if (!idleResult.isIdle && sleepConfig.trigger_mode === 'periodic') {
+                    if (heartbeatCounter >= sleepConfig.period_heartbeats) {
+                        logger?.info?.(`[PD:EvolutionWorker] Periodic trigger: heartbeatCounter=${heartbeatCounter} >= period_heartbeats=${sleepConfig.period_heartbeats}`);
+                        shouldTrySleepReflection = true;
+                        heartbeatCounter = 0; // Reset counter
+                    } else {
+                        logger?.info?.(`[PD:EvolutionWorker] Periodic: ${heartbeatCounter}/${sleepConfig.period_heartbeats} heartbeats — waiting`);
+                    }
+                }
+
+                if (shouldTrySleepReflection) {
+                    const cooldown = checkCooldown(wctx.stateDir, undefined, {
+                        maxRunsPerWindow: sleepConfig.max_runs_per_day,
+                        quotaWindowMs: 24 * 60 * 60 * 1000,
+                    });
+                    logger?.info?.(`[PD:EvolutionWorker] Cooldown check: globalCooldownActive=${cooldown.globalCooldownActive} quotaExhausted=${cooldown.quotaExhausted} runsRemaining=${cooldown.runsRemaining}`);
                     if (!cooldown.globalCooldownActive && !cooldown.quotaExhausted) {
+                        logger?.info?.('[PD:EvolutionWorker] Attempting to enqueue sleep_reflection task...');
                         enqueueSleepReflectionTask(wctx, logger).catch((err) => {
                             logger?.error?.(`[PD:EvolutionWorker] Failed to enqueue sleep_reflection task: ${String(err)}`);
                         });
+                    } else {
+                        logger?.info?.(`[PD:EvolutionWorker] Skipping sleep_reflection: globalCooldown=${cooldown.globalCooldownActive} quotaExhausted=${cooldown.quotaExhausted}`);
                     }
-                } else {
-                    logger?.debug?.(`[PD:EvolutionWorker] Workspace active (last activity ${idleResult.idleForMs}ms ago)`);
                 }
 
                 const painCheckResult = await checkPainFlag(wctx, logger);

package/src/service/nocturnal-config.ts

@@ -0,0 +1,72 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface SleepReflectionConfig {
+    /** Trigger mode: "idle" (default) or "periodic" */
+    trigger_mode: 'idle' | 'periodic';
+    /** In periodic mode, trigger every N heartbeat cycles */
+    period_heartbeats: number;
+    /** Minimum time between runs (ms) */
+    cooldown_ms: number;
+    /** Maximum runs per 24-hour window */
+    max_runs_per_day: number;
+    /** Whether sleep_reflection is enabled */
+    enabled: boolean;
+}
+
+export interface NocturnalConfig {
+    sleep_reflection?: Partial<SleepReflectionConfig>;
+}
+
+const DEFAULT_SLEEP_REFLECTION: SleepReflectionConfig = {
+    trigger_mode: 'idle',
+    period_heartbeats: 4,       // ~1 hour at 15-min heartbeat interval
+    cooldown_ms: 30 * 60 * 1000, // 30 minutes
+    max_runs_per_day: 3,
+    enabled: true,
+};
+
+const CONFIG_FILENAME = 'nocturnal-config.json';
+
+/**
+ * Resolve the nocturnal config file path.
+ */
+function resolveConfigPath(stateDir: string): string {
+    return path.join(stateDir, CONFIG_FILENAME);
+}
+
+/**
+ * Load nocturnal config from .state/nocturnal-config.json.
+ * Returns default config if file doesn't exist or is malformed.
+ */
+export function loadNocturnalConfig(stateDir: string): SleepReflectionConfig {
+    const configPath = resolveConfigPath(stateDir);
+    let fileConfig: NocturnalConfig = {};
+
+    if (fs.existsSync(configPath)) {
+        try {
+            const raw = fs.readFileSync(configPath, 'utf8');
+            fileConfig = JSON.parse(raw);
+        } catch {
+            // Malformed config — continue with defaults
+        }
+    }
+
+    const fileSleep = fileConfig.sleep_reflection || {};
+
+    return {
+        trigger_mode: fileSleep.trigger_mode === 'periodic' ? 'periodic' : DEFAULT_SLEEP_REFLECTION.trigger_mode,
+        period_heartbeats: typeof fileSleep.period_heartbeats === 'number' && fileSleep.period_heartbeats > 0
+            ? fileSleep.period_heartbeats
+            : DEFAULT_SLEEP_REFLECTION.period_heartbeats,
+        cooldown_ms: typeof fileSleep.cooldown_ms === 'number' && fileSleep.cooldown_ms >= 0
+            ? fileSleep.cooldown_ms
+            : DEFAULT_SLEEP_REFLECTION.cooldown_ms,
+        max_runs_per_day: typeof fileSleep.max_runs_per_day === 'number' && fileSleep.max_runs_per_day > 0
+            ? fileSleep.max_runs_per_day
+            : DEFAULT_SLEEP_REFLECTION.max_runs_per_day,
+        enabled: typeof fileSleep.enabled === 'boolean'
+            ? fileSleep.enabled
+            : DEFAULT_SLEEP_REFLECTION.enabled,
+    };
+}

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

@@ -474,7 +474,10 @@ export class NocturnalTargetSelector {
             toolName: gb.toolName,
             reason: gb.reason,
           })),
-          userCorrections: [],
+          // #268: Use actual correction samples from snapshot instead of empty array
+          userCorrections: snapshot.userCorrections.map((uc) => ({
+            correctionCue: uc.correctionCue ?? undefined,
+          })),
           planApprovals: [],
         });
         hasViolation = violationResult.violated;

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

@@ -40,6 +40,11 @@ describe('Phase 4a: Correction rejected integration', () => {
       correctionDetected: true, correctionCue: '错了',
       referencesAssistantTurnId: atId, createdAt: new Date().toISOString(),
     });
+    // Tool call triggers maybeCreateCorrectionSample on success
+    trajectory.recordToolCall({
+      sessionId: 'corr-session', toolName: 'read', outcome: 'success',
+      createdAt: new Date().toISOString(),
+    });
 
     // Verify sample was created
     const samples = trajectory.listCorrectionSamples('pending');
@@ -68,6 +73,11 @@ describe('Phase 4a: Correction rejected integration', () => {
       correctionDetected: true, correctionCue: '改进',
       referencesAssistantTurnId: atId, createdAt: new Date().toISOString(),
     });
+    // Tool call triggers maybeCreateCorrectionSample on success
+    trajectory.recordToolCall({
+      sessionId: 'approved-session', toolName: 'read', outcome: 'success',
+      createdAt: new Date().toISOString(),
+    });
 
     const samples = trajectory.listCorrectionSamples('pending');
     expect(samples.length).toBe(1);

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

@@ -122,15 +122,28 @@ describe('write_pain_flag tool', () => {
     expect(api._logs.some((l: any) => l.level === 'warn')).toBe(true);
   });
 
-  it('returns clear error when workspace cannot be resolved', async () => {
-    const api = createMockApi('') as any;
-    const tool = createWritePainFlagTool(api);
+  it('falls back to PathResolver when config.workspaceDir is not set', async () => {
+    // Even without explicit workspaceDir, the tool should succeed
+    // by falling back to PathResolver (which finds default workspace)
+    const logs: { level: string; message: string }[] = [];
+    const api = {
+      config: {},
+      logger: {
+        info: (m: string) => logs.push({ level: 'info', message: m }),
+        warn: (m: string) => logs.push({ level: 'warn', message: m }),
+        error: (m: string) => logs.push({ level: 'error', message: m }),
+        debug: (m: string) => logs.push({ level: 'debug', message: m }),
+      },
+      runtime: { subagent: null, agent: null },
+      _logs: logs,
+    } as any;
 
-    const result = await tool.execute('test-3', { reason: 'Test error' });
+    const tool = createWritePainFlagTool(api);
+    const result = await tool.execute('test-3', { reason: 'Test fallback' });
 
-    expect(result.content[0].text).toContain('❌');
-    expect(result.content[0].text).toContain('workspace');
-    expect(api._logs.some((l: any) => l.level === 'error')).toBe(true);
+    // Should succeed via PathResolver fallback
+    expect(result.content[0].text).toContain('✅');
+    expect(result.content[0].text).toContain('Test fallback');
   });
 
   // ─────────────────────────────────────────────────────────
@@ -209,16 +222,19 @@ describe('write_pain_flag tool', () => {
     expect(text).toContain('heartbeat');
   });
 
-  it('provides clear failure feedback with error message', async () => {
+  it('handles missing state directory by creating it automatically', async () => {
     const api = createMockApi(workspaceDir) as any;
-    // Simulate workspace resolution failure by removing the config
-    (api as any).config = {};
+    // Remove .state directory to test auto-creation
+    if (fs.existsSync(stateDir)) {
+      fs.rmSync(stateDir, { recursive: true, force: true });
+    }
 
     const tool = createWritePainFlagTool(api);
-    const result = await tool.execute('test-7', { reason: 'Should fail' });
+    const result = await tool.execute('test-auto', { reason: 'Auto-create state dir' });
 
-    expect(result.content[0].text).toContain('❌');
-    expect(result.content[0].text).toContain('workspace');
+    expect(result.content[0].text).toContain('✅');
+    const painFlagPath = path.join(stateDir, '.pain_flag');
+    expect(fs.existsSync(painFlagPath)).toBe(true);
   });
 
   // ─────────────────────────────────────────────────────────