principles-disciple 1.14.0 → 1.15.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.14.0",
+  "version": "1.15.0",
   "skills": [
     "./skills"
   ],

package/package.json

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

package/src/core/principle-tree-migration.ts

@@ -0,0 +1,196 @@
+/**
+ * Principle Tree Migration — Migrates trainingStore to tree.principles
+ *
+ * This migration handles the Phase 11 gap: existing principles in trainingStore
+ * were never written to tree.principles, blocking the Rule/Implementation layer.
+ *
+ * Usage:
+ *   - Called automatically by migratePrincipleTree() during plugin initialization
+ *   - Or run manually: node scripts/migrate-principle-tree.mjs <workspace-dir>
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import {
+  loadLedger,
+  saveLedger,
+  type LedgerPrinciple,
+} from './principle-tree-ledger.js';
+import type { LegacyPrincipleTrainingState } from './principle-tree-ledger.js';
+import { SystemLogger } from './system-logger.js';
+
+export interface PrincipleTreeMigrationResult {
+  migratedCount: number;
+  skippedCount: number;
+  errorCount: number;
+  details: Array<{
+    principleId: string;
+    status: 'migrated' | 'skipped' | 'error';
+    reason?: string;
+  }>;
+}
+
+/**
+ * Check if migration is needed by comparing trainingStore and tree.principles
+ */
+export function needsMigration(stateDir: string): boolean {
+  const ledger = loadLedger(stateDir);
+  return Object.keys(ledger.trainingStore).some((principleId) => !ledger.tree.principles[principleId]);
+}
+
+/**
+ * Create a minimal LedgerPrinciple from LegacyPrincipleTrainingState
+ */
+function trainingStateToTreePrinciple(
+  principleId: string,
+  state: LegacyPrincipleTrainingState,
+  now: string
+): LedgerPrinciple {
+  return {
+    id: principleId,
+    version: 1,
+    text: `Principle ${principleId}`, // Minimal text, will be enriched from PRINCIPLES.md if available
+    triggerPattern: '', // Unknown from legacy data
+    action: '', // Unknown from legacy data
+    status: mapInternalizationStatusToPrincipleStatus(state.internalizationStatus),
+    priority: 'P1', // Default priority
+    scope: 'general',
+    evaluability: state.evaluability,
+    valueScore: 0,
+    adherenceRate: state.complianceRate * 100, // Convert 0-1 to 0-100
+    painPreventedCount: 0,
+    derivedFromPainIds: [],
+    ruleIds: [],
+    conflictsWithPrincipleIds: [],
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+/**
+ * Map internalization status to principle status
+ */
+function mapInternalizationStatusToPrincipleStatus(
+  status: LegacyPrincipleTrainingState['internalizationStatus']
+): 'candidate' | 'active' | 'deprecated' {
+  switch (status) {
+    case 'internalized':
+    case 'deployed_pending_eval':
+      return 'active';
+    case 'regressed':
+    case 'needs_training':
+      return 'candidate';
+    case 'prompt_only':
+    case 'in_training':
+      return 'candidate';
+    default:
+      return 'candidate';
+  }
+}
+
+/**
+ * Migrate trainingStore principles to tree.principles
+ *
+ * This function is idempotent: it only migrates principles that don't exist
+ * in tree.principles yet.
+ */
+export function migratePrincipleTree(
+  stateDir: string,
+  workspaceDir?: string
+): PrincipleTreeMigrationResult {
+  const result: PrincipleTreeMigrationResult = {
+    migratedCount: 0,
+    skippedCount: 0,
+    errorCount: 0,
+    details: [],
+  };
+
+  try {
+    const ledger = loadLedger(stateDir);
+    const now = new Date().toISOString();
+
+    for (const [principleId, state] of Object.entries(ledger.trainingStore)) {
+      // Skip if already exists in tree.principles
+      if (ledger.tree.principles[principleId]) {
+        result.skippedCount++;
+        result.details.push({
+          principleId,
+          status: 'skipped',
+          reason: 'Already exists in tree.principles',
+        });
+        continue;
+      }
+
+      try {
+        const treePrinciple = trainingStateToTreePrinciple(principleId, state, now);
+        const nextLedger = loadLedger(stateDir);
+        if (!nextLedger.tree.principles[principleId]) {
+          nextLedger.tree.principles[principleId] = treePrinciple;
+          nextLedger.tree.lastUpdated = now;
+          saveLedger(stateDir, nextLedger);
+        }
+
+        result.migratedCount++;
+        result.details.push({
+          principleId,
+          status: 'migrated',
+        });
+
+        if (workspaceDir) {
+          SystemLogger.log(
+            workspaceDir,
+            'PRINCIPLE_TREE_MIGRATED',
+            `Migrated ${principleId} from trainingStore to tree.principles`
+          );
+        }
+      } catch (err) {
+        result.errorCount++;
+        result.details.push({
+          principleId,
+          status: 'error',
+          reason: String(err),
+        });
+
+        if (workspaceDir) {
+          SystemLogger.log(
+            workspaceDir,
+            'PRINCIPLE_TREE_MIGRATION_ERROR',
+            `Failed to migrate ${principleId}: ${String(err)}`
+          );
+        }
+      }
+    }
+
+    if (workspaceDir && result.migratedCount > 0) {
+      SystemLogger.log(
+        workspaceDir,
+        'PRINCIPLE_TREE_MIGRATION_COMPLETE',
+        `Migrated ${result.migratedCount} principles to tree.principles (${result.skippedCount} skipped, ${result.errorCount} errors)`
+      );
+    }
+  } catch (err) {
+    if (workspaceDir) {
+      SystemLogger.log(
+        workspaceDir,
+        'PRINCIPLE_TREE_MIGRATION_FAILED',
+        `Migration failed: ${String(err)}`
+      );
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Run migration if needed (called during plugin initialization)
+ */
+export function runMigrationIfNeeded(
+  stateDir: string,
+  workspaceDir?: string
+): PrincipleTreeMigrationResult | null {
+  if (!needsMigration(stateDir)) {
+    return null;
+  }
+
+  return migratePrincipleTree(stateDir, workspaceDir);
+}

package/src/service/evolution-worker.ts

@@ -188,6 +188,30 @@ export interface RecentPainContext {
   recentMaxPainScore: number;
 }
 
+function hasUsableNocturnalSnapshot(snapshotData: Record<string, unknown> | undefined): boolean {
+    if (!snapshotData || typeof snapshotData.sessionId !== 'string' || snapshotData.sessionId.length === 0) {
+        return false;
+    }
+
+    if (snapshotData._dataSource !== 'pain_context_fallback') {
+        return true;
+    }
+
+    const stats = (snapshotData.stats && typeof snapshotData.stats === 'object')
+        ? snapshotData.stats as Record<string, number | null | undefined>
+        : undefined;
+    const recentPain = Array.isArray(snapshotData.recentPain) ? snapshotData.recentPain.length : 0;
+    const hasNonZeroStats = !!stats && [
+        'totalAssistantTurns',
+        'totalToolCalls',
+        'failureCount',
+        'totalPainEvents',
+        'totalGateBlocks',
+    ].some((key) => Number(stats[key] ?? 0) > 0);
+
+    return hasNonZeroStats || recentPain > 0;
+}
+
 export interface EvolutionQueueItem {
     // Core identity
     id: string;
@@ -1367,42 +1391,16 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
                         logger?.info?.(`[PD:EvolutionWorker] Processing sleep_reflection task ${sleepTask.id}`);
                     }
 
-                    // NOC-14: Use NocturnalWorkflowManager for sleep_reflection tasks
-                    // Lazy-create manager (needs runtimeAdapter from api)
-                    // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned in if block, else block continues
-                    let nocturnalManager: NocturnalWorkflowManager | undefined;
-                    if (api) {
-                        nocturnalManager = new NocturnalWorkflowManager({
-                            workspaceDir: wctx.workspaceDir,
-                            stateDir: wctx.stateDir,
-                            logger: api.logger,
-                            runtimeAdapter: new OpenClawTrinityRuntimeAdapter(api),
-                        });
-                    } else {
-                        // Cannot create manager without api (runtimeAdapter required)
-                        sleepTask.status = 'failed';
-                        sleepTask.completed_at = new Date().toISOString();
-                        sleepTask.resolution = 'failed_max_retries';
-                        sleepTask.lastError = 'No API available to create NocturnalWorkflowManager';
-                        sleepTask.retryCount = (sleepTask.retryCount ?? 0) + 1;
-                        logger?.warn?.(`[PD:EvolutionWorker] sleep_reflection task ${sleepTask.id} skipped: no API`);
-                        continue;
-                    }
-
-                    // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned in both if/else branches
-                    let workflowId: string;
+                    let workflowId: string | undefined;
+                    // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned when runtime API is available
+                    let nocturnalManager: NocturnalWorkflowManager;
+                    // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned only for newly started workflows
+                    let snapshotData: Record<string, unknown> | undefined;
 
                     if (isPollingTask) {
-                        // Poll-only path: skip workflow start, use existing workflowId
-                        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- Reason: isPollingTask flag is only set when resultRef is expected to be present
+                        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- Reason: polling path requires existing resultRef
                         workflowId = sleepTask.resultRef!;
                     } else {
-                        // Start workflow via NocturnalWorkflowManager instead of direct executeNocturnalReflectionAsync
-                        // Pass taskId in metadata for correlation
-
-                        // #181: Build a proper snapshot from trajectory.db instead of hardcoded zeros
-                        // eslint-disable-next-line @typescript-eslint/init-declarations -- undefined is valid zero value, assigned conditionally in if/fallback blocks
-                        let snapshotData: Record<string, unknown> | undefined;
                         if (sleepTask.recentPainContext) {
                             try {
                                 const extractor = createNocturnalTrajectoryExtractor(wctx.workspaceDir);
@@ -1412,16 +1410,14 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
                                         sessionId: fullSnapshot.sessionId,
                                         sessionStart: fullSnapshot.startedAt,
                                         stats: fullSnapshot.stats,
-                                        recentPain: fullSnapshot.painEvents.slice(-5), // last 5
+                                        recentPain: fullSnapshot.painEvents.slice(-5),
                                     };
                                 }
                             } catch (snapErr) {
                                 logger?.warn?.(`[PD:EvolutionWorker] Failed to build trajectory snapshot for ${sleepTask.id}: ${String(snapErr)}`);
                             }
                         }
-                        // Fallback: use pain context only if trajectory extractor failed
                         if (!snapshotData && sleepTask.recentPainContext) {
-                            // #200: Log fallback usage to make data gaps visible
                             logger?.warn?.(`[PD:EvolutionWorker] Using pain-context fallback for ${sleepTask.id}: trajectory stats unavailable (stats will be partial)`);
                             snapshotData = {
                                 sessionId: sleepTask.id,
@@ -1434,31 +1430,63 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
                                     totalGateBlocks: 0,
                                 },
                                 recentPain: sleepTask.recentPainContext.mostRecent ? [sleepTask.recentPainContext.mostRecent] : [],
-                                // #200: Mark data source so downstream can handle appropriately
                                 _dataSource: 'pain_context_fallback',
                             };
                         }
 
+                        if (!hasUsableNocturnalSnapshot(snapshotData)) {
+                            sleepTask.status = 'failed';
+                            sleepTask.completed_at = new Date().toISOString();
+                            sleepTask.resolution = 'failed_max_retries';
+                            sleepTask.lastError = 'sleep_reflection failed: missing_usable_snapshot (skipReason: empty_fallback_snapshot)';
+                            sleepTask.retryCount = (sleepTask.retryCount ?? 0) + 1;
+                            logger?.warn?.(`[PD:EvolutionWorker] sleep_reflection task ${sleepTask.id} rejected: missing usable snapshot`);
+                            continue;
+                        }
+                    }
+
+                    if (!api) {
+                        sleepTask.status = 'failed';
+                        sleepTask.completed_at = new Date().toISOString();
+                        sleepTask.resolution = 'failed_max_retries';
+                        sleepTask.lastError = 'No API available to create NocturnalWorkflowManager';
+                        sleepTask.retryCount = (sleepTask.retryCount ?? 0) + 1;
+                        logger?.warn?.(`[PD:EvolutionWorker] sleep_reflection task ${sleepTask.id} skipped: no API`);
+                        continue;
+                    }
+
+                    nocturnalManager = new NocturnalWorkflowManager({
+                        workspaceDir: wctx.workspaceDir,
+                        stateDir: wctx.stateDir,
+                        logger: api.logger,
+                        runtimeAdapter: new OpenClawTrinityRuntimeAdapter(api),
+                    });
+
+                    if (!isPollingTask) {
                         const workflowHandle = await nocturnalManager.startWorkflow(nocturnalWorkflowSpec, {
                             parentSessionId: `sleep_reflection:${sleepTask.id}`,
                             workspaceDir: wctx.workspaceDir,
                             taskInput: {},
                             metadata: {
                                 snapshot: snapshotData,
-                                // #205: Remove hardcoded 'default' - let NocturnalTargetSelector choose
-                                // via executeNocturnalReflectionAsync when no principleId is provided
-                                taskId: sleepTask.id,  // NOC-14: correlation ID for evolution worker
-                                // Pass painContext to Selector for principle ranking bias
+                                taskId: sleepTask.id,
                                 painContext: sleepTask.recentPainContext,
                             },
                         });
-
-                        // Store workflowId on task for polling on subsequent cycles
                         sleepTask.resultRef = workflowHandle.workflowId;
-                        // eslint-disable-next-line @typescript-eslint/prefer-destructuring -- Reason: workflowId is reassignable outer let - destructuring would shadow
                         workflowId = workflowHandle.workflowId;
                     }
 
+                    if (!workflowId) {
+                        sleepTask.status = 'failed';
+                        sleepTask.completed_at = new Date().toISOString();
+                        sleepTask.resolution = 'failed_max_retries';
+                        sleepTask.lastError = 'sleep_reflection failed: missing_workflow_id';
+                        sleepTask.retryCount = (sleepTask.retryCount ?? 0) + 1;
+                        logger?.warn?.(`[PD:EvolutionWorker] sleep_reflection task ${sleepTask.id} missing workflow id after startup`);
+                        continue;
+                    }
+
                     // Workflow is running asynchronously. Check if it completed in this cycle
                     // by polling getWorkflowDebugSummary.
                     const summary = await nocturnalManager.getWorkflowDebugSummary(workflowId);
@@ -1490,16 +1518,12 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
                             sleepTask.lastError = detailedError;
                             sleepTask.retryCount = (sleepTask.retryCount ?? 0) + 1;
 
+                            sleepTask.status = 'failed';
+                            sleepTask.completed_at = new Date().toISOString();
+                            sleepTask.resolution = 'failed_max_retries';
                             if (isExpectedSubagentError(errorReason)) {
-                                // #202: Expected subagent unavailability — use stub fallback
-                                sleepTask.status = 'completed';
-                                sleepTask.completed_at = new Date().toISOString();
-                                sleepTask.resolution = 'stub_fallback';
-                                logger?.info?.(`[PD:EvolutionWorker] sleep_reflection task ${sleepTask.id} workflow completed with stub fallback (expected subagent error: ${errorReason})`);
+                                logger?.warn?.(`[PD:EvolutionWorker] sleep_reflection task ${sleepTask.id} background runtime unavailable: ${errorReason}`);
                             } else {
-                                sleepTask.status = 'failed';
-                                sleepTask.completed_at = new Date().toISOString();
-                                sleepTask.resolution = 'failed_max_retries';
                                 logger?.warn?.(`[PD:EvolutionWorker] sleep_reflection task ${sleepTask.id} workflow failed: ${sleepTask.lastError}`);
                             }
                         } else {
@@ -1511,18 +1535,14 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
                     // #202: Handle expected subagent unavailability (e.g., process isolation in daemon mode)
                     // When subagent is unavailable due to gateway running in separate process,
                     // use stub fallback instead of failing the task.
+                    sleepTask.status = 'failed';
+                    sleepTask.completed_at = new Date().toISOString();
+                    sleepTask.resolution = 'failed_max_retries';
+                    sleepTask.lastError = String(taskErr);
+                    sleepTask.retryCount = (sleepTask.retryCount ?? 0) + 1;
                     if (isExpectedSubagentError(taskErr)) {
-                        sleepTask.status = 'completed';
-                        sleepTask.completed_at = new Date().toISOString();
-                        sleepTask.resolution = 'stub_fallback';
-                        sleepTask.lastError = String(taskErr);
-                        logger?.info?.(`[PD:EvolutionWorker] sleep_reflection task ${sleepTask.id} completed with stub fallback (subagent unavailable)`);
+                        logger?.warn?.(`[PD:EvolutionWorker] sleep_reflection task ${sleepTask.id} background runtime unavailable: ${String(taskErr)}`);
                     } else {
-                        sleepTask.status = 'failed';
-                        sleepTask.completed_at = new Date().toISOString();
-                        sleepTask.resolution = 'failed_max_retries';
-                        sleepTask.lastError = String(taskErr);
-                        sleepTask.retryCount = (sleepTask.retryCount ?? 0) + 1;
                         logger?.error?.(`[PD:EvolutionWorker] sleep_reflection task ${sleepTask.id} threw: ${taskErr}`);
                     }
                 }

package/src/service/monitoring-query-service.ts

@@ -0,0 +1,277 @@
+import { WorkflowStore } from './subagent-workflow/workflow-store.js';
+
+/**
+ * Monitoring query service for Nocturnal workflows and Trinity stages.
+ * Encapsulates all monitoring data queries, keeping logic separate from API routes.
+ */
+export class MonitoringQueryService {
+  private readonly workspaceDir: string;
+  private readonly store: WorkflowStore;
+
+  constructor(workspaceDir: string) {
+    this.workspaceDir = workspaceDir;
+    this.store = new WorkflowStore({ workspaceDir });
+  }
+
+  dispose(): void {
+    this.store.dispose();
+  }
+
+  /**
+   * Get workflows with optional filtering and stuck detection.
+   * @param filters - Optional state and type filters
+   * @returns Workflow list with stuck detection
+   */
+  getWorkflows(filters: { state?: string; type?: string } = {}): WorkflowListResponse {
+    // Query workflows from WorkflowStore
+    let workflows = filters.state
+      ? this.store.listWorkflows(filters.state)
+      : this.store.listWorkflows();
+
+    // Filter by workflow type if specified
+    if (filters.type) {
+      workflows = workflows.filter(wf => wf.workflow_type === filters.type);
+    }
+
+    const now = Date.now();
+    const workflowsWithStuckDetection = workflows.map(wf => {
+      // Parse metadata for timeout configuration
+      const metadata = parseWorkflowMetadata(wf.metadata_json);
+      const timeoutMs = metadata.timeoutMs ?? 15 * 60 * 1000; // Default 15 minutes
+
+      // Check if workflow is stuck (active and exceeded timeout)
+      const isStuck = wf.state === 'active' && (now - wf.created_at) > timeoutMs;
+      const stuckDuration = isStuck ? now - wf.created_at : null;
+
+      return {
+        workflowId: wf.workflow_id,
+        type: wf.workflow_type,
+        state: isStuck ? 'stuck' : wf.state,
+        duration: now - wf.created_at,
+        createdAt: new Date(wf.created_at).toISOString(),
+        stuckDuration,
+      };
+    });
+
+    return { workflows: workflowsWithStuckDetection };
+  }
+
+  /**
+   * Get Trinity stage status for a specific workflow.
+   * @param workflowId - Workflow ID to query
+   * @returns Trinity stage status or null if workflow not found
+   */
+  getTrinityStatus(workflowId: string): TrinityStatusResponse | null {
+    // Get workflow and validate
+    const workflow = this.store.getWorkflow(workflowId);
+    if (!workflow) {
+      return null;
+    }
+
+    // Fetch stage data
+    const events = this.store.getEvents(workflowId);
+    const stageOutputs = this.store.getStageOutputs(workflowId);
+
+    // Define stage types
+    const stages = ['dreamer', 'philosopher', 'scribe'] as const;
+
+    // Compute stage states from events
+    const stagesInfo: TrinityStageInfo[] = stages.map(stage => {
+      // Find events for this stage
+      const startEvent = events.find(e => e.event_type === `trinity_${stage}_start`);
+      const completeEvent = events.find(e => e.event_type === `trinity_${stage}_complete`);
+      const failedEvent = events.find(e => e.event_type === `trinity_${stage}_failed`);
+
+      // Determine status
+      // eslint-disable-next-line @typescript-eslint/init-declarations
+      let status: 'pending' | 'running' | 'completed' | 'failed';
+      // eslint-disable-next-line @typescript-eslint/init-declarations
+      let reason: string | undefined;
+
+      if (!startEvent) {
+        status = 'pending';
+        reason = undefined;
+      } else if (failedEvent) {
+        status = 'failed';
+        ({ reason } = failedEvent);
+      } else if (completeEvent) {
+        status = 'completed';
+        reason = undefined;
+      } else {
+        status = 'running';
+        reason = undefined;
+      }
+
+      // Count outputs for this stage
+      const outputCount = stageOutputs.filter(so => so.stage === stage).length;
+
+      // Calculate duration if stage started and completed/failed
+      // eslint-disable-next-line @typescript-eslint/init-declarations
+      let duration: number | undefined;
+      if (startEvent && (completeEvent || failedEvent)) {
+        const endEvent = completeEvent || failedEvent;
+        if (endEvent) {
+          duration = endEvent.created_at - startEvent.created_at;
+        }
+      }
+
+      return {
+        stage,
+        status,
+        reason,
+        outputCount,
+        duration,
+      };
+    });
+
+    return {
+      workflowId,
+      stages: stagesInfo,
+    };
+  }
+
+  /**
+   * Get aggregate health metrics for all Trinity workflows.
+   * @returns Aggregate health statistics
+   */
+  getTrinityHealth(): TrinityHealthResponse {
+    // Get all workflows
+    const workflows = this.store.listWorkflows();
+
+    // Initialize counters
+    let totalCalls = 0;
+    let totalDuration = 0;
+    let failedCalls = 0;
+
+    // Initialize stage statistics
+    const stageStats = {
+      dreamer: { total: 0, completed: 0, failed: 0 },
+      philosopher: { total: 0, completed: 0, failed: 0 },
+      scribe: { total: 0, completed: 0, failed: 0 },
+    };
+
+    // Iterate through workflows and aggregate
+    for (const workflow of workflows) {
+      const events = this.store.getEvents(workflow.workflow_id);
+      const isTerminal =
+        workflow.state === 'completed'
+        || workflow.state === 'terminal_error'
+        || workflow.state === 'expired'
+        || workflow.state === 'cleanup_pending';
+      let workflowFailed = false;
+
+      // Aggregate stage statistics
+      for (const stage of ['dreamer', 'philosopher', 'scribe'] as const) {
+        // Check if stage started
+        const started = events.some(e => e.event_type === `trinity_${stage}_start`);
+        if (started) {
+          stageStats[stage].total++;
+        }
+
+        // Check if completed
+        const completed = events.some(e => e.event_type === `trinity_${stage}_complete`);
+        if (completed) {
+          stageStats[stage].completed++;
+        }
+
+        // Check if failed
+        const failed = events.some(e => e.event_type === `trinity_${stage}_failed`);
+        if (failed) {
+          stageStats[stage].failed++;
+          workflowFailed = true;
+        }
+      }
+
+      // Calculate duration for terminal workflows so the aggregate reflects all finished runs.
+      if (isTerminal) {
+        totalCalls++;
+        const duration = workflow.duration_ms ?? (Date.now() - workflow.created_at);
+        totalDuration += duration;
+        if (workflowFailed || workflow.state === 'terminal_error' || workflow.state === 'expired') {
+          failedCalls++;
+        }
+      }
+    }
+
+    // Calculate derived metrics
+    const avgDuration = totalCalls > 0 ? totalDuration / totalCalls : 0;
+    const failureRate = totalCalls > 0 ? failedCalls / totalCalls : 0;
+
+    return {
+      totalCalls,
+      avgDuration: Math.round(avgDuration),
+      failureRate: Number(failureRate.toFixed(4)),
+      stageStats,
+    };
+  }
+}
+
+function parseWorkflowMetadata(metadataJson: string): { timeoutMs?: number } {
+  try {
+    const parsed = JSON.parse(metadataJson) as { timeoutMs?: number };
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Response type for workflow listing endpoint.
+ */
+export interface WorkflowListResponse {
+  workflows: WorkflowInfo[];
+}
+
+/**
+ * Enriched workflow information with stuck detection.
+ */
+export interface WorkflowInfo {
+  workflowId: string;
+  type: string;
+  state: string;
+  duration: number;
+  createdAt: string;
+  stuckDuration: number | null;
+}
+
+/**
+ * Response type for Trinity status endpoint.
+ */
+export interface TrinityStatusResponse {
+  workflowId: string;
+  stages: TrinityStageInfo[];
+}
+
+/**
+ * Information about a single Trinity stage.
+ */
+export interface TrinityStageInfo {
+  stage: 'dreamer' | 'philosopher' | 'scribe';
+  status: 'pending' | 'running' | 'completed' | 'failed';
+  reason?: string;
+  outputCount: number;
+  duration?: number;
+}
+
+/**
+ * Response type for Trinity health metrics endpoint.
+ */
+export interface TrinityHealthResponse {
+  totalCalls: number;
+  avgDuration: number;
+  failureRate: number;
+  stageStats: {
+    dreamer: StageStats;
+    philosopher: StageStats;
+    scribe: StageStats;
+  };
+}
+
+/**
+ * Per-stage statistics.
+ */
+export interface StageStats {
+  total: number;
+  completed: number;
+  failed: number;
+}

package/src/service/nocturnal-service.ts

@@ -1174,7 +1174,15 @@ async function executeNocturnalReflectionWithAdapter(
         quotaCheckPassed: true,
       },
     };
-    diagnostics.idle = { isIdle: true, mostRecentActivityAt: 0, idleForMs: 0, userActiveSessions: 0, abandonedSessionIds: [], trajectoryGuardrailConfirmsIdle: true, reason: 'selector skipped (override provided)' };
+    diagnostics.idle = {
+      isIdle: true,
+      mostRecentActivityAt: 0,
+      idleForMs: 0,
+      userActiveSessions: 0,
+      abandonedSessionIds: [],
+      trajectoryGuardrailConfirmsIdle: true,
+      reason: 'selector skipped (override provided)',
+    };
   } else {
     // Normal Selector path
     const extractor = createNocturnalTrajectoryExtractor(workspaceDir, stateDir);

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

@@ -234,6 +234,7 @@ export class NocturnalWorkflowManager implements WorkflowManager {
         // When principleId is provided, we pass it as principleIdOverride to skip Selector.
         // When principleId is missing, Selector will choose a principle from training store.
         this.logger.info(`[PD:NocturnalWorkflow] Calling executeNocturnalReflectionAsync for full pipeline (principleId=${principleId ?? 'auto-select'})`);
+        const pipelineStart = Date.now();
 
         // #213: Wrap fire-and-forget Promise with .catch() to prevent
         // unhandled promise rejections if anything throws outside the try-catch
@@ -263,25 +264,32 @@ export class NocturnalWorkflowManager implements WorkflowManager {
                 );
 
                 if (result.success) {
+                    this.logger.info(`[PD:NocturnalWorkflow] [${workflowId}] Pipeline step 4/4: Completed successfully, artifactId=${result.diagnostics?.persistedPath}`);
+                    this.store.updateWorkflowState(workflowId, 'completed');
                     this.store.recordEvent(workflowId, 'nocturnal_completed', null, 'completed', 'Full pipeline completed via executeNocturnalReflectionAsync', {
                         artifactId: result.diagnostics?.persistedPath,
                     });
                     this.completedWorkflows.set(workflowId, Date.now());
                 } else {
                     const reason = result.noTargetSelected ? 'no_target_selected' : 'validation_failed';
+                    this.logger.warn(`[PD:NocturnalWorkflow] [${workflowId}] Pipeline failed: reason=${reason}, noTargetSelected=${result.noTargetSelected}, skipReason=${result.skipReason ?? 'none'}, validationFailures=${result.validationFailures?.length ?? 0}`);
+                    this.store.updateWorkflowState(workflowId, 'terminal_error');
                     this.store.recordEvent(workflowId, 'nocturnal_failed', null, 'terminal_error', reason, {
                         failures: result.validationFailures,
                         skipReason: result.skipReason,
                     });
                 }
             } catch (err) {
-                this.logger.error(`[PD:NocturnalWorkflow] executeNocturnalReflectionAsync threw: ${String(err)}`);
+                const errDuration = Date.now() - pipelineStart;
+                this.logger.error(`[PD:NocturnalWorkflow] [${workflowId}] executeNocturnalReflectionAsync threw after ${errDuration}ms: ${String(err)}`);
+                this.store.updateWorkflowState(workflowId, 'terminal_error');
                 this.store.recordEvent(workflowId, 'nocturnal_failed', null, 'terminal_error', String(err), { workflowId });
             }
         }).catch((err) => {
-            // #213: Outer catch — catches errors from the fire-and-forget promise
+            // #213: Outer catch – catches errors from the fire-and-forget promise
             // itself (e.g., if the async callback throws before entering try).
             this.logger.error(`[PD:NocturnalWorkflow] Unhandled error in async pipeline for ${workflowId}: ${String(err)}`);
+            this.store.updateWorkflowState(workflowId, 'terminal_error');
             this.store.recordEvent(workflowId, 'nocturnal_failed', null, 'terminal_error', String(err), { workflowId });
         });
 

package/tests/core/principle-tree-migration.test.ts

@@ -0,0 +1,77 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { needsMigration } from '../../src/core/principle-tree-migration.js';
+import { safeRmDir } from '../test-utils.js';
+
+function writeLedger(stateDir: string, payload: unknown): void {
+  fs.mkdirSync(stateDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(stateDir, 'principle_training_state.json'),
+    JSON.stringify(payload, null, 2),
+    'utf8'
+  );
+}
+
+describe('principle-tree-migration', () => {
+  const tempDirs: string[] = [];
+
+  afterEach(() => {
+    while (tempDirs.length > 0) {
+      const dir = tempDirs.pop();
+      if (dir) safeRmDir(dir);
+    }
+  });
+
+  it('requires migration when trainingStore and tree.principles counts match but ids differ', () => {
+    const workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-migration-'));
+    const stateDir = path.join(workspaceDir, '.state');
+    tempDirs.push(workspaceDir);
+
+    writeLedger(stateDir, {
+      P_001: {
+        principleId: 'P_001',
+        evaluability: 'manual_only',
+        applicableOpportunityCount: 0,
+        observedViolationCount: 0,
+        complianceRate: 0,
+        violationTrend: 0,
+        generatedSampleCount: 0,
+        approvedSampleCount: 0,
+        includedTrainRunIds: [],
+        deployedCheckpointIds: [],
+        internalizationStatus: 'prompt_only',
+      },
+      _tree: {
+        principles: {
+          P_999: {
+            id: 'P_999',
+            version: 1,
+            text: 'Other principle',
+            triggerPattern: '',
+            action: '',
+            status: 'candidate',
+            priority: 'P1',
+            scope: 'general',
+            evaluability: 'manual_only',
+            valueScore: 0,
+            adherenceRate: 0,
+            painPreventedCount: 0,
+            derivedFromPainIds: [],
+            ruleIds: [],
+            conflictsWithPrincipleIds: [],
+            createdAt: '2026-04-10T00:00:00.000Z',
+            updatedAt: '2026-04-10T00:00:00.000Z',
+          },
+        },
+        rules: {},
+        implementations: {},
+        metrics: {},
+        lastUpdated: '2026-04-10T00:00:00.000Z',
+      },
+    });
+
+    expect(needsMigration(stateDir)).toBe(true);
+  });
+});

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

@@ -0,0 +1,208 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+vi.mock('../../src/core/dictionary-service.js', () => ({
+  DictionaryService: {
+    get: vi.fn(() => ({ flush: vi.fn() })),
+  },
+}));
+
+vi.mock('../../src/core/session-tracker.js', () => ({
+  initPersistence: vi.fn(),
+  flushAllSessions: vi.fn(),
+  listSessions: vi.fn(() => []),
+}));
+
+const { mockStartWorkflow, mockGetWorkflowDebugSummary } = vi.hoisted(() => ({
+  mockStartWorkflow: vi.fn(),
+  mockGetWorkflowDebugSummary: vi.fn(),
+}));
+
+vi.mock('../../src/service/subagent-workflow/nocturnal-workflow-manager.js', () => ({
+  NocturnalWorkflowManager: class {
+    startWorkflow = mockStartWorkflow;
+    getWorkflowDebugSummary = mockGetWorkflowDebugSummary;
+  },
+  nocturnalWorkflowSpec: {
+    workflowType: 'nocturnal',
+    transport: 'runtime_direct',
+    timeoutMs: 15 * 60 * 1000,
+    ttlMs: 30 * 60 * 1000,
+  },
+}));
+
+const { mockGetNocturnalSessionSnapshot } = vi.hoisted(() => ({
+  mockGetNocturnalSessionSnapshot: vi.fn(),
+}));
+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,
+    })),
+  };
+});
+
+import { EvolutionWorkerService } from '../../src/service/evolution-worker.js';
+import { safeRmDir } from '../test-utils.js';
+
+function readQueue(stateDir: string) {
+  return JSON.parse(fs.readFileSync(path.join(stateDir, 'evolution_queue.json'), 'utf8'));
+}
+
+describe('EvolutionWorkerService nocturnal hardening', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.clearAllMocks();
+    EvolutionWorkerService.api = null;
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    EvolutionWorkerService.api = null;
+  });
+
+  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'
+    );
+
+    try {
+      EvolutionWorkerService.start({
+        workspaceDir,
+        stateDir,
+        logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },
+        config: {},
+      } as any);
+
+      await vi.advanceTimersByTimeAsync(6000);
+
+      const queue = readQueue(stateDir);
+      expect(queue[0].status).toBe('failed');
+      expect(queue[0].lastError).toContain('missing_usable_snapshot');
+      expect(queue[0].resultRef).toBeFalsy();
+      expect(mockStartWorkflow).not.toHaveBeenCalled();
+    } finally {
+      EvolutionWorkerService.stop({ workspaceDir, stateDir, logger: console } as any);
+      safeRmDir(workspaceDir);
+    }
+  });
+
+  it('keeps gateway-only background failures as failed instead of completed stub fallback', 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: {},
+        },
+      ],
+    });
+
+    EvolutionWorkerService.api = {
+      logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },
+      runtime: {},
+    } as any;
+
+    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: { score: 0.5, source: 'pain', reason: 'x', timestamp: '2026-04-10T00:00:00.000Z' },
+            recentPainCount: 1,
+            recentMaxPainScore: 0.5,
+          },
+        },
+      ], null, 2),
+      'utf8'
+    );
+
+    try {
+      EvolutionWorkerService.start({
+        workspaceDir,
+        stateDir,
+        logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },
+        config: {},
+      } as any);
+
+      await vi.advanceTimersByTimeAsync(6000);
+
+      const queue = readQueue(stateDir);
+      expect(queue[0].status).toBe('failed');
+      expect(queue[0].resolution).toBe('failed_max_retries');
+      expect(queue[0].lastError).toContain('gateway request');
+    } finally {
+      EvolutionWorkerService.stop({ workspaceDir, stateDir, logger: console } as any);
+      safeRmDir(workspaceDir);
+    }
+  });
+});

package/tests/service/monitoring-query-service.test.ts

@@ -0,0 +1,113 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { WorkflowEventRow, WorkflowRow } from '../../src/service/subagent-workflow/types.js';
+
+const mockListWorkflows = vi.fn<() => WorkflowRow[]>();
+const mockGetWorkflow = vi.fn<(workflowId: string) => WorkflowRow | null>();
+const mockGetEvents = vi.fn<(workflowId: string) => WorkflowEventRow[]>();
+const mockGetStageOutputs = vi.fn<(workflowId: string) => Array<{ stage: string }>>();
+const mockDispose = vi.fn();
+
+vi.mock('../../src/service/subagent-workflow/workflow-store.js', () => ({
+  WorkflowStore: class {
+    listWorkflows = mockListWorkflows;
+    getWorkflow = mockGetWorkflow;
+    getEvents = mockGetEvents;
+    getStageOutputs = mockGetStageOutputs;
+    dispose = mockDispose;
+  },
+}));
+
+import { MonitoringQueryService } from '../../src/service/monitoring-query-service.js';
+
+function createWorkflow(overrides: Partial<WorkflowRow> = {}): WorkflowRow {
+  return {
+    workflow_id: overrides.workflow_id ?? 'wf-1',
+    workflow_type: overrides.workflow_type ?? 'nocturnal',
+    transport: overrides.transport ?? 'runtime_direct',
+    parent_session_id: overrides.parent_session_id ?? 'parent-1',
+    child_session_key: overrides.child_session_key ?? 'child-1',
+    run_id: overrides.run_id ?? null,
+    state: overrides.state ?? 'completed',
+    cleanup_state: overrides.cleanup_state ?? 'none',
+    created_at: overrides.created_at ?? Date.UTC(2026, 3, 10, 0, 0, 0),
+    updated_at: overrides.updated_at ?? Date.UTC(2026, 3, 10, 0, 5, 0),
+    last_observed_at: overrides.last_observed_at ?? null,
+    duration_ms: overrides.duration_ms ?? 1_000,
+    metadata_json: overrides.metadata_json ?? '{}',
+  };
+}
+
+function createEvent(
+  workflowId: string,
+  eventType: string,
+  createdAt: number,
+  reason = ''
+): WorkflowEventRow {
+  return {
+    workflow_id: workflowId,
+    event_type: eventType,
+    from_state: null,
+    to_state: 'completed',
+    reason,
+    payload_json: '{}',
+    created_at: createdAt,
+  };
+}
+
+describe('MonitoringQueryService', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockListWorkflows.mockReturnValue([]);
+    mockGetWorkflow.mockReturnValue(null);
+    mockGetEvents.mockReturnValue([]);
+    mockGetStageOutputs.mockReturnValue([]);
+  });
+
+  it('ignores malformed workflow metadata when listing workflows', () => {
+    mockListWorkflows.mockReturnValue([
+      createWorkflow({
+        workflow_id: 'wf-malformed',
+        metadata_json: '{invalid',
+      }),
+    ]);
+
+    const service = new MonitoringQueryService('/workspace');
+    const result = service.getWorkflows();
+
+    expect(result.workflows).toHaveLength(1);
+    expect(result.workflows[0]).toMatchObject({
+      workflowId: 'wf-malformed',
+      state: 'completed',
+      stuckDuration: null,
+    });
+  });
+
+  it('computes failure rate per terminal workflow instead of per failed stage', () => {
+    mockListWorkflows.mockReturnValue([
+      createWorkflow({ workflow_id: 'wf-complete', state: 'completed', duration_ms: 500 }),
+      createWorkflow({ workflow_id: 'wf-failed', state: 'terminal_error', duration_ms: 750 }),
+    ]);
+    mockGetEvents.mockImplementation((workflowId: string) => {
+      if (workflowId === 'wf-failed') {
+        return [
+          createEvent(workflowId, 'trinity_dreamer_start', 1),
+          createEvent(workflowId, 'trinity_dreamer_failed', 2, 'dreamer failed'),
+          createEvent(workflowId, 'trinity_philosopher_start', 3),
+          createEvent(workflowId, 'trinity_philosopher_failed', 4, 'philosopher failed'),
+        ];
+      }
+      return [
+        createEvent(workflowId, 'trinity_dreamer_start', 1),
+        createEvent(workflowId, 'trinity_dreamer_complete', 2),
+      ];
+    });
+
+    const service = new MonitoringQueryService('/workspace');
+    const result = service.getTrinityHealth();
+
+    expect(result.totalCalls).toBe(2);
+    expect(result.failureRate).toBe(0.5);
+    expect(result.stageStats.dreamer.failed).toBe(1);
+    expect(result.stageStats.philosopher.failed).toBe(1);
+  });
+});

package/tests/service/nocturnal-runtime-hardening.test.ts

@@ -0,0 +1,85 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+const { mockExecuteNocturnalReflectionAsync } = vi.hoisted(() => ({
+  mockExecuteNocturnalReflectionAsync: vi.fn(),
+}));
+
+vi.mock('../../src/service/nocturnal-service.js', () => ({
+  executeNocturnalReflectionAsync: mockExecuteNocturnalReflectionAsync,
+}));
+
+vi.mock('../../src/utils/subagent-probe.js', () => ({
+  isSubagentRuntimeAvailable: vi.fn(() => true),
+}));
+
+vi.mock('../../src/core/nocturnal-paths.js', () => ({
+  resolveNocturnalDir: vi.fn((workspaceDir: string) => path.join(workspaceDir, '.state', 'nocturnal', 'samples')),
+}));
+
+import { NocturnalWorkflowManager, nocturnalWorkflowSpec } from '../../src/service/subagent-workflow/nocturnal-workflow-manager.js';
+import { safeRmDir } from '../test-utils.js';
+
+describe('NocturnalWorkflowManager runtime hardening', () => {
+  let workspaceDir: string;
+  let stateDir: string;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-nocturnal-wf-'));
+    stateDir = path.join(workspaceDir, '.state');
+    fs.mkdirSync(stateDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    safeRmDir(workspaceDir);
+  });
+
+  it('marks workflow terminal_error when async pipeline throws a gateway-only runtime error', async () => {
+    mockExecuteNocturnalReflectionAsync.mockRejectedValue(
+      new Error('Plugin runtime subagent methods are only available during a gateway request.')
+    );
+
+    const manager = new NocturnalWorkflowManager({
+      workspaceDir,
+      stateDir,
+      logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() } as any,
+      runtimeAdapter: {} as any,
+    });
+
+    const handle = await manager.startWorkflow(nocturnalWorkflowSpec, {
+      parentSessionId: 'sleep_reflection:test',
+      taskInput: {},
+      metadata: {
+        snapshot: {
+          sessionId: 'session-1',
+          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,
+          },
+        },
+      },
+    });
+
+    await Promise.resolve();
+    await Promise.resolve();
+
+    const summary = await manager.getWorkflowDebugSummary(handle.workflowId);
+    expect(summary?.state).toBe('terminal_error');
+    expect(summary?.recentEvents.some((event) => event.eventType === 'nocturnal_failed')).toBe(true);
+
+    manager.dispose();
+  });
+});