principles-disciple 1.27.0 → 1.28.1

package/scripts/validate-live-path.ts

@@ -20,6 +20,7 @@
  *   WORKSPACE_DIR - Optional workspace directory (defaults to process.cwd())
  */
 
+import * as Database from 'better-sqlite3';
 import * as fs from 'fs';
 import * as path from 'path';
 
@@ -33,7 +34,6 @@ const LOCK_STALE_MS = 30_000;
 const WORKSPACE_DIR = process.env.WORKSPACE_DIR || process.cwd();
 const STATE_DIR = path.join(WORKSPACE_DIR, '.state');
 const QUEUE_PATH = path.join(STATE_DIR, 'EVOLUTION_QUEUE');
-const QUEUE_LOCK_PATH = QUEUE_PATH + LOCK_SUFFIX;
 const LEDGER_PATH = path.join(STATE_DIR, 'principle_training_state.json');
 const DB_PATH = path.join(STATE_DIR, 'subagent_workflows.db');
 
@@ -80,17 +80,14 @@ async function acquireLockAsync(filePath: string, options: {
   baseRetryDelayMs?: number;
   lockStaleMs?: number;
 } = {}): Promise<LockContext> {
-  const opts = {
-    lockSuffix: LOCK_SUFFIX,
-    maxRetries: LOCK_MAX_RETRIES,
-    baseRetryDelayMs: LOCK_RETRY_DELAY_MS,
-    lockStaleMs: LOCK_STALE_MS,
-    ...options,
-  };
+  const lockSuffix = options.lockSuffix ?? LOCK_SUFFIX;
+  const maxRetries = options.maxRetries ?? LOCK_MAX_RETRIES;
+  const baseRetryDelayMs = options.baseRetryDelayMs ?? LOCK_RETRY_DELAY_MS;
+  const lockStaleMs = options.lockStaleMs ?? LOCK_STALE_MS;
   const { pid } = process;
-  const lockPath = filePath + opts.lockSuffix;
+  const lockPath = filePath + lockSuffix;
 
-  for (let attempt = 0; attempt < opts.maxRetries!; attempt++) {
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
     try {
       // Check if lock file exists and is stale
       if (fs.existsSync(lockPath)) {
@@ -100,11 +97,11 @@ async function acquireLockAsync(filePath: string, options: {
         const lockAge = Date.now() - lockStats.mtimeMs;
 
         // Clean up stale lock
-        if (lockAge > opts.lockStaleMs!) {
+        if (lockAge > lockStaleMs) {
           fs.unlinkSync(lockPath);
         } else if (lockPid !== pid) {
           // Lock held by another process
-          await new Promise(resolve => setTimeout(resolve, opts.baseRetryDelayMs!));
+          await new Promise(resolve => setTimeout(resolve, baseRetryDelayMs));
           continue;
         }
       }
@@ -125,17 +122,20 @@ async function acquireLockAsync(filePath: string, options: {
         },
       };
     } catch (error: unknown) {
-      if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
-        if (attempt < opts.maxRetries! - 1) {
-          await new Promise(resolve => setTimeout(resolve, opts.baseRetryDelayMs!));
+      const err = error as { code?: string };
+      if (err.code === 'EEXIST') {
+        if (attempt < maxRetries - 1) {
+          await new Promise(resolve => setTimeout(resolve, baseRetryDelayMs));
           continue;
         }
       }
-      throw new Error(`Failed to acquire lock for ${filePath}: ${String(error)}`);
+      const lockError = new Error(`Failed to acquire lock for ${filePath}: ${String(error)}`);
+      lockError.cause = error;
+      throw lockError;
     }
   }
 
-  throw new Error(`Failed to acquire lock for ${filePath} after ${opts.maxRetries} attempts`);
+  throw new Error(`Failed to acquire lock for ${filePath} after ${maxRetries} attempts`);
 }
 
 function releaseLock(ctx: LockContext): void {
@@ -225,7 +225,6 @@ function listNocturnalWorkflows(): WorkflowRow[] {
     return [];
   }
 
-  const Database = require('better-sqlite3');
   const db = new Database(DB_PATH, { readonly: true });
   const rows = db.prepare(`
     SELECT workflow_id, workflow_type, state, metadata_json, created_at
@@ -279,6 +278,7 @@ async function main() {
   const verbose = process.argv.includes('--verbose');
 
   // 1. Check bootstrapped rules
+  // eslint-disable-next-line @typescript-eslint/init-declarations
   let rules: LedgerRule[];
   try {
     rules = loadBootstrappedRules();

package/src/commands/nocturnal-train.ts

@@ -30,6 +30,7 @@ import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.
 import {
   type TrainerBackendKind,
   type HardwareTier,
+  type TrainingExperimentResult,
 } from '../core/external-training-contract.js';
 import {
   TrainingProgram,
@@ -270,14 +271,11 @@ Hardware tiers:
       // This closes the gap in the create-experiment -> trainer -> import-result chain.
       // NOTE: This blocks until training completes (could be minutes).
       if (runNow) {
-         
-        const {spec} = createResult;
         const baseDir = TRAINER_SCRIPTS_DIR;
         const scriptPath = path.join(baseDir, 'main.py');
         const specPath = path.join(baseDir, `experiment-${spec.experimentId}.json`);
-         
-        const {outputDir} = spec;
-        const resultFilePath = path.join(outputDir, `result-${spec.experimentId}.json`);
+
+        const resultFilePath = path.join(spec.outputDir, `result-${spec.experimentId}.json`);
 
         // Write spec file
         const specDir = path.dirname(specPath);
@@ -287,7 +285,7 @@ Hardware tiers:
         fs.writeFileSync(specPath, JSON.stringify(spec, null, 2), 'utf-8');
 
          
-        let trainerResult!: import('../core/external-training-contract.js').TrainingExperimentResult;
+        let trainerResult!: TrainingExperimentResult;
 
         try {
           if (spec.backend === 'dry-run') {

package/src/commands/pain.ts

@@ -127,20 +127,17 @@ export function handlePainCommand(ctx: PluginCommandContext): PluginCommandResul
     
     // Determine Mental Mode (aligned with prompt.ts logic)
      
-    let mentalMode = '';
-    if (isZh) {
-        if (gfi >= 70) mentalMode = '🚑 救赎模式 (HUMBLE_RECOVERY)';
-        else if (gfi >= 40) mentalMode = '🤝 安抚模式 (CONCILIATORY)';
-        else mentalMode = '⚡ 高效模式 (EFFICIENT)';
-    } else {
-        if (gfi >= 70) mentalMode = '🚑 HUMBLE_RECOVERY';
-        else if (gfi >= 40) mentalMode = '🤝 CONCILIATORY';
-        else mentalMode = '⚡ EFFICIENT';
-    }
+    const mentalMode = isZh
+        ? gfi >= 70 ? '🚑 救赎模式 (HUMBLE_RECOVERY)'
+        : gfi >= 40 ? '🤝 安抚模式 (CONCILIATORY)'
+        : '⚡ 高效模式 (EFFICIENT)'
+        : gfi >= 70 ? '🚑 HUMBLE_RECOVERY'
+        : gfi >= 40 ? '🤝 CONCILIATORY'
+        : '⚡ EFFICIENT';
     
     // Determine health status based on GFI
      
-    let healthLabel = 'Healthy';
+    let healthLabel: string;
     let suggestionText = '';
 
     if (isZh) {

package/src/commands/pd-reflect.ts

@@ -5,7 +5,7 @@
  * This command must operate on an explicitly resolved active workspace.
  */
 
-import { PluginCommandDefinition, PluginCommandContext, PluginCommandResult, OpenClawPluginApi } from '../openclaw-sdk.js';
+import type { PluginCommandDefinition, PluginCommandContext, PluginCommandResult, OpenClawPluginApi } from '../openclaw-sdk.js';
 import { acquireQueueLock, EVOLUTION_QUEUE_LOCK_SUFFIX } from '../service/evolution-worker.js';
 import * as fs from 'fs';
 import * as path from 'path';

package/src/core/bootstrap-rules.ts

@@ -30,7 +30,7 @@ export interface BootstrapResult {
  * @returns Array of principle IDs sorted by observedViolationCount (descending)
  * @throws Error if no deterministic principles found
  */
-export function selectPrinciplesForBootstrap(stateDir: string, limit: number = 3): string[] {
+export function selectPrinciplesForBootstrap(stateDir: string, limit = 3): string[] {
   // Load training store to get evaluability and violation data
   const store = loadStore(stateDir);
 
@@ -76,7 +76,7 @@ export function selectPrinciplesForBootstrap(stateDir: string, limit: number = 3
  * @returns Array of results indicating created or skipped status
  * @throws Error if no deterministic principles found
  */
-export function bootstrapRules(stateDir: string, limit: number = 3): BootstrapResult[] {
+export function bootstrapRules(stateDir: string, limit = 3): BootstrapResult[] {
   // Select principles for bootstrap
   const selectedPrincipleIds = selectPrinciplesForBootstrap(stateDir, limit);
 
@@ -107,7 +107,7 @@ export function bootstrapRules(stateDir: string, limit: number = 3): BootstrapRe
 
     // Create stub rule
     const now = new Date().toISOString();
-    const rule = createRule(stateDir, {
+    createRule(stateDir, {
       id: ruleId,
       version: 1,
       name: `Stub bootstrap rule for ${principleId}`,

package/src/core/merge-gate-audit.ts

@@ -364,7 +364,7 @@ function validateSingleReplayReport(reportPath: string): ReplayValidationCategor
     return 'missing_evidence_summary';
   }
 
-  const evidenceSummary = (parsed as ReplayReport).evidenceSummary;
+  const evidenceSummary = parsed.evidenceSummary;
   if (parsed.overallDecision === 'pass' && evidenceSummary.totalSamples === 0) {
     return 'unsupported_pass';
   }

package/src/core/nocturnal-candidate-scoring.ts

@@ -116,6 +116,23 @@ export const DEFAULT_SCORING_WEIGHTS: ScoringWeights = {
   confidence: 0.15,
 };
 
+/**
+ * Result of diversity validation on Dreamer candidates.
+ * Soft enforcement: result is informational, never gates the pipeline.
+ */
+export interface DiversityValidationResult {
+  /** Whether candidates passed diversity checks */
+  diversityCheckPassed: boolean;
+  /** Whether at least 2 distinct risk levels were present */
+  riskLevelDiversity: boolean;
+  /** Whether no candidate pair exceeded keyword overlap threshold */
+  keywordOverlapPassed: boolean;
+  /** Highest pairwise keyword overlap score (for telemetry) */
+  maxOverlapScore: number;
+  /** Human-readable summary of check results */
+  details: string;
+}
+
 // ---------------------------------------------------------------------------
 // Scoring Logic
 // ---------------------------------------------------------------------------
@@ -232,6 +249,120 @@ export function checkThresholds(
   return [failedThresholds.length === 0, failedThresholds];
 }
 
+/**
+ * Validate that Dreamer candidates are strategically diverse.
+ *
+ * DIVER-03: Checks risk level diversity (Set.size >= 2 when candidates >= 2)
+ * and keyword overlap similarity (reject if intersection / max(|A|, |B|) > 0.8
+ * for words > 3 chars per D-05).
+ *
+ * This is SOFT enforcement: returns a result, never throws.
+ * Pipeline continues regardless of diversityCheckPassed value.
+ *
+ * @param candidates - Dreamer candidates to validate
+ * @returns DiversityValidationResult with pass/fail details
+ */
+export function validateCandidateDiversity(
+  candidates: DreamerCandidate[],
+): DiversityValidationResult {
+  // Edge cases: empty, null, or single candidate always passes
+  if (!candidates || candidates.length <= 1) {
+    return {
+      diversityCheckPassed: true,
+      riskLevelDiversity: true,
+      keywordOverlapPassed: true,
+      maxOverlapScore: 0,
+      details: candidates?.length === 1
+        ? 'Single candidate — diversity check not applicable'
+        : 'No candidates to validate',
+    };
+  }
+
+  // Check 1: Risk level diversity (D-05)
+  const riskLevels = new Set(
+    candidates
+      .map(c => c.riskLevel)
+      .filter((r): r is "low" | "medium" | "high" => typeof r === 'string')
+  );
+  // If NO candidates have riskLevel, skip risk diversity check (graceful degradation)
+  const riskLevelDiversity = riskLevels.size === 0 || riskLevels.size >= 2;
+
+  // Check 2: Keyword overlap (D-05: intersection / max(|A|, |B|) for words > 3 chars)
+  let maxOverlapScore = 0;
+  let keywordOverlapPassed = true;
+
+  for (let i = 0; i < candidates.length; i++) {
+    for (let j = i + 1; j < candidates.length; j++) {
+      const overlap = computeKeywordOverlap(
+        candidates[i].betterDecision ?? '',
+        candidates[j].betterDecision ?? '',
+      );
+      if (overlap > maxOverlapScore) {
+        maxOverlapScore = overlap;
+      }
+      if (overlap > 0.8) {
+        keywordOverlapPassed = false;
+      }
+    }
+  }
+
+  const diversityCheckPassed = riskLevelDiversity && keywordOverlapPassed;
+
+  // Build details string
+  const parts: string[] = [];
+  if (!riskLevelDiversity) {
+    parts.push(`Risk levels not diverse (found: ${[...riskLevels].join(', ') || 'none'})`);
+  }
+  if (!keywordOverlapPassed) {
+    parts.push(`Keyword overlap too high (max: ${maxOverlapScore.toFixed(2)})`);
+  }
+
+  return {
+    diversityCheckPassed,
+    riskLevelDiversity,
+    keywordOverlapPassed,
+    maxOverlapScore: Math.round(maxOverlapScore * 100) / 100,
+    details: diversityCheckPassed
+      ? 'Diversity check passed'
+      : parts.join('; '),
+  };
+}
+
+/**
+ * Compute keyword overlap between two strings.
+ * Algorithm: intersection / max(|A|, |B|) for words > 3 chars (per D-05).
+ * Returns value between 0 and 1.
+ */
+function computeKeywordOverlap(textA: string, textB: string): number {
+  const wordsA = extractKeywords(textA);
+  const wordsB = extractKeywords(textB);
+
+  if (wordsA.length === 0 && wordsB.length === 0) return 0;
+  if (wordsA.length === 0 || wordsB.length === 0) return 0;
+
+  const setA = new Set(wordsA);
+  const setB = new Set(wordsB);
+
+  let intersection = 0;
+  for (const word of setA) {
+    if (setB.has(word)) intersection++;
+  }
+
+  const denominator = Math.max(setA.size, setB.size);
+  return denominator === 0 ? 0 : intersection / denominator;
+}
+
+/**
+ * Extract keywords from text: words > 3 characters, lowercased.
+ */
+function extractKeywords(text: string): string[] {
+  if (!text) return [];
+  return text
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(w => w.length > 3);
+}
+
 /**
  * Score and rank all candidates deterministically.
  *

package/src/core/nocturnal-reasoning-deriver.ts

@@ -0,0 +1,337 @@
+/**
+ * Nocturnal Reasoning Deriver — Runtime Reasoning Signal Extraction
+ * ==============================================================
+ *
+ * PURPOSE: Derive structured reasoning signals from existing snapshot data
+ * without any snapshot schema changes. Pure functions, zero dependencies.
+ *
+ * THREE FUNCTIONS:
+ * - deriveReasoningChain: Extract thinking content, uncertainty, confidence from assistant turns
+ * - deriveDecisionPoints: Extract before/after context per tool call (Plan 02)
+ * - deriveContextualFactors: Compute contextual factors from snapshot (Plan 02)
+ */
+
+import type { NocturnalAssistantTurn, NocturnalToolCall, NocturnalUserTurn, NocturnalSessionSnapshot } from './nocturnal-trajectory-extractor.js';
+import { detectThinkingModelMatches, listThinkingModels } from './thinking-models.js';
+
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+
+/** Parse an ISO 8601 timestamp, returning NaN for invalid formats. */
+function parseTs(ts: string): number {
+  // ISO 8601 strings without Z suffix or offset are treated as local time.
+  // Log a warning for ambiguous formats (missing timezone indicator).
+  if (
+    typeof ts === 'string' &&
+    !ts.endsWith('Z') &&
+    !ts.includes('+') &&
+    ts.includes('-', 4)
+  ) {
+    // Looks like an ISO date but no timezone — could be ambiguous
+    const bare = ts.slice(0, 10);
+    if (/^\d{4}-\d{2}-\d{2}$/.test(bare)) {
+      // Plain YYYY-MM-DD without time or Z — definitely ambiguous
+      console.warn(`[Deriver] Timestamp missing timezone: "${ts}"`);
+    }
+  }
+  return Date.parse(ts);
+}
+
+// ---------------------------------------------------------------------------
+// Shared types (used across all three derive functions)
+// ---------------------------------------------------------------------------
+
+export interface DerivedReasoningSignal {
+  turnIndex: number;
+  thinkingContent: string;
+  uncertaintyMarkers: string[];
+  confidenceSignal: "high" | "medium" | "low";
+}
+
+export interface DerivedDecisionPoint {
+  toolName: string;
+  outcome: "success" | "failure" | "blocked";
+  beforeContext: string;
+  afterReflection?: string;
+  confidenceDelta?: number;
+}
+
+export interface DerivedContextualFactors {
+  fileStructureKnown: boolean;
+  errorHistoryPresent: boolean;
+  userGuidanceAvailable: boolean;
+  timePressure: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const UNCERTAINTY_PATTERNS: RegExp[] = [
+  /let me (check|verify|confirm|understand)/gi,
+  /I should (first|probably|maybe)/gi,
+  /not sure (if|whether|about)/gi,
+];
+
+const THINKING_TAG_REGEX = /<thinking>([\s\S]*?)<\/thinking>/g;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute thinking model activation ratio for text.
+ * Uses detectThinkingModelMatches() from thinking-models.ts.
+ * Returns 0-1, rounded to 2 decimal places.
+ */
+function computeThinkingModelActivation(text: string): number {
+  if (!text || text.trim().length === 0) return 0;
+  const matches = detectThinkingModelMatches(text);
+  const totalModels = listThinkingModels().length;
+  if (totalModels === 0) return 0;
+  return Math.round((matches.length / totalModels) * 100) / 100;
+}
+
+/**
+ * Map activation ratio (0-1) to confidence signal.
+ * Thresholds: high > 0.6, medium 0.3-0.6, low < 0.3
+ */
+function mapConfidenceSignal(activation: number): "high" | "medium" | "low" {
+  if (activation > 0.6) return "high";
+  if (activation >= 0.3) return "medium";
+  return "low";
+}
+
+// ---------------------------------------------------------------------------
+// deriveReasoningChain (DERIV-01)
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract thinking content, uncertainty markers, and confidence signal
+ * from each assistant turn in the snapshot.
+ *
+ * DERIV-01: Returns one DerivedReasoningSignal per assistant turn.
+ * Empty input returns empty array. Never throws.
+ */
+export function deriveReasoningChain(assistantTurns: NocturnalAssistantTurn[]): DerivedReasoningSignal[] {
+  if (!assistantTurns || assistantTurns.length === 0) return [];
+
+  return assistantTurns.map(turn => {
+    const text = turn.sanitizedText ?? '';
+
+    // Extract all <thinking> content blocks (multiple blocks per turn possible)
+    const thinkingMatches = [...text.matchAll(THINKING_TAG_REGEX)];
+    const thinkingContent = thinkingMatches.map(m => m[1].trim()).join('\n');
+
+    // Detect uncertainty markers (collect all unique matches across 3 patterns)
+    const uncertaintyMarkers: string[] = [];
+    for (const pattern of UNCERTAINTY_PATTERNS) {
+      // Reset lastIndex to avoid g-flag state issues
+      pattern.lastIndex = 0;
+      const matches = text.match(pattern);
+      if (matches) {
+        for (const m of matches) {
+          if (!uncertaintyMarkers.includes(m)) {
+            uncertaintyMarkers.push(m);
+          }
+        }
+      }
+    }
+
+    // Confidence signal: only meaningful when <thinking> content exists.
+    // Without thinking tags we cannot extract a genuine reasoning trace, so
+    // we fall back to 'low' rather than misleading the downstream pipeline
+    // with activation derived from non-thinking patterns in the response text.
+    let confidenceSignal: "high" | "medium" | "low";
+    if (thinkingContent.length === 0) {
+      confidenceSignal = 'low';
+    } else {
+      const activation = computeThinkingModelActivation(text);
+      confidenceSignal = mapConfidenceSignal(activation);
+    }
+
+    return {
+      turnIndex: turn.turnIndex,
+      thinkingContent,
+      uncertaintyMarkers,
+      confidenceSignal,
+    };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Helpers (Plan 02)
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert confidence signal to numeric value for delta computation.
+ * high=1, medium=0.5, low=0
+ */
+function confidenceToNumber(signal: "high" | "medium" | "low"): number {
+  switch (signal) {
+    case "high": return 1;
+    case "medium": return 0.5;
+    case "low": return 0;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// deriveDecisionPoints (DERIV-02)
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract before-context and after-reflection for each tool call.
+ *
+ * DERIV-02: For each tool call, find the assistant turn immediately before it
+ * (by createdAt timestamp) and extract last 500 chars as beforeContext.
+ * On failure outcome, find the next assistant turn and extract first 300 chars
+ * as afterReflection. Compute confidence delta between before/after.
+ *
+ * Empty inputs return empty array. Never throws.
+ */
+export function deriveDecisionPoints(
+  assistantTurns: NocturnalAssistantTurn[],
+  toolCalls: NocturnalToolCall[],
+): DerivedDecisionPoint[] {
+  if (!toolCalls || toolCalls.length === 0) return [];
+  if (!assistantTurns || assistantTurns.length === 0) {
+    // Return decision points with empty beforeContext when no assistant turns
+    return toolCalls.map(tc => ({
+      toolName: tc.toolName,
+      outcome: tc.outcome,
+      beforeContext: '',
+    }));
+  }
+
+  // Sort assistant turns by createdAt for binary search
+  const sortedTurns = [...assistantTurns].sort(
+    (a, b) => parseTs(a.createdAt) - parseTs(b.createdAt)
+  );
+
+  // Binary search: find rightmost assistant turn with createdAt < tcTime
+  const findBeforeTurn = (tcTime: number): NocturnalAssistantTurn | undefined => {
+    let lo = 0, hi = sortedTurns.length - 1, result: NocturnalAssistantTurn | undefined;
+    while (lo <= hi) {
+      const mid = (lo + hi) >>> 1;
+      if (parseTs(sortedTurns[mid].createdAt) < tcTime) {
+        result = sortedTurns[mid];
+        lo = mid + 1;
+      } else {
+        hi = mid - 1;
+      }
+    }
+    return result;
+  };
+
+  return toolCalls.map(tc => {
+    const tcTime = parseTs(tc.createdAt);
+    const beforeTurn = findBeforeTurn(tcTime);
+
+    const beforeContext = beforeTurn
+      ? beforeTurn.sanitizedText.slice(-500)
+      : '';
+
+    // On failure, find next assistant turn after tool call
+    let afterReflection: string | undefined;
+    let confidenceDelta: number | undefined;
+
+    if (tc.outcome === 'failure') {
+      const afterTurn = sortedTurns.find(
+        turn => parseTs(turn.createdAt) > tcTime
+      );
+      if (afterTurn) {
+        afterReflection = afterTurn.sanitizedText.slice(0, 300);
+      }
+
+      // Compute confidence delta if both before and after turns exist
+      if (beforeTurn && afterTurn) {
+        const beforeConfidence = confidenceToNumber(
+          mapConfidenceSignal(computeThinkingModelActivation(beforeTurn.sanitizedText))
+        );
+        const afterConfidence = confidenceToNumber(
+          mapConfidenceSignal(computeThinkingModelActivation(afterTurn.sanitizedText))
+        );
+        confidenceDelta = Math.round((afterConfidence - beforeConfidence) * 100) / 100;
+      }
+    }
+
+    const result: DerivedDecisionPoint = {
+      toolName: tc.toolName,
+      outcome: tc.outcome,
+      beforeContext,
+    };
+    if (afterReflection !== undefined) result.afterReflection = afterReflection;
+    if (confidenceDelta !== undefined) result.confidenceDelta = confidenceDelta;
+    return result;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// deriveContextualFactors (DERIV-03)
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute contextual factors from session snapshot data.
+ *
+ * DERIV-03: Four boolean factors indicating the environment
+ * the agent was operating in. All derived from existing snapshot
+ * fields -- no schema changes.
+ *
+ * Empty/missing data returns all-false defaults. Never throws.
+ */
+export function deriveContextualFactors(
+  snapshot: NocturnalSessionSnapshot,
+): DerivedContextualFactors {
+  const defaults: DerivedContextualFactors = {
+    fileStructureKnown: false,
+    errorHistoryPresent: false,
+    userGuidanceAvailable: false,
+    timePressure: false,
+  };
+
+  if (!snapshot) return defaults;
+
+  const { toolCalls = [], userTurns = [] } = snapshot;
+
+  // fileStructureKnown: any Read tool precedes any Write tool in chronological order
+  let fileStructureKnown = false;
+  const isReadTool = (name: string) => /^(read|grep|search|find|inspect|look)/i.test(name);
+  const isWriteTool = (name: string) => /^(edit|write|create|delete|remove|move|rename)/i.test(name);
+  let hasSeenRead = false;
+  for (const tc of toolCalls) {
+    if (isReadTool(tc.toolName)) hasSeenRead = true;
+    if (isWriteTool(tc.toolName) && hasSeenRead) {
+      fileStructureKnown = true;
+      break;
+    }
+  }
+
+  // errorHistoryPresent: any tool call with outcome === 'failure'
+  const errorHistoryPresent = toolCalls.some(tc => tc.outcome === 'failure');
+
+  // userGuidanceAvailable: any user turn with correctionDetected === true
+  const userGuidanceAvailable = (userTurns || []).some(ut => ut.correctionDetected === true);
+
+  // timePressure: >50% of consecutive tool call pairs have < 2s gap
+  let timePressure = false;
+  if (toolCalls.length >= 2) {
+    const sorted = [...toolCalls].sort(
+      (a, b) => parseTs(a.createdAt) - parseTs(b.createdAt)
+    );
+    let rapidGaps = 0;
+    for (let i = 0; i < sorted.length - 1; i++) {
+      const gap = parseTs(sorted[i + 1].createdAt) - parseTs(sorted[i].createdAt);
+      if (gap < 2000) rapidGaps++;
+    }
+    const totalPairs = sorted.length - 1;
+    timePressure = rapidGaps / totalPairs > 0.5;
+  }
+
+  return {
+    fileStructureKnown,
+    errorHistoryPresent,
+    userGuidanceAvailable,
+    timePressure,
+  };
+}