principles-disciple 1.14.0 → 1.16.0

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