principles-disciple 1.21.0 → 1.23.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.21.0",
+  "version": "1.23.0",
   "skills": [
     "./skills"
   ],
@@ -76,8 +76,8 @@
     }
   },
   "buildFingerprint": {
-    "gitSha": "bce835db37a0",
-    "bundleMd5": "9e44177badb37ac423669fd187bf2667",
-    "builtAt": "2026-04-10T14:01:23.050Z"
+    "gitSha": "ebbaa40d6e3a",
+    "bundleMd5": "7c84860901894f7c049b54028d489ed4",
+    "builtAt": "2026-04-12T15:51:34.724Z"
   }
 }

package/package.json

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

package/scripts/sync-plugin.mjs

@@ -372,6 +372,7 @@ function verifyBundleContents() {
         { name: 'EvolutionWorkerService', reason: 'main plugin service export' },
         { name: 'checkPainFlag',          reason: 'pain flag detection' },
         { name: 'processEvolutionQueue',  reason: 'queue processing' },
+        { name: 'acquireQueueLock',       reason: 'queue lock for pd-reflect and worker' },
     ];
 
     const missing = [];

package/src/commands/nocturnal-rollout.ts

@@ -56,6 +56,11 @@ import {
 import {
   getCheckpoint,
 } from '../core/model-training-registry.js';
+import {
+  runMergeGateAudit,
+  formatMergeGateAuditReport,
+} from '../core/merge-gate-audit.js';
+import { resolvePdPath } from '../core/paths.js';
 
 function isZh(ctx: PluginCommandContext): boolean {
   return String(ctx.config?.language || 'en').startsWith('zh');
@@ -257,6 +262,14 @@ ${result.passes
       return { text };
     }
 
+    // ── Merge-Gate Audit ──────────────────────────────────────────────────
+    if (subcommand === 'audit') {
+      const stateDir = resolvePdPath(workspaceDir, 'STATE_DIR');
+      const report = runMergeGateAudit(workspaceDir, stateDir);
+      const formatted = formatMergeGateAuditReport(report);
+      return { text: formatted };
+    }
+
     // ── Advance Promotion ─────────────────────────────────────────────────
     if (subcommand === 'advance-promotion') {
       const checkpointId = parts[1] || checkpointIdArg;
@@ -267,6 +280,28 @@ ${result.passes
       const profile = parseProfile(profileArg);
       const hasReview = args.includes('--review');
       const noteArg = parts.find((p) => p.startsWith('--note='))?.split('=')[1];
+      const skipAudit = args.includes('--skip-audit');
+
+      // ── Merge-gate auto-gate: block advance-promotion if audit is BLOCK ──
+      if (!skipAudit) {
+        const stateDir = resolvePdPath(workspaceDir, 'STATE_DIR');
+        const auditReport = runMergeGateAudit(workspaceDir, stateDir);
+        if (auditReport.overallStatus === 'block') {
+          return {
+            text: zh
+              ? `❌ Merge-Gate 审计阻止了晋升：发现 ${auditReport.counts.block} 个阻断项
+
+${formatMergeGateAuditReport(auditReport)}
+
+如需强制晋升，请添加 --skip-audit 标志。`
+              : `❌ Merge-Gate audit blocked promotion: ${auditReport.counts.block} blocking issue(s) found
+
+${formatMergeGateAuditReport(auditReport)}
+
+To force promotion, add --skip-audit flag.`,
+          };
+        }
+      }
 
       try {
         const promotion = advancePromotion(workspaceDir, {

package/src/core/nocturnal-arbiter.ts

@@ -623,11 +623,12 @@ export function validateArtifact(
   // Rule 11: Quality threshold gate — reject low-signal artifacts
   // A reflection artifact must show positive cognitive improvement (thinkingModelDelta > 0).
   // planningRatioGain must not show catastrophic regression (< -0.5).
+  // #244: Use strict < so thinkingModelDelta=threshold passes (thin violations allowed at boundary)
   if (
     options.qualityThresholds?.thinkingModelDeltaMin !== undefined &&
     thinkingModelDelta !== undefined &&
     typeof thinkingModelDelta === 'number' &&
-    thinkingModelDelta <= options.qualityThresholds.thinkingModelDeltaMin
+    thinkingModelDelta < options.qualityThresholds.thinkingModelDeltaMin
   ) {
     failures.push({
       reason: `thinkingModelDelta (${thinkingModelDelta}) does not meet minimum quality threshold (${options.qualityThresholds.thinkingModelDeltaMin}) — reflection shows no cognitive improvement`,

package/src/hooks/subagent.ts

@@ -1,6 +1,7 @@
 import type { PluginHookSubagentEndedEvent, PluginHookSubagentContext, PluginLogger, OpenClawPluginApi } from '../openclaw-sdk.js';
 import { buildPainFlag, writePainFlag } from '../core/pain.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
+import { extractAgentIdFromSessionKey } from '../utils/session-key.js';
 // No longer needed — diagnostician runs via HEARTBEAT, not subagent
 import { recordEvolutionSuccess } from '../core/evolution-engine.js';
 import { WorkflowStore } from '../service/subagent-workflow/workflow-store.js';
@@ -81,18 +82,6 @@ function emitSubagentPainEvent(
     }
 }
 
-
-function extractAgentIdFromSessionKey(sessionKey: string | undefined): string | undefined {
-    // sessionKey format: "agent:{agentId}:{type}:{uuid}" or "agent:{agentId}:{uuid}"
-    if (!sessionKey) return undefined;
-    const match = /^agent:([^:]+):/.exec(sessionKey);
-    return match ? match[1] : undefined;
-}
-
-
-
-
-
 type SubagentEndedHookContext = PluginHookSubagentContext & {
     api?: OpenClawPluginApi;
     workspaceDir?: string;

package/src/index.ts

@@ -61,6 +61,7 @@ import { PathResolver, resolveWorkspaceDirFromApi } from './core/path-resolver.j
 import { validateWorkspaceDir } from './core/workspace-dir-validation.js';
 import { resolveRequiredWorkspaceDir, resolveWorkspaceDir, type WorkspaceResolutionContext } from './core/workspace-dir-service.js';
 import { createPrinciplesConsoleRoute } from './http/principles-console-route.js';
+import { extractAgentIdFromSessionKey } from './utils/session-key.js';
 
 // Track initialization to avoid repeated calls
 let workspaceInitialized = false;
@@ -423,11 +424,13 @@ const plugin = {
     registerCommandWithAlias('pd-thinking', 'pdt', getCommandDescription('pd-thinking', language), (ctx: any) => handleThinkingOs(ctx), { acceptsArgs: true });
     registerCommandWithAlias('pd-reflect', 'pdrl', getCommandDescription('pd-reflect', language), (ctx: any) => {
       try {
-        const workspaceDir = resolveCommandWorkspaceDirStrict(api, ctx);
-        return handlePdReflect.handler({ ...ctx, api, workspaceDir } as any);
+        // Resolve agentId from sessionKey (if available), fallback to 'main'
+        const agentId = extractAgentIdFromSessionKey(ctx.sessionKey) ?? 'main';
+        const workspaceDir = resolveRequiredWorkspaceDir(api, { ...ctx, agentId }, { source: 'pd-reflect', fallbackAgentId: 'main' });
+        return handlePdReflect.handler({ ...ctx, api, workspaceDir });
       } catch (err) {
-        api.logger.error(`[PD] Command /pd-reflect failed: ${String(err)}`);
-        return { text: language === 'zh' ? "命令执行失败，请检查日志。" : "Command failed. Check logs." };
+        api.logger.error(`[PD:pd-reflect] Command failed: ${String(err)}`);
+        return { text: language === 'zh' ? '命令执行失败，请查看日志。' : 'Command failed. Check logs.' };
       }
     });
     registerCommandWithAlias('pd-daily', 'pdd', getCommandDescription('pd-daily', language), () => ({

package/src/service/evolution-worker.ts

@@ -1596,6 +1596,7 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
                                 snapshot: snapshotData,
                                 taskId: sleepTask.id,
                                 painContext: sleepTask.recentPainContext,
+                                triggerSource: sleepTask.source,
                             },
                         });
                         sleepTask.resultRef = workflowHandle.workflowId;

package/src/service/nocturnal-runtime.ts

@@ -60,6 +60,20 @@ function isSystemSession(state: SessionState): boolean {
     if (sessionId?.startsWith('boot-')) return true;
     if (sessionId?.startsWith('probe-')) return true;
 
+    // CRITICAL FIX: Legacy sessions from persistence may have missing trigger/sessionKey
+    // If both are missing AND the session is old (inactive > abandoned threshold),
+    // treat as legacy/orphan to avoid blocking idle detection with unknown sessions.
+    // Recent sessions without trigger/sessionKey are likely real user sessions still
+    // being enriched — do NOT classify them as system sessions.
+    const ABANDONED_THRESHOLD_MS = 2 * 60 * 60 * 1000; // 2 hours
+    if (!trigger && !sessionKey) {
+        const inactiveFor = Date.now() - state.lastActivityAt;
+        if (inactiveFor > ABANDONED_THRESHOLD_MS) {
+            return true; // Legacy/orphan session — don't block idle detection
+        }
+        // Recent session without metadata — likely a real user session, let it through
+    }
+
     return false;
 }
 

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

@@ -210,7 +210,7 @@ export class NocturnalWorkflowManager implements WorkflowManager {
 
         // Extract snapshot and principleId from taskInput.metadata (NOC-07: Trinity async path)
         const snapshotValidation = validateNocturnalSnapshotIngress(options.metadata?.snapshot);
-        const snapshot = snapshotValidation.snapshot;
+        const {snapshot} = snapshotValidation;
         const principleId = options.metadata?.principleId as string | undefined;
         // Extract painContext for Selector ranking bias
         const painContext = options.metadata?.painContext as RecentPainContext | undefined;
@@ -254,6 +254,22 @@ export class NocturnalWorkflowManager implements WorkflowManager {
                         },
                         // Pass painContext for Selector ranking bias
                         painContext,
+                        // #244: Only skip preflight idle gate for manual/test triggers.
+                        // Automatic triggers must go through normal idle check.
+                        ...(((options.metadata)?.triggerSource === 'manual' ||
+                            (options.metadata)?.triggerSource === 'test')
+                          ? {
+                              idleCheckOverride: {
+                                  isIdle: true,
+                                  mostRecentActivityAt: Date.now() - 1800000,
+                                  idleForMs: 1800000,
+                                  userActiveSessions: 0,
+                                  abandonedSessionIds: [],
+                                  trajectoryGuardrailConfirmsIdle: true,
+                                  reason: 'manual/test override',
+                              },
+                            }
+                          : {}),
                         // Skip Selector if principleId and snapshot are provided
                         ...(principleId && snapshot ? {
                             principleIdOverride: principleId,

package/src/utils/session-key.ts

@@ -0,0 +1,17 @@
+/**
+ * Session key parsing utilities.
+ *
+ * Session key format: "agent:{agentId}:{type}:{uuid}" or "agent:{agentId}:{uuid}"
+ */
+
+/**
+ * Extract agentId from a sessionKey.
+ * Returns `undefined` if sessionKey is missing, malformed, or has whitespace-only agentId.
+ */
+export function extractAgentIdFromSessionKey(sessionKey: string | undefined): string | undefined {
+    if (!sessionKey) return undefined;
+    const match = /^agent:([^:]+):/.exec(sessionKey);
+    if (!match) return undefined;
+    const agentId = match[1].trim();
+    return agentId || undefined;
+}

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

@@ -491,4 +491,61 @@ describe('Nocturnal Arbiter', () => {
       expect(result.artifact?.sourceSnapshotRef).toBe('');
     });
   });
+
+  // -------------------------------------------------------------------------
+  // Tests: quality threshold gates (Rule 10/11)
+  // -------------------------------------------------------------------------
+
+  describe('quality threshold gates', () => {
+    const defaultThresholds = { thinkingModelDeltaMin: 0.05, planningRatioGainMin: -0.5 };
+
+    it('rejects when thinkingModelDelta is below threshold', () => {
+      const artifact = makeValidArtifact({ thinkingModelDelta: 0.03 });
+      const result = validateArtifact(artifact, { qualityThresholds: defaultThresholds });
+      expect(result.passed).toBe(false);
+      expect(result.failures).toHaveLength(1);
+      expect(result.failures[0].field).toBe('thinkingModelDelta');
+    });
+
+    it('passes when thinkingModelDelta equals threshold exactly (boundary value)', () => {
+      const artifact = makeValidArtifact({ thinkingModelDelta: 0.05 });
+      const result = validateArtifact(artifact, { qualityThresholds: defaultThresholds });
+      expect(result.passed).toBe(true);
+    });
+
+    it('passes when thinkingModelDelta exceeds threshold', () => {
+      const artifact = makeValidArtifact({ thinkingModelDelta: 0.15 });
+      const result = validateArtifact(artifact, { qualityThresholds: defaultThresholds });
+      expect(result.passed).toBe(true);
+    });
+
+    it('passes when thinkingModelDelta is absent (optional field)', () => {
+      const artifact = makeValidArtifact();
+      delete artifact.thinkingModelDelta;
+      const result = validateArtifact(artifact, { qualityThresholds: defaultThresholds });
+      expect(result.passed).toBe(true);
+    });
+
+    it('rejects when planningRatioGain is below threshold', () => {
+      const artifact = makeValidArtifact({ planningRatioGain: -0.6 });
+      const result = validateArtifact(artifact, { qualityThresholds: defaultThresholds });
+      expect(result.passed).toBe(false);
+      expect(result.failures.some(f => f.field === 'planningRatioGain')).toBe(true);
+    });
+
+    it('passes when planningRatioGain equals threshold exactly (boundary value)', () => {
+      const artifact = makeValidArtifact({ planningRatioGain: -0.5 });
+      const result = validateArtifact(artifact, { qualityThresholds: defaultThresholds });
+      expect(result.passed).toBe(true);
+    });
+
+    it('rejects both quality thresholds simultaneously', () => {
+      const artifact = makeValidArtifact({ thinkingModelDelta: 0.01, planningRatioGain: -0.8 });
+      const result = validateArtifact(artifact, { qualityThresholds: defaultThresholds });
+      expect(result.passed).toBe(false);
+      expect(result.failures.length).toBeGreaterThanOrEqual(2);
+      expect(result.failures.some(f => f.field === 'thinkingModelDelta')).toBe(true);
+      expect(result.failures.some(f => f.field === 'planningRatioGain')).toBe(true);
+    });
+  });
 });

package/tests/service/evolution-worker.nocturnal.test.ts

@@ -35,18 +35,22 @@ vi.mock('../../src/service/subagent-workflow/nocturnal-workflow-manager.js', ()
 
 const { mockGetNocturnalSessionSnapshot, mockListRecentNocturnalCandidateSessions } = vi.hoisted(() => ({
   mockGetNocturnalSessionSnapshot: vi.fn(),
-  mockListRecentNocturnalCandidateSessions: vi.fn(() => []),
+  mockListRecentNocturnalCandidateSessions: vi.fn(() => [] as Array<{ sessionId: string; startedAt: string; failureCount: number; painEventCount: number; gateBlockCount: number }>),
 }));
+
+// Create a shared mock extractor instance so spy calls are tracked correctly
+const mockExtractorInstance = {
+  getNocturnalSessionSnapshot: mockGetNocturnalSessionSnapshot,
+  listRecentNocturnalCandidateSessions: mockListRecentNocturnalCandidateSessions,
+};
+
 vi.mock('../../src/core/nocturnal-trajectory-extractor.js', async () => {
   const actual = await vi.importActual<typeof import('../../src/core/nocturnal-trajectory-extractor.js')>(
     '../../src/core/nocturnal-trajectory-extractor.js'
   );
   return {
     ...actual,
-    createNocturnalTrajectoryExtractor: vi.fn(() => ({
-      getNocturnalSessionSnapshot: mockGetNocturnalSessionSnapshot,
-      listRecentNocturnalCandidateSessions: mockListRecentNocturnalCandidateSessions,
-    })),
+    createNocturnalTrajectoryExtractor: vi.fn(() => mockExtractorInstance),
   };
 });
 
@@ -55,6 +59,17 @@ import { WorkspaceContext } from '../../src/core/workspace-context.js';
 import { handlePdReflect } from '../../src/commands/pd-reflect.js';
 import { safeRmDir } from '../test-utils.js';
 
+// Helper to create a mock API for E2E tests
+function createMockApi() {
+  return {
+    logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },
+    runtime: { agent: { runEmbeddedPiAgent: vi.fn() } },
+  } as any;
+}
+
+// Helper config for fast poll cycle
+const fastPollConfig = { get: (k: string) => k === 'intervals.worker_poll_ms' ? 100 : undefined };
+
 function readQueue(stateDir: string) {
   return JSON.parse(fs.readFileSync(path.join(stateDir, 'evolution_queue.json'), 'utf8'));
 }
@@ -93,11 +108,11 @@ session_id: explicit-session-from-pain
 
     try {
       const context = readRecentPainContext(wctx);
-      
+
       // Verify the session_id was extracted from the pain flag file
       expect(context.mostRecent).toBeDefined();
-      expect(context.mostRecent.sessionId).toBe('explicit-session-from-pain');
-      expect(context.mostRecent.score).toBe(80);
+      expect(context.mostRecent!.sessionId).toBe('explicit-session-from-pain');
+      expect(context.mostRecent!.score).toBe(80);
       expect(context.recentPainCount).toBe(1);
     } finally {
       safeRmDir(workspaceDir);
@@ -155,9 +170,9 @@ session_id: pain-session-abc
 
     // Contract: session_id must be extracted from the pain flag
     expect(painContext.mostRecent).toBeDefined();
-    expect(painContext.mostRecent.sessionId).toBe('pain-session-abc');
-    expect(painContext.mostRecent.score).toBe(70);
-    expect(painContext.mostRecent.source).toBe('tool_failure');
+    expect(painContext.mostRecent!.sessionId).toBe('pain-session-abc');
+    expect(painContext.mostRecent!.score).toBe(70);
+    expect(painContext.mostRecent!.source).toBe('tool_failure');
 
     // Now simulate what the worker does: attach this context to a queued task
     const simulatedTask = {
@@ -167,7 +182,7 @@ session_id: pain-session-abc
     };
 
     // Verify the contract holds end-to-end
-    expect(simulatedTask.recentPainContext.mostRecent.sessionId).toBe('pain-session-abc');
+    expect(simulatedTask.recentPainContext.mostRecent!.sessionId).toBe('pain-session-abc');
   });
 
   it('e2e: /pd-reflect command writes to workspace/.state, never to HOME/.state', async () => {
@@ -214,4 +229,359 @@ session_id: pain-session-abc
       safeRmDir(workspaceDir);
     }
   });
+
+  // === Nocturnal E2E Pipeline Tests (from PR #243) ===
+
+  it('does not start a nocturnal workflow when only an empty fallback snapshot is available', async () => {
+    const workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-nocturnal-empty-'));
+    const stateDir = path.join(workspaceDir, '.state');
+    fs.mkdirSync(path.join(stateDir, 'sessions'), { recursive: true });
+    fs.mkdirSync(path.join(stateDir, 'logs'), { recursive: true });
+
+    mockGetNocturnalSessionSnapshot.mockReturnValue(null);
+
+    fs.writeFileSync(
+      path.join(stateDir, 'evolution_queue.json'),
+      JSON.stringify([
+        {
+          id: 'sleep-empty',
+          taskKind: 'sleep_reflection',
+          priority: 'medium',
+          score: 50,
+          source: 'nocturnal',
+          reason: 'Sleep reflection',
+          timestamp: '2026-04-10T00:00:00.000Z',
+          enqueued_at: '2026-04-10T00:00:00.000Z',
+          status: 'pending',
+          retryCount: 0,
+          maxRetries: 1,
+          recentPainContext: {
+            mostRecent: null,
+            recentPainCount: 0,
+            recentMaxPainScore: 0,
+          },
+        },
+      ], null, 2),
+      'utf8'
+    );
+
+    const mockApi = createMockApi();
+    EvolutionWorkerService.api = mockApi;
+
+    try {
+      EvolutionWorkerService.start({
+        workspaceDir,
+        stateDir,
+        logger: mockApi.logger,
+        config: fastPollConfig,
+        api: mockApi,
+      } as any);
+
+      await vi.advanceTimersByTimeAsync(6000);
+
+      const queue = readQueue(stateDir);
+      expect(queue[0].status).toBe('failed');
+      expect(queue[0].lastError).toContain('invalid_snapshot_ingress');
+      expect(queue[0].lastError).toContain('fallback snapshot must contain at least one pain signal');
+      expect(queue[0].resultRef).toBeFalsy();
+      expect(mockStartWorkflow).not.toHaveBeenCalled();
+    } finally {
+      EvolutionWorkerService.stop!({ workspaceDir, stateDir, logger: console } as any);
+      safeRmDir(workspaceDir);
+    }
+  });
+
+  it('uses stub_fallback for expected gateway-only background unavailability', async () => {
+    const workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-nocturnal-gateway-'));
+    const stateDir = path.join(workspaceDir, '.state');
+    fs.mkdirSync(path.join(stateDir, 'sessions'), { recursive: true });
+    fs.mkdirSync(path.join(stateDir, 'logs'), { recursive: true });
+
+    mockGetNocturnalSessionSnapshot.mockReturnValue({
+      sessionId: 'sleep-gateway',
+      startedAt: '2026-04-10T00:00:00.000Z',
+      updatedAt: '2026-04-10T00:01:00.000Z',
+      assistantTurns: [],
+      userTurns: [],
+      toolCalls: [],
+      painEvents: [],
+      gateBlocks: [],
+      stats: { totalAssistantTurns: 1, totalToolCalls: 1, totalPainEvents: 0, totalGateBlocks: 0, failureCount: 0 },
+    });
+    mockStartWorkflow.mockResolvedValue({ workflowId: 'wf-1', childSessionKey: 'child-1', state: 'active' });
+    mockGetWorkflowDebugSummary.mockResolvedValue({
+      state: 'terminal_error',
+      metadata: {},
+      recentEvents: [{ reason: 'Error: Plugin runtime subagent methods are only available during a gateway request.', payload: {} }],
+    });
+
+    fs.writeFileSync(
+      path.join(stateDir, 'evolution_queue.json'),
+      JSON.stringify([
+        {
+          id: 'sleep-gateway',
+          taskKind: 'sleep_reflection',
+          priority: 'medium',
+          score: 50,
+          source: 'nocturnal',
+          reason: 'Sleep reflection',
+          timestamp: '2026-04-10T00:00:00.000Z',
+          enqueued_at: '2026-04-10T00:00:00.000Z',
+          status: 'pending',
+          retryCount: 0,
+          maxRetries: 1,
+          recentPainContext: {
+            mostRecent: { source: 'test', score: 50, reason: 'test', timestamp: '2026-04-10T00:00:00.000Z', sessionId: 'sleep-gateway' },
+            recentPainCount: 1,
+            recentMaxPainScore: 50,
+          },
+        },
+      ], null, 2),
+      'utf8'
+    );
+
+    const mockApi = createMockApi();
+    EvolutionWorkerService.api = mockApi;
+
+    try {
+      EvolutionWorkerService.start({
+        workspaceDir,
+        stateDir,
+        logger: mockApi.logger,
+        config: fastPollConfig,
+        api: mockApi,
+      } as any);
+
+      await vi.advanceTimersByTimeAsync(6000);
+
+      const queue = readQueue(stateDir);
+      expect(queue[0].status).toBe('completed');
+      expect(queue[0].resolution).toBe('stub_fallback');
+    } finally {
+      EvolutionWorkerService.stop!({ workspaceDir, stateDir, logger: console } as any);
+      safeRmDir(workspaceDir);
+    }
+  });
+
+  it('uses stub_fallback for expected subagent runtime unavailability', async () => {
+    const workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-nocturnal-subagent-'));
+    const stateDir = path.join(workspaceDir, '.state');
+    fs.mkdirSync(path.join(stateDir, 'sessions'), { recursive: true });
+    fs.mkdirSync(path.join(stateDir, 'logs'), { recursive: true });
+
+    mockGetNocturnalSessionSnapshot.mockReturnValue({
+      sessionId: 'sleep-subagent',
+      startedAt: '2026-04-10T00:00:00.000Z',
+      updatedAt: '2026-04-10T00:01:00.000Z',
+      assistantTurns: [],
+      userTurns: [],
+      toolCalls: [],
+      painEvents: [],
+      gateBlocks: [],
+      stats: { totalAssistantTurns: 1, totalToolCalls: 1, totalPainEvents: 0, totalGateBlocks: 0, failureCount: 0 },
+    });
+    mockStartWorkflow.mockRejectedValue(new Error('NocturnalWorkflowManager: subagent runtime unavailable'));
+
+    fs.writeFileSync(
+      path.join(stateDir, 'evolution_queue.json'),
+      JSON.stringify([
+        {
+          id: 'sleep-subagent',
+          taskKind: 'sleep_reflection',
+          priority: 'medium',
+          score: 50,
+          source: 'nocturnal',
+          reason: 'Sleep reflection',
+          timestamp: '2026-04-10T00:00:00.000Z',
+          enqueued_at: '2026-04-10T00:00:00.000Z',
+          status: 'pending',
+          retryCount: 0,
+          maxRetries: 1,
+          recentPainContext: {
+            mostRecent: { source: 'test', score: 50, reason: 'test', timestamp: '2026-04-10T00:00:00.000Z', sessionId: 'sleep-subagent' },
+            recentPainCount: 1,
+            recentMaxPainScore: 50,
+          },
+        },
+      ], null, 2),
+      'utf8'
+    );
+
+    const mockApi = createMockApi();
+    EvolutionWorkerService.api = mockApi;
+
+    try {
+      EvolutionWorkerService.start({
+        workspaceDir,
+        stateDir,
+        logger: mockApi.logger,
+        config: fastPollConfig,
+        api: mockApi,
+      } as any);
+
+      await vi.advanceTimersByTimeAsync(6000);
+
+      const queue = readQueue(stateDir);
+      expect(queue[0].status).toBe('completed');
+      expect(queue[0].resolution).toBe('stub_fallback');
+    } finally {
+      EvolutionWorkerService.stop!({ workspaceDir, stateDir, logger: console } as any);
+      safeRmDir(workspaceDir);
+    }
+  });
+
+  it('prioritizes pain signal session ID for snapshot extraction', async () => {
+    const workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-nocturnal-pain-session-'));
+    const stateDir = path.join(workspaceDir, '.state');
+    fs.mkdirSync(path.join(stateDir, 'sessions'), { recursive: true });
+    fs.mkdirSync(path.join(stateDir, 'logs'), { recursive: true });
+
+    const painSessionId = 'pain-signal-session-123';
+
+    mockGetNocturnalSessionSnapshot.mockImplementation((sessionId: string) => {
+      if (sessionId === painSessionId) {
+        return {
+          sessionId: painSessionId,
+          startedAt: '2026-04-09T23:00:00.000Z',
+          updatedAt: '2026-04-09T23:01:00.000Z',
+          assistantTurns: [],
+          userTurns: [],
+          toolCalls: [],
+          painEvents: [{ source: 'tool_failure', score: 70, severity: null, reason: 'test', createdAt: '2026-04-09T23:00:00.000Z' }],
+          gateBlocks: [],
+          stats: { totalAssistantTurns: 1, totalToolCalls: 1, failureCount: 1, totalPainEvents: 1, totalGateBlocks: 0 },
+        };
+      }
+      return null;
+    });
+    mockStartWorkflow.mockResolvedValue({ workflowId: 'wf-pain', childSessionKey: 'child-pain', state: 'active' });
+
+    fs.writeFileSync(
+      path.join(stateDir, 'evolution_queue.json'),
+      JSON.stringify([
+        {
+          id: 'sleep-pain-priority',
+          taskKind: 'sleep_reflection',
+          priority: 'medium',
+          score: 50,
+          source: 'nocturnal',
+          reason: 'Sleep reflection',
+          timestamp: '2026-04-10T00:00:00.000Z',
+          enqueued_at: '2026-04-10T00:00:00.000Z',
+          status: 'pending',
+          retryCount: 0,
+          maxRetries: 1,
+          recentPainContext: {
+            mostRecent: { source: 'tool_failure', score: 70, reason: 'test', timestamp: '2026-04-10T00:00:00.000Z', sessionId: painSessionId },
+            recentPainCount: 1,
+            recentMaxPainScore: 70,
+          },
+        },
+      ], null, 2),
+      'utf8'
+    );
+
+    const mockApi = createMockApi();
+    EvolutionWorkerService.api = mockApi;
+
+    try {
+      EvolutionWorkerService.start({
+        workspaceDir,
+        stateDir,
+        logger: mockApi.logger,
+        config: fastPollConfig,
+        api: mockApi,
+      } as any);
+
+      await vi.advanceTimersByTimeAsync(6000);
+
+      expect(mockStartWorkflow).toHaveBeenCalledTimes(1);
+      const metadata = mockStartWorkflow.mock.calls[0][1].metadata;
+      expect(metadata.snapshot.sessionId).toBe(painSessionId);
+    } finally {
+      EvolutionWorkerService.stop!({ workspaceDir, stateDir, logger: console } as any);
+      safeRmDir(workspaceDir);
+    }
+  });
+
+  it('e2e: bounded session selection — never picks a session newer than the triggering task', async () => {
+    const workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-nocturnal-e2e-bounded-'));
+    const stateDir = path.join(workspaceDir, '.state');
+    fs.mkdirSync(path.join(stateDir, 'sessions'), { recursive: true });
+    fs.mkdirSync(path.join(stateDir, 'logs'), { recursive: true });
+
+    const taskTimestamp = '2026-04-10T00:00:00.000Z';
+    const validSessionTimestamp = '2026-04-09T23:00:00.000Z';
+    const invalidSessionTimestamp = '2026-04-10T01:00:00.000Z';
+
+    mockGetNocturnalSessionSnapshot.mockImplementation((sessionId: string) => {
+      if (sessionId === 'valid-session') {
+        return {
+          sessionId: 'valid-session',
+          startedAt: validSessionTimestamp,
+          updatedAt: validSessionTimestamp,
+          assistantTurns: [],
+          userTurns: [],
+          toolCalls: [],
+          painEvents: [{ source: 'tool_failure', score: 50, severity: null, reason: 'test', createdAt: validSessionTimestamp }],
+          gateBlocks: [],
+          stats: { totalAssistantTurns: 1, totalToolCalls: 1, failureCount: 1, totalPainEvents: 1, totalGateBlocks: 0 },
+        };
+      }
+      return null;
+    });
+    mockListRecentNocturnalCandidateSessions.mockReturnValue([
+      { sessionId: 'valid-session', startedAt: validSessionTimestamp, failureCount: 1, painEventCount: 1, gateBlockCount: 0 },
+      { sessionId: 'invalid-session', startedAt: invalidSessionTimestamp, failureCount: 1, painEventCount: 0, gateBlockCount: 0 },
+    ]);
+    mockStartWorkflow.mockResolvedValue({ workflowId: 'wf-bounded', childSessionKey: 'child-bounded', state: 'active' });
+
+    fs.writeFileSync(
+      path.join(stateDir, 'evolution_queue.json'),
+      JSON.stringify([
+        {
+          id: 'sleep-e2e-bounded',
+          taskKind: 'sleep_reflection',
+          priority: 'medium',
+          score: 50,
+          source: 'nocturnal',
+          reason: 'Sleep reflection',
+          timestamp: taskTimestamp,
+          enqueued_at: taskTimestamp,
+          status: 'pending',
+          retryCount: 0,
+          maxRetries: 1,
+          recentPainContext: {
+            mostRecent: { source: 'test', score: 50, reason: 'test', timestamp: taskTimestamp, sessionId: 'pain-session' },
+            recentPainCount: 1,
+            recentMaxPainScore: 50,
+          },
+        },
+      ], null, 2),
+      'utf8'
+    );
+
+    const mockApi = createMockApi();
+    EvolutionWorkerService.api = mockApi;
+
+    try {
+      EvolutionWorkerService.start({
+        workspaceDir,
+        stateDir,
+        logger: mockApi.logger,
+        config: fastPollConfig,
+        api: mockApi,
+      } as any);
+
+      await vi.advanceTimersByTimeAsync(6000);
+
+      expect(mockStartWorkflow).toHaveBeenCalledTimes(1);
+      const metadata = mockStartWorkflow.mock.calls[0][1].metadata;
+      expect(metadata.snapshot.sessionId).toBe('valid-session');
+      expect(new Date(metadata.snapshot.startedAt).getTime()).toBeLessThanOrEqual(new Date(taskTimestamp).getTime());
+    } finally {
+      EvolutionWorkerService.stop!({ workspaceDir, stateDir, logger: console } as any);
+      safeRmDir(workspaceDir);
+    }
+  });
 });