principles-disciple 1.28.0 → 1.28.2

package/src/service/subagent-workflow/deep-reflect-workflow-manager.ts

@@ -150,6 +150,7 @@ export const deepReflectWorkflowSpec: SubagentWorkflowSpec<DeepReflectResult> =
         };
     },
 
+    // eslint-disable-next-line complexity -- complexity 13, refactor candidate
     async persistResult(ctx: WorkflowPersistContext<DeepReflectResult>): Promise<void> {
         const { result, metadata, workspaceDir } = ctx;
 

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

@@ -36,7 +36,6 @@ import {
 } from '../nocturnal-service.js';
 import { type TrinityStageFailure, type TrinityResult } from '../../core/nocturnal-trinity.js';
 import type { TrinityRuntimeAdapter } from '../../core/nocturnal-trinity.js';
-import type { NocturnalSessionSnapshot } from '../../core/nocturnal-trajectory-extractor.js';
 import type { RecentPainContext } from '../evolution-worker.js';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -244,6 +243,7 @@ export class NocturnalWorkflowManager implements WorkflowManager {
         // #213: Wrap fire-and-forget Promise with .catch() to prevent
         // unhandled promise rejections if anything throws outside the try-catch
         // (e.g., during parameter construction or environment errors).
+    // eslint-disable-next-line complexity -- complexity 15, refactor candidate
         Promise.resolve().then(async () => {
             try {
                 const result = await executeNocturnalReflectionAsync(
@@ -652,6 +652,7 @@ export class NocturnalWorkflowManager implements WorkflowManager {
      * Derives stage events from TrinityResult.telemetry and TrinityResult.failures.
      * Always records _start event for each stage that ran, plus _complete or _failed based on outcome.
      */
+    // eslint-disable-next-line complexity -- complexity 12, refactor candidate
     private recordStageEvents(workflowId: string, result: TrinityResult): void {
         const { telemetry, failures } = result;
 

package/src/service/subagent-workflow/subagent-error-utils.ts

@@ -5,6 +5,7 @@
  *
  * Callers should suppress warnings for these errors — they are not real failures.
  */
+    // eslint-disable-next-line complexity -- complexity 13, refactor candidate
 export function isExpectedSubagentError(err: unknown): boolean {
     const msg = String(err);
     return (

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

@@ -449,6 +449,7 @@ export abstract class WorkflowManagerBase implements WorkflowManager {
         }
     }
 
+        // eslint-disable-next-line complexity -- complexity 11, slightly over threshold
     async sweepExpiredWorkflows(maxAgeMs?: number): Promise<number> {
         const ttl = maxAgeMs ?? this.defaultTtlMs;
         const expired = this.store.getExpiredWorkflows(ttl);

package/src/tools/critique-prompt.ts

@@ -17,6 +17,7 @@ const DEPTH_INSTRUCTIONS = {
  * 严格按照测试用例的调用习惯和断言要求进行重写。
  * 增加 OpenClaw 兼容性路径解析。
  */
+    // eslint-disable-next-line complexity -- complexity 12, refactor candidate
 export function buildCritiquePromptV2(
     params: {
         context: string;

package/src/utils/io.ts

@@ -2,6 +2,7 @@ import * as path from 'path';
 import * as fs from 'fs';
 import { resolvePdPath } from '../core/paths.js';
 
+    // eslint-disable-next-line complexity -- complexity 12, refactor candidate
 export function normalizePath(filePath: string, projectDir: string): string {
   if (!filePath) return '';
 

package/tests/core/nocturnal-candidate-scoring.test.ts

@@ -5,6 +5,7 @@ import {
   rankCandidates,
   runTournament,
   DEFAULT_SCORING_WEIGHTS,
+  validateCandidateDiversity,
 } from '../../src/core/nocturnal-candidate-scoring.js';
 import type { DreamerCandidate, PhilosopherJudgment } from '../../src/core/nocturnal-trinity.js';
 import type { ThresholdValues } from '../../src/core/adaptive-thresholds.js';
@@ -398,3 +399,134 @@ describe('DEFAULT_SCORING_WEIGHTS', () => {
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// Tests: validateCandidateDiversity
+// ---------------------------------------------------------------------------
+
+describe('validateCandidateDiversity', () => {
+  it('passes when candidates have 2+ distinct risk levels and low keyword overlap', () => {
+    const candidates: DreamerCandidate[] = [
+      makeCandidate({ candidateIndex: 0, riskLevel: 'low', betterDecision: 'Read config.json to verify settings' }),
+      makeCandidate({ candidateIndex: 1, riskLevel: 'high', betterDecision: 'Refactor the entire authentication module from scratch' }),
+    ];
+    const result = validateCandidateDiversity(candidates);
+    expect(result.diversityCheckPassed).toBe(true);
+    expect(result.riskLevelDiversity).toBe(true);
+    expect(result.keywordOverlapPassed).toBe(true);
+  });
+
+  it('fails when all candidates have the same risk level', () => {
+    const candidates: DreamerCandidate[] = [
+      makeCandidate({ candidateIndex: 0, riskLevel: 'low', betterDecision: 'Read file A to check settings' }),
+      makeCandidate({ candidateIndex: 1, riskLevel: 'low', betterDecision: 'Review file completely different approach' }),
+      makeCandidate({ candidateIndex: 2, riskLevel: 'low', betterDecision: 'Inspect another unique diagnostic method' }),
+    ];
+    const result = validateCandidateDiversity(candidates);
+    expect(result.diversityCheckPassed).toBe(false);
+    expect(result.riskLevelDiversity).toBe(false);
+  });
+
+  it('fails when candidate pair has keyword overlap > 0.8', () => {
+    const candidates: DreamerCandidate[] = [
+      makeCandidate({ candidateIndex: 0, riskLevel: 'low', betterDecision: 'Review the authentication configuration file before making any changes to the system' }),
+      makeCandidate({ candidateIndex: 1, riskLevel: 'high', betterDecision: 'Review the authentication configuration file before making any changes to the system' }),
+    ];
+    const result = validateCandidateDiversity(candidates);
+    expect(result.diversityCheckPassed).toBe(false);
+    expect(result.keywordOverlapPassed).toBe(false);
+    expect(result.maxOverlapScore).toBeGreaterThan(0.8);
+  });
+
+  it('passes for single candidate', () => {
+    const candidates: DreamerCandidate[] = [
+      makeCandidate({ candidateIndex: 0, riskLevel: 'low' }),
+    ];
+    const result = validateCandidateDiversity(candidates);
+    expect(result.diversityCheckPassed).toBe(true);
+    expect(result.details).toContain('Single candidate');
+  });
+
+  it('passes for empty array', () => {
+    const result = validateCandidateDiversity([]);
+    expect(result.diversityCheckPassed).toBe(true);
+    expect(result.details).toContain('No candidates');
+  });
+
+  it('passes when candidates lack riskLevel (graceful degradation)', () => {
+    const candidates: DreamerCandidate[] = [
+      makeCandidate({ candidateIndex: 0, betterDecision: 'Read config.json to verify settings' }),
+      makeCandidate({ candidateIndex: 1, betterDecision: 'Refactor the entire authentication module from scratch' }),
+    ];
+    // No riskLevel on any candidate - should pass (no risk levels to check)
+    const result = validateCandidateDiversity(candidates);
+    expect(result.diversityCheckPassed).toBe(true);
+    expect(result.riskLevelDiversity).toBe(true);
+  });
+
+  it('fails when some candidates have riskLevel but fewer than 2 distinct values', () => {
+    const candidates: DreamerCandidate[] = [
+      makeCandidate({ candidateIndex: 0, riskLevel: 'medium', betterDecision: 'Read config.json to verify settings' }),
+      makeCandidate({ candidateIndex: 1, betterDecision: 'Refactor the entire authentication module from scratch' }),
+    ];
+    // Only 1 candidate has riskLevel, so only 1 distinct value → fail
+    const result = validateCandidateDiversity(candidates);
+    expect(result.diversityCheckPassed).toBe(false);
+    expect(result.riskLevelDiversity).toBe(false);
+  });
+
+  it('uses max(|A|, |B|) as denominator for keyword overlap', () => {
+    // Short text A, long text B - overlap should use max as denominator
+    const candidates: DreamerCandidate[] = [
+      makeCandidate({ candidateIndex: 0, riskLevel: 'low', betterDecision: 'review authentication configuration' }),
+      makeCandidate({ candidateIndex: 1, riskLevel: 'high', betterDecision: 'review authentication configuration before proceeding with changes to the deployment pipeline infrastructure' }),
+    ];
+    const result = validateCandidateDiversity(candidates);
+    // "review", "authentication", "configuration" overlap in both
+    // Set A = {review, authentication, configuration} = 3
+    // Set B = {review, authentication, configuration, before, proceeding, with, changes, deployment, pipeline, infrastructure} = 10
+    // intersection = 3, max(3, 10) = 10, overlap = 3/10 = 0.3
+    expect(result.maxOverlapScore).toBeLessThanOrEqual(0.4);
+  });
+
+  it('ignores words <= 3 characters in keyword overlap', () => {
+    const candidates: DreamerCandidate[] = [
+      makeCandidate({ candidateIndex: 0, riskLevel: 'low', betterDecision: 'the and but for' }),
+      makeCandidate({ candidateIndex: 1, riskLevel: 'high', betterDecision: 'the and but for' }),
+    ];
+    // All words are <= 3 chars, so no keywords extracted → overlap = 0
+    const result = validateCandidateDiversity(candidates);
+    expect(result.keywordOverlapPassed).toBe(true);
+    expect(result.maxOverlapScore).toBe(0);
+  });
+
+  it('never throws on malformed input', () => {
+    // Undefined candidates
+    expect(() => validateCandidateDiversity(undefined as unknown as DreamerCandidate[])).not.toThrow();
+    // Null candidates
+    expect(() => validateCandidateDiversity(null as unknown as DreamerCandidate[])).not.toThrow();
+    // Candidates with undefined fields
+    expect(() => validateCandidateDiversity([
+      { candidateIndex: 0 } as DreamerCandidate,
+    ])).not.toThrow();
+    // Mixed valid and malformed
+    expect(() => validateCandidateDiversity([
+      makeCandidate({ candidateIndex: 0, riskLevel: 'low' }),
+      { candidateIndex: 1 } as DreamerCandidate,
+    ])).not.toThrow();
+  });
+
+  it('returns correct maxOverlapScore rounded to 2 decimal places', () => {
+    const candidates: DreamerCandidate[] = [
+      makeCandidate({ candidateIndex: 0, riskLevel: 'low', betterDecision: 'Review configuration settings before deployment' }),
+      makeCandidate({ candidateIndex: 1, riskLevel: 'high', betterDecision: 'Review configuration settings before deployment testing' }),
+    ];
+    const result = validateCandidateDiversity(candidates);
+    // Verify the maxOverlapScore is a number with at most 2 decimal places
+    const decimalPart = result.maxOverlapScore.toString().split('.')[1];
+    if (decimalPart) {
+      expect(decimalPart.length).toBeLessThanOrEqual(2);
+    }
+    expect(typeof result.maxOverlapScore).toBe('number');
+  });
+});

package/tests/core/nocturnal-reasoning-deriver.test.ts

@@ -0,0 +1,372 @@
+import { describe, it, expect } from 'vitest';
+import {
+  deriveReasoningChain,
+  deriveDecisionPoints,
+  deriveContextualFactors,
+} from '../../src/core/nocturnal-reasoning-deriver.js';
+import type {
+  NocturnalAssistantTurn,
+  NocturnalToolCall,
+  NocturnalUserTurn,
+  NocturnalSessionSnapshot,
+} from '../../src/core/nocturnal-trajectory-extractor.js';
+
+// ---------------------------------------------------------------------------
+// Test Fixtures
+// ---------------------------------------------------------------------------
+
+function makeAssistantTurn(overrides: Partial<NocturnalAssistantTurn> = {}): NocturnalAssistantTurn {
+  return {
+    turnIndex: 0,
+    sanitizedText: 'I will read the file to understand the structure before making changes.',
+    model: 'gpt-4',
+    createdAt: '2026-04-12T10:00:00.000Z',
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// deriveReasoningChain
+// ---------------------------------------------------------------------------
+
+describe('deriveReasoningChain', () => {
+  it('extracts thinking content from <thinking> tags', () => {
+    const turns = [makeAssistantTurn({
+      sanitizedText: '<thinking>planning the approach</thinking>Now I will proceed.',
+    })];
+    const result = deriveReasoningChain(turns);
+    expect(result).toHaveLength(1);
+    expect(result[0].thinkingContent).toBe('planning the approach');
+  });
+
+  it('returns empty thinkingContent when no <thinking> tags present', () => {
+    const turns = [makeAssistantTurn({
+      sanitizedText: 'I will just read the file and proceed.',
+    })];
+    const result = deriveReasoningChain(turns);
+    expect(result[0].thinkingContent).toBe('');
+  });
+
+  it('detects uncertainty markers', () => {
+    const turns = [makeAssistantTurn({
+      sanitizedText: 'let me verify the output. not sure if this is correct.',
+    })];
+    const result = deriveReasoningChain(turns);
+    expect(result[0].uncertaintyMarkers).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining('let me verify'),
+        expect.stringContaining('not sure if'),
+      ]),
+    );
+  });
+
+  it('detects all 3 uncertainty patterns', () => {
+    const turns = [makeAssistantTurn({
+      sanitizedText: 'let me check the file. I should probably review this. not sure whether this works.',
+    })];
+    const result = deriveReasoningChain(turns);
+    expect(result[0].uncertaintyMarkers.length).toBeGreaterThanOrEqual(3);
+  });
+
+  it('computes high confidence signal', () => {
+    // Use text rich in thinking model patterns to trigger high activation
+    const richText = 'Let me plan this carefully. I need to analyze the structure first. ' +
+      'The approach should consider multiple perspectives. Let me think step by step. ' +
+      'I should verify my understanding. Breaking this down into parts helps. ' +
+      'Consider the constraints and requirements carefully.';
+    const turns = [makeAssistantTurn({ sanitizedText: richText })];
+    const result = deriveReasoningChain(turns);
+    // The exact signal depends on thinking model definitions, but it should be one of the three
+    expect(['high', 'medium', 'low']).toContain(result[0].confidenceSignal);
+  });
+
+  it('computes low confidence signal', () => {
+    const turns = [makeAssistantTurn({
+      sanitizedText: 'Just a simple text with no particular patterns.',
+    })];
+    const result = deriveReasoningChain(turns);
+    expect(result[0].confidenceSignal).toBe('low');
+  });
+
+  it('returns empty array for empty input', () => {
+    expect(deriveReasoningChain([])).toEqual([]);
+  });
+
+  it('returns empty array for null input', () => {
+    expect(deriveReasoningChain(null as any)).toEqual([]);
+  });
+
+  it('handles multiple turns correctly', () => {
+    const turns = [
+      makeAssistantTurn({ turnIndex: 0, sanitizedText: 'First turn.' }),
+      makeAssistantTurn({ turnIndex: 1, sanitizedText: '<thinking>Second turn thinking</thinking>' }),
+      makeAssistantTurn({ turnIndex: 2, sanitizedText: 'let me check this. Third turn.' }),
+    ];
+    const result = deriveReasoningChain(turns);
+    expect(result).toHaveLength(3);
+    expect(result.map(r => r.turnIndex)).toEqual([0, 1, 2]);
+  });
+
+  it('handles empty sanitizedText gracefully', () => {
+    const turns = [makeAssistantTurn({ sanitizedText: '' })];
+    const result = deriveReasoningChain(turns);
+    expect(result[0].thinkingContent).toBe('');
+    expect(result[0].uncertaintyMarkers).toEqual([]);
+    expect(result[0].confidenceSignal).toBe('low');
+  });
+
+  it('extracts thinking content from multiline tags', () => {
+    const turns = [makeAssistantTurn({
+      sanitizedText: '<thinking>\nStep 1: analyze\nStep 2: plan\n</thinking>',
+    })];
+    const result = deriveReasoningChain(turns);
+    expect(result[0].thinkingContent).toContain('Step 1: analyze');
+    expect(result[0].thinkingContent).toContain('Step 2: plan');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Test Fixtures (Plan 02)
+// ---------------------------------------------------------------------------
+
+function makeToolCall(overrides: Partial<NocturnalToolCall> = {}): NocturnalToolCall {
+  return {
+    toolName: 'edit',
+    outcome: 'success',
+    filePath: 'src/index.ts',
+    durationMs: 150,
+    exitCode: 0,
+    errorType: null,
+    errorMessage: null,
+    createdAt: '2026-04-12T10:01:00.000Z',
+    ...overrides,
+  };
+}
+
+function makeUserTurn(overrides: Partial<NocturnalUserTurn> = {}): NocturnalUserTurn {
+  return {
+    turnIndex: 0,
+    correctionDetected: false,
+    correctionCue: null,
+    createdAt: '2026-04-12T10:00:30.000Z',
+    ...overrides,
+  };
+}
+
+function makeSnapshot(overrides: Partial<NocturnalSessionSnapshot> = {}): NocturnalSessionSnapshot {
+  return {
+    sessionId: 'test-session-001',
+    startedAt: '2026-04-12T10:00:00.000Z',
+    updatedAt: '2026-04-12T10:05:00.000Z',
+    assistantTurns: [],
+    userTurns: [],
+    toolCalls: [],
+    painEvents: [],
+    gateBlocks: [],
+    stats: {
+      totalAssistantTurns: 0,
+      totalToolCalls: 0,
+      totalPainEvents: 0,
+      totalGateBlocks: 0,
+      failureCount: 0,
+    },
+    ...overrides,
+  } as NocturnalSessionSnapshot;
+}
+
+// ---------------------------------------------------------------------------
+// deriveDecisionPoints
+// ---------------------------------------------------------------------------
+
+describe('deriveDecisionPoints', () => {
+  it('extracts beforeContext from preceding assistant turn', () => {
+    const turns = [makeAssistantTurn({
+      sanitizedText: 'I will analyze the code structure before making changes to ensure correctness.',
+      createdAt: '2026-04-12T10:00:00.000Z',
+    })];
+    const toolCalls = [makeToolCall({ createdAt: '2026-04-12T10:01:00.000Z' })];
+    const result = deriveDecisionPoints(turns, toolCalls);
+    expect(result).toHaveLength(1);
+    expect(result[0].beforeContext).toBe('I will analyze the code structure before making changes to ensure correctness.');
+    expect(result[0].toolName).toBe('edit');
+    expect(result[0].outcome).toBe('success');
+  });
+
+  it('extracts afterReflection on failure outcome', () => {
+    const turns = [
+      makeAssistantTurn({ createdAt: '2026-04-12T10:00:00.000Z', sanitizedText: 'before' }),
+      makeAssistantTurn({ createdAt: '2026-04-12T10:02:00.000Z', sanitizedText: 'After the failure I need to reconsider the approach and try a different method' }),
+    ];
+    const toolCalls = [makeToolCall({
+      outcome: 'failure',
+      createdAt: '2026-04-12T10:01:00.000Z',
+    })];
+    const result = deriveDecisionPoints(turns, toolCalls);
+    expect(result[0].afterReflection).toBe('After the failure I need to reconsider the approach and try a different method');
+    expect(result[0].outcome).toBe('failure');
+  });
+
+  it('omits afterReflection on success outcome', () => {
+    const turns = [makeAssistantTurn({ createdAt: '2026-04-12T10:00:00.000Z' })];
+    const toolCalls = [makeToolCall({ outcome: 'success', createdAt: '2026-04-12T10:01:00.000Z' })];
+    const result = deriveDecisionPoints(turns, toolCalls);
+    expect(result[0].afterReflection).toBeUndefined();
+  });
+
+  it('returns empty array for empty toolCalls', () => {
+    expect(deriveDecisionPoints([makeAssistantTurn()], [])).toEqual([]);
+  });
+
+  it('returns empty beforeContext when no assistant turns', () => {
+    const toolCalls = [makeToolCall()];
+    const result = deriveDecisionPoints([], toolCalls);
+    expect(result).toHaveLength(1);
+    expect(result[0].beforeContext).toBe('');
+  });
+
+  it('computes confidenceDelta on failure', () => {
+    const beforeText = 'Let me plan this carefully. I need to analyze the structure first. ' +
+      'The approach should consider multiple perspectives. Let me think step by step. ' +
+      'I should verify my understanding. Breaking this down into parts helps.';
+    const turns = [
+      makeAssistantTurn({ createdAt: '2026-04-12T10:00:00.000Z', sanitizedText: beforeText }),
+      makeAssistantTurn({ createdAt: '2026-04-12T10:02:00.000Z', sanitizedText: 'ok' }),
+    ];
+    const toolCalls = [makeToolCall({ outcome: 'failure', createdAt: '2026-04-12T10:01:00.000Z' })];
+    const result = deriveDecisionPoints(turns, toolCalls);
+    // confidenceDelta should be computed (defined) when both before and after turns exist
+    expect(result[0].confidenceDelta).toBeDefined();
+    expect(typeof result[0].confidenceDelta).toBe('number');
+  });
+
+  it('matches by createdAt timestamp not turnIndex', () => {
+    const turns = [
+      makeAssistantTurn({ turnIndex: 2, createdAt: '2026-04-12T10:00:00.000Z', sanitizedText: 'turn index 2' }),
+      makeAssistantTurn({ turnIndex: 0, createdAt: '2026-04-12T09:59:00.000Z', sanitizedText: 'turn index 0' }),
+    ];
+    const toolCalls = [makeToolCall({ createdAt: '2026-04-12T10:01:00.000Z' })];
+    const result = deriveDecisionPoints(turns, toolCalls);
+    // Should pick turnIndex 2 (closest before tool call by timestamp)
+    expect(result[0].beforeContext).toBe('turn index 2');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// deriveContextualFactors
+// ---------------------------------------------------------------------------
+
+describe('deriveContextualFactors', () => {
+  it('computes all four factors from a rich snapshot', () => {
+    const snapshot = makeSnapshot({
+      toolCalls: [
+        makeToolCall({ toolName: 'read', outcome: 'success', createdAt: '2026-04-12T10:00:00.000Z' }),
+        makeToolCall({ toolName: 'edit', outcome: 'success', createdAt: '2026-04-12T10:00:01.000Z' }),
+        makeToolCall({ toolName: 'edit', outcome: 'failure', createdAt: '2026-04-12T10:00:02.000Z' }),
+      ],
+      userTurns: [makeUserTurn({ correctionDetected: true })],
+    });
+    const result = deriveContextualFactors(snapshot);
+    expect(result.fileStructureKnown).toBe(true);
+    expect(result.errorHistoryPresent).toBe(true);
+    expect(result.userGuidanceAvailable).toBe(true);
+    expect(result.timePressure).toBe(true);
+  });
+
+  it('fileStructureKnown: true when read precedes write', () => {
+    const snapshot = makeSnapshot({
+      toolCalls: [
+        makeToolCall({ toolName: 'read', createdAt: '2026-04-12T10:00:00.000Z' }),
+        makeToolCall({ toolName: 'edit', createdAt: '2026-04-12T10:00:01.000Z' }),
+      ],
+    });
+    expect(deriveContextualFactors(snapshot).fileStructureKnown).toBe(true);
+  });
+
+  it('fileStructureKnown: false when write has no preceding read', () => {
+    const snapshot = makeSnapshot({
+      toolCalls: [
+        makeToolCall({ toolName: 'edit', createdAt: '2026-04-12T10:00:00.000Z' }),
+        makeToolCall({ toolName: 'read', createdAt: '2026-04-12T10:00:01.000Z' }),
+      ],
+    });
+    expect(deriveContextualFactors(snapshot).fileStructureKnown).toBe(false);
+  });
+
+  it('fileStructureKnown: false with only write tools', () => {
+    const snapshot = makeSnapshot({
+      toolCalls: [makeToolCall({ toolName: 'edit' })],
+    });
+    expect(deriveContextualFactors(snapshot).fileStructureKnown).toBe(false);
+  });
+
+  it('errorHistoryPresent: true when any tool call failed', () => {
+    const snapshot = makeSnapshot({
+      toolCalls: [
+        makeToolCall({ outcome: 'success' }),
+        makeToolCall({ outcome: 'failure' }),
+      ],
+    });
+    expect(deriveContextualFactors(snapshot).errorHistoryPresent).toBe(true);
+  });
+
+  it('errorHistoryPresent: false when all outcomes are success', () => {
+    const snapshot = makeSnapshot({
+      toolCalls: [makeToolCall({ outcome: 'success' })],
+    });
+    expect(deriveContextualFactors(snapshot).errorHistoryPresent).toBe(false);
+  });
+
+  it('userGuidanceAvailable: true when correction detected', () => {
+    const snapshot = makeSnapshot({
+      userTurns: [makeUserTurn({ correctionDetected: true })],
+    });
+    expect(deriveContextualFactors(snapshot).userGuidanceAvailable).toBe(true);
+  });
+
+  it('userGuidanceAvailable: false without corrections', () => {
+    const snapshot = makeSnapshot({
+      userTurns: [makeUserTurn({ correctionDetected: false })],
+    });
+    expect(deriveContextualFactors(snapshot).userGuidanceAvailable).toBe(false);
+  });
+
+  it('timePressure: true when majority of gaps < 2 seconds', () => {
+    const snapshot = makeSnapshot({
+      toolCalls: [
+        makeToolCall({ createdAt: '2026-04-12T10:00:00.000Z' }),
+        makeToolCall({ createdAt: '2026-04-12T10:00:01.000Z' }),
+        makeToolCall({ createdAt: '2026-04-12T10:00:01.500Z' }),
+      ],
+    });
+    expect(deriveContextualFactors(snapshot).timePressure).toBe(true);
+  });
+
+  it('timePressure: false when gaps are large', () => {
+    const snapshot = makeSnapshot({
+      toolCalls: [
+        makeToolCall({ createdAt: '2026-04-12T10:00:00.000Z' }),
+        makeToolCall({ createdAt: '2026-04-12T10:00:10.000Z' }),
+        makeToolCall({ createdAt: '2026-04-12T10:00:20.000Z' }),
+      ],
+    });
+    expect(deriveContextualFactors(snapshot).timePressure).toBe(false);
+  });
+
+  it('returns all-false defaults for null snapshot', () => {
+    expect(deriveContextualFactors(null as any)).toEqual({
+      fileStructureKnown: false,
+      errorHistoryPresent: false,
+      userGuidanceAvailable: false,
+      timePressure: false,
+    });
+  });
+
+  it('returns all-false defaults for empty snapshot', () => {
+    expect(deriveContextualFactors(makeSnapshot())).toEqual({
+      fileStructureKnown: false,
+      errorHistoryPresent: false,
+      userGuidanceAvailable: false,
+      timePressure: false,
+    });
+  });
+});