principles-disciple 1.27.0 → 1.28.1

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

@@ -0,0 +1,224 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { TrajectoryDatabase } from '../../src/core/trajectory.js';
+import { NocturnalTrajectoryExtractor } from '../../src/core/nocturnal-trajectory-extractor.js';
+import { detectViolation } from '../../src/core/nocturnal-compliance.js';
+
+function safeRmDir(dir: string): void {
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+}
+
+// ─────────────────────────────────────────────────────────
+// Phase 4a: Correction rejected → pain event → nocturnal selection
+// ─────────────────────────────────────────────────────────
+describe('Phase 4a: Correction rejected integration', () => {
+  let workspaceDir: string;
+  let trajectory: TrajectoryDatabase;
+
+  beforeEach(() => {
+    workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-e2e-correction-'));
+    trajectory = new TrajectoryDatabase({ workspaceDir });
+  });
+
+  afterEach(() => {
+    trajectory?.dispose();
+    safeRmDir(workspaceDir);
+  });
+
+  it('rejected correction creates a pain event with source=correction_rejected', () => {
+    // 1. Create session + correction sample
+    trajectory.recordSession({ sessionId: 'corr-session', startedAt: new Date().toISOString() });
+    const atId = trajectory.recordAssistantTurn({
+      sessionId: 'corr-session', runId: 'run-1', provider: 'local', model: 'main',
+      rawText: 'Here is my code', sanitizedText: 'Here is my code', usageJson: {}, empathySignalJson: {},
+      createdAt: new Date().toISOString(),
+    });
+    trajectory.recordUserTurn({
+      sessionId: 'corr-session', turnIndex: 1, rawText: 'This is wrong!',
+      correctionDetected: true, correctionCue: '错了',
+      referencesAssistantTurnId: atId, createdAt: new Date().toISOString(),
+    });
+
+    // Verify sample was created
+    const samples = trajectory.listCorrectionSamples('pending');
+    expect(samples.length).toBe(1);
+
+    // 2. Reject the sample
+    trajectory.reviewCorrectionSample(samples[0].sampleId, 'rejected', 'Bad approach');
+
+    // 3. Verify pain event was created
+    const painEvents = trajectory.listPainEventsForSession('corr-session');
+    const correctionPain = painEvents.find(e => e.source === 'correction_rejected');
+    expect(correctionPain).toBeDefined();
+    expect(correctionPain!.score).toBeGreaterThanOrEqual(0);
+    expect(correctionPain!.score).toBeLessThanOrEqual(100);
+  });
+
+  it('approved correction does NOT create a pain event', () => {
+    trajectory.recordSession({ sessionId: 'approved-session', startedAt: new Date().toISOString() });
+    const atId = trajectory.recordAssistantTurn({
+      sessionId: 'approved-session', runId: 'run-2', provider: 'local', model: 'main',
+      rawText: 'Good code', sanitizedText: 'Good code', usageJson: {}, empathySignalJson: {},
+      createdAt: new Date().toISOString(),
+    });
+    trajectory.recordUserTurn({
+      sessionId: 'approved-session', turnIndex: 1, rawText: 'Looks better',
+      correctionDetected: true, correctionCue: '改进',
+      referencesAssistantTurnId: atId, createdAt: new Date().toISOString(),
+    });
+
+    const samples = trajectory.listCorrectionSamples('pending');
+    expect(samples.length).toBe(1);
+
+    trajectory.reviewCorrectionSample(samples[0].sampleId, 'approved', 'Good');
+
+    const painEvents = trajectory.listPainEventsForSession('approved-session');
+    const correctionPain = painEvents.find(e => e.source === 'correction_rejected');
+    expect(correctionPain).toBeUndefined();
+  });
+});
+
+// ─────────────────────────────────────────────────────────
+// Phase 4b: Gate block + pain multi-signal test
+// ─────────────────────────────────────────────────────────
+describe('Phase 4b: Multi-signal session selection', () => {
+  let workspaceDir: string;
+  let trajectory: TrajectoryDatabase;
+
+  beforeEach(() => {
+    workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-e2e-multisignal-'));
+    trajectory = new TrajectoryDatabase({ workspaceDir });
+  });
+
+  afterEach(() => {
+    trajectory?.dispose();
+    safeRmDir(workspaceDir);
+  });
+
+  it('session with more failures has higher violation density', () => {
+    // Create session A: just 1 failure
+    trajectory.recordSession({ sessionId: 'session-a-pain-only', startedAt: new Date().toISOString() });
+    const atIdA = trajectory.recordAssistantTurn({
+      sessionId: 'session-a-pain-only', runId: 'run-a', provider: 'local', model: 'main',
+      rawText: 'Code here', sanitizedText: 'Code here', usageJson: {}, empathySignalJson: {},
+      createdAt: new Date().toISOString(),
+    });
+    trajectory.recordUserTurn({
+      sessionId: 'session-a-pain-only', turnIndex: 1, rawText: '错了',
+      correctionDetected: true, correctionCue: '错了',
+      referencesAssistantTurnId: atIdA, createdAt: new Date().toISOString(),
+    });
+    trajectory.recordToolCall({
+      sessionId: 'session-a-pain-only', toolName: 'write', outcome: 'failure',
+      errorMessage: 'Write failed', errorType: 'Error', createdAt: new Date().toISOString(),
+    });
+
+    // Create session B: 2 failures
+    trajectory.recordSession({ sessionId: 'session-b-multi', startedAt: new Date().toISOString() });
+    const atIdB = trajectory.recordAssistantTurn({
+      sessionId: 'session-b-multi', runId: 'run-b', provider: 'local', model: 'main',
+      rawText: 'Code here', sanitizedText: 'Code here', usageJson: {}, empathySignalJson: {},
+      createdAt: new Date().toISOString(),
+    });
+    trajectory.recordUserTurn({
+      sessionId: 'session-b-multi', turnIndex: 1, rawText: '太复杂了',
+      correctionDetected: true, correctionCue: '太复杂了',
+      referencesAssistantTurnId: atIdB, createdAt: new Date().toISOString(),
+    });
+    trajectory.recordToolCall({
+      sessionId: 'session-b-multi', toolName: 'edit', outcome: 'failure',
+      errorMessage: 'Edit failed', errorType: 'Error', createdAt: new Date().toISOString(),
+    });
+    trajectory.recordToolCall({
+      sessionId: 'session-b-multi', toolName: 'write', outcome: 'failure',
+      errorMessage: 'Write failed too', errorType: 'Error', createdAt: new Date().toISOString(),
+    });
+
+    // Verify session B has more failure signals
+    const extractor = new NocturnalTrajectoryExtractor(trajectory);
+    const snapshotA = extractor.getNocturnalSessionSnapshot('session-a-pain-only');
+    const snapshotB = extractor.getNocturnalSessionSnapshot('session-b-multi');
+
+    expect(snapshotA).not.toBeNull();
+    expect(snapshotB).not.toBeNull();
+
+    // Session B should have more violation signals
+    const densityA = (snapshotA!.stats.failureCount ?? 0) + (snapshotA!.stats.totalPainEvents ?? 0) * 0.5;
+    const densityB = (snapshotB!.stats.failureCount ?? 0) + (snapshotB!.stats.totalPainEvents ?? 0) * 0.5;
+    expect(densityB).toBeGreaterThan(densityA);
+  });
+});
+
+// ─────────────────────────────────────────────────────────
+// Phase 4c: Boundary value test matrix
+// ─────────────────────────────────────────────────────────
+describe('Phase 4c: Boundary value tests', () => {
+  let workspaceDir: string;
+  let trajectory: TrajectoryDatabase;
+
+  beforeEach(() => {
+    workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-e2e-boundary-'));
+    trajectory = new TrajectoryDatabase({ workspaceDir });
+  });
+
+  afterEach(() => {
+    trajectory?.dispose();
+    safeRmDir(workspaceDir);
+  });
+
+  it('session with correction cue is listed as candidate', () => {
+    trajectory.recordSession({ sessionId: 'single-pain', startedAt: new Date().toISOString() });
+    const atIdC = trajectory.recordAssistantTurn({
+      sessionId: 'single-pain', runId: 'run-c', provider: 'local', model: 'main',
+      rawText: 'Agent response', sanitizedText: 'Agent response', usageJson: {}, empathySignalJson: {},
+      createdAt: new Date().toISOString(),
+    });
+    trajectory.recordUserTurn({
+      sessionId: 'single-pain', turnIndex: 1, rawText: '错了',
+      correctionDetected: true, correctionCue: '错了',
+      referencesAssistantTurnId: atIdC, createdAt: new Date().toISOString(),
+    });
+
+    const extractor = new NocturnalTrajectoryExtractor(trajectory);
+    const candidates = extractor.listRecentNocturnalCandidateSessions({ limit: 10, minToolCalls: 0 });
+
+    const painCandidate = candidates.find(c => c.sessionId === 'single-pain');
+    expect(painCandidate).toBeDefined();
+  });
+
+  it('detectViolation returns violated for P_* principles with tool failure', () => {
+    trajectory.recordSession({ sessionId: 'violation-session', startedAt: new Date().toISOString() });
+    trajectory.recordAssistantTurn({
+      sessionId: 'violation-session', runId: 'run-d', provider: 'local', model: 'main',
+      rawText: 'Code', sanitizedText: 'Code', usageJson: {}, empathySignalJson: {},
+      createdAt: new Date().toISOString(),
+    });
+    trajectory.recordToolCall({
+      sessionId: 'violation-session', toolName: 'write', outcome: 'failure',
+      errorMessage: 'Failed', errorType: 'Error', createdAt: new Date().toISOString(),
+    });
+
+    const extractor = new NocturnalTrajectoryExtractor(trajectory);
+    const snapshot = extractor.getNocturnalSessionSnapshot('violation-session');
+    expect(snapshot).not.toBeNull();
+
+    // P_* principles should be violated with any failure
+    const violation = detectViolation('P_001', {
+      sessionId: 'violation-session',
+      toolCalls: snapshot!.toolCalls.map(tc => ({
+        toolName: tc.toolName, outcome: tc.outcome as 'success' | 'failure' | 'blocked',
+        errorMessage: tc.errorMessage ?? undefined,
+      })),
+      painSignals: snapshot!.painEvents.map(pe => ({
+        source: pe.source, score: pe.score, severity: pe.severity as 'mild' | 'moderate' | 'severe' | undefined,
+      })),
+      gateBlocks: [],
+      userCorrections: [],
+      planApprovals: [],
+    });
+
+    expect(violation.violated).toBe(true);
+  });
+});

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,
+    });
+  });
+});