create-principles-disciple 1.0.0 → 1.74.0

package/plugin/dist/service/failure-classifier.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Failure Classifier -- Pure stateless classification of task failure patterns
+ * ===========================================================
+ *
+ * Classifies consecutive task failures from the evolution queue as transient
+ * or persistent. This module is pure (no file I/O) and testable in isolation.
+ *
+ * The classifier reads the evolution queue to count consecutive failures per
+ * task kind. When the count reaches the configured threshold (default 3),
+ * the pattern is classified as "persistent" and the cooldown strategy should
+ * be invoked.
+ *
+ * IMPORTANT: Only `status === 'failed'` counts as a failure.
+ * `status === 'completed'` (including stub_fallback and skipped_thin_violation
+ * resolutions) counts as a success and breaks the consecutive failure chain.
+ */
+import type { EvolutionQueueItem } from './evolution-worker.js';
+/** Task kinds subject to failure classification.
+ *  Only sleep_reflection and keyword_optimization have outcome handling in
+ *  evolution-worker.ts. pain_diagnosis and model_eval are excluded. */
+export type ClassifiableTaskKind = 'sleep_reflection' | 'keyword_optimization';
+export interface FailureClassificationResult {
+    /** Whether the failure pattern is transient or persistent */
+    classification: 'transient' | 'persistent';
+    /** Number of consecutive failures for this task kind */
+    consecutiveFailures: number;
+    /** The task kind that was analyzed */
+    taskKind: ClassifiableTaskKind;
+}
+/**
+ * Classify the failure pattern for a given task kind based on recent task
+ * outcomes in the evolution queue.
+ *
+ * Algorithm:
+ * 1. Filter queue to tasks of the specified taskKind with status 'completed' or 'failed'
+ * 2. Sort by completed_at (or timestamp fallback) descending (newest first)
+ * 3. Count consecutive 'failed' tasks from the top
+ * 4. First non-'failed' task (i.e., 'completed') breaks the chain
+ * 5. If consecutive count >= threshold, classify as 'persistent'
+ *
+ * @param queue - Current evolution queue (array of EvolutionQueueItem)
+ * @param taskKind - Task kind to classify
+ * @param threshold - Consecutive failure threshold for "persistent" (default: 3)
+ * @returns FailureClassificationResult
+ */
+export declare function classifyFailure(queue: EvolutionQueueItem[], taskKind: ClassifiableTaskKind, threshold?: number): FailureClassificationResult;

package/plugin/dist/service/failure-classifier.js

@@ -0,0 +1,57 @@
+/**
+ * Failure Classifier -- Pure stateless classification of task failure patterns
+ * ===========================================================
+ *
+ * Classifies consecutive task failures from the evolution queue as transient
+ * or persistent. This module is pure (no file I/O) and testable in isolation.
+ *
+ * The classifier reads the evolution queue to count consecutive failures per
+ * task kind. When the count reaches the configured threshold (default 3),
+ * the pattern is classified as "persistent" and the cooldown strategy should
+ * be invoked.
+ *
+ * IMPORTANT: Only `status === 'failed'` counts as a failure.
+ * `status === 'completed'` (including stub_fallback and skipped_thin_violation
+ * resolutions) counts as a success and breaks the consecutive failure chain.
+ */
+/**
+ * Classify the failure pattern for a given task kind based on recent task
+ * outcomes in the evolution queue.
+ *
+ * Algorithm:
+ * 1. Filter queue to tasks of the specified taskKind with status 'completed' or 'failed'
+ * 2. Sort by completed_at (or timestamp fallback) descending (newest first)
+ * 3. Count consecutive 'failed' tasks from the top
+ * 4. First non-'failed' task (i.e., 'completed') breaks the chain
+ * 5. If consecutive count >= threshold, classify as 'persistent'
+ *
+ * @param queue - Current evolution queue (array of EvolutionQueueItem)
+ * @param taskKind - Task kind to classify
+ * @param threshold - Consecutive failure threshold for "persistent" (default: 3)
+ * @returns FailureClassificationResult
+ */
+export function classifyFailure(queue, taskKind, threshold = 3) {
+    // Filter to this task kind, only terminal states (completed or failed)
+    const relevantTasks = queue
+        .filter(t => t.taskKind === taskKind)
+        .filter(t => t.status === 'completed' || t.status === 'failed')
+        .sort((a, b) => {
+        const aTime = new Date(a.completed_at || a.timestamp).getTime();
+        const bTime = new Date(b.completed_at || b.timestamp).getTime();
+        return bTime - aTime; // newest first
+    });
+    let consecutive = 0;
+    for (const task of relevantTasks) {
+        if (task.status === 'failed') {
+            consecutive++;
+        }
+        else {
+            break; // completed (any resolution including stub_fallback) breaks the chain
+        }
+    }
+    return {
+        classification: consecutive >= threshold ? 'persistent' : 'transient',
+        consecutiveFailures: consecutive,
+        taskKind,
+    };
+}

package/plugin/dist/service/internalization-trigger-adapter.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Internalization Dumb Trigger Adapter (PRI-63)
+ *
+ * Thin adapter that wakes periodically to probe SQLite for ready
+ * internalization tasks. Plugin layer only — does NOT execute LLM calls,
+ * does NOT directly chain PeerRunners, does NOT modify task status.
+ *
+ * Core decision functions (validateInternalizationTaskReady) determine
+ * if a task is ready to be processed. This adapter is only responsible
+ * for waking and logging — actual dispatch is handled by future
+ * Orchestrator PRI.
+ *
+ * @see docs/adr/0003-peer-agent-state-machine-orchestration.md
+ * @see packages/principles-core/src/runtime-v2/internalization/internalization-state-machine.ts (PRI-62)
+ */
+import type { TaskRecord } from '@principles/core/runtime-v2';
+export interface TriggerLogger {
+    debug?(msg: string, meta?: Record<string, unknown>): void;
+    info?(msg: string, meta?: Record<string, unknown>): void;
+    warn?(msg: string, meta?: Record<string, unknown>): void;
+    error?(msg: string, meta?: Record<string, unknown>): void;
+}
+export interface InternalizationTaskProvider {
+    listTasks(filter?: {
+        status?: string;
+        taskKind?: string;
+    }): Promise<TaskRecord[]>;
+    getTask(taskId: string): Promise<TaskRecord | null>;
+}
+export interface TriggerContext {
+    workspaceDir: string;
+    stateDir: string;
+}
+export interface InternalizationTriggerAdapter {
+    wake(ctx: TriggerContext): Promise<void>;
+    start(ctx: TriggerContext, intervalMs?: number): () => void;
+    stop(): void;
+}
+/**
+ * Creates a dumb trigger adapter that probes for ready internalization tasks.
+ *
+ * Design constraints (enforced by architecture regression guards):
+ * - PLUGIN_NO_INLINE_EXECUTION: wake() is read-only, does not await long tasks
+ * - PEER_NO_DIRECT_CHAINING: adapter does not call Dreamer/Philosopher/Scribe
+ * - TASK_MODEL_REUSE: reuses PITaskRecord / TaskRecord, no second task model
+ *
+ * @param provider - Task data access abstraction (SqliteTaskStore in production)
+ * @param logger - Optional structured logger
+ */
+export declare function createInternalizationTrigger(provider: InternalizationTaskProvider, logger?: TriggerLogger): InternalizationTriggerAdapter;
+export type { PITaskRecord, PeerRunnerKind } from '@principles/core/runtime-v2';

package/plugin/dist/service/internalization-trigger-adapter.js

@@ -0,0 +1,184 @@
+/**
+ * Internalization Dumb Trigger Adapter (PRI-63)
+ *
+ * Thin adapter that wakes periodically to probe SQLite for ready
+ * internalization tasks. Plugin layer only — does NOT execute LLM calls,
+ * does NOT directly chain PeerRunners, does NOT modify task status.
+ *
+ * Core decision functions (validateInternalizationTaskReady) determine
+ * if a task is ready to be processed. This adapter is only responsible
+ * for waking and logging — actual dispatch is handled by future
+ * Orchestrator PRI.
+ *
+ * @see docs/adr/0003-peer-agent-state-machine-orchestration.md
+ * @see packages/principles-core/src/runtime-v2/internalization/internalization-state-machine.ts (PRI-62)
+ */
+import { validateInternalizationTaskReady, isPeerRunnerKind, hydratePITaskRecord, } from '@principles/core/runtime-v2';
+// ── Log helper ────────────────────────────────────────────────────────────────
+function emitLog(logger, event) {
+    const { event: eventType, ...meta } = event;
+    switch (eventType) {
+        case 'INTERNALIZATION_TRIGGER_WAKE':
+            logger?.info?.('[PD:InternalizationTrigger] INTERNALIZATION_TRIGGER_WAKE', meta);
+            break;
+        case 'INTERNALIZATION_TRIGGER_NOOP':
+            logger?.debug?.('[PD:InternalizationTrigger] INTERNALIZATION_TRIGGER_NOOP', meta);
+            break;
+        case 'INTERNALIZATION_TRIGGER_BLOCKED':
+            logger?.debug?.('[PD:InternalizationTrigger] INTERNALIZATION_TRIGGER_BLOCKED', meta);
+            break;
+        case 'INTERNALIZATION_TRIGGER_FAILED':
+            logger?.error?.('[PD:InternalizationTrigger] INTERNALIZATION_TRIGGER_FAILED', meta);
+            break;
+    }
+}
+// ── Core adapter factory ───────────────────────────────────────────────────────
+/**
+ * Creates a dumb trigger adapter that probes for ready internalization tasks.
+ *
+ * Design constraints (enforced by architecture regression guards):
+ * - PLUGIN_NO_INLINE_EXECUTION: wake() is read-only, does not await long tasks
+ * - PEER_NO_DIRECT_CHAINING: adapter does not call Dreamer/Philosopher/Scribe
+ * - TASK_MODEL_REUSE: reuses PITaskRecord / TaskRecord, no second task model
+ *
+ * @param provider - Task data access abstraction (SqliteTaskStore in production)
+ * @param logger - Optional structured logger
+ */
+export function createInternalizationTrigger(provider, logger) {
+    const state = {
+        intervalId: null,
+    };
+    // ── wake: single trigger cycle ─────────────────────────────────────────────
+    async function wake(ctx) {
+        // Fail closed: missing workspaceDir or stateDir
+        if (!ctx.workspaceDir || !ctx.stateDir) {
+            emitLog(logger, {
+                event: 'INTERNALIZATION_TRIGGER_FAILED',
+                workspaceDir: ctx.workspaceDir ?? '(missing)',
+                failureCategory: 'invalid_context',
+                error: 'workspaceDir or stateDir is missing',
+                timestamp: new Date().toISOString(),
+            });
+            return;
+        }
+        try {
+            // Query pending and retry_wait tasks (non-terminal states that can be leased)
+            const pendingTasks = await provider.listTasks({ status: 'pending' });
+            const retryWaitTasks = await provider.listTasks({ status: 'retry_wait' });
+            // Filter to only PeerRunner tasks, then hydrate PI metadata from diagnosticJson.
+            // Tasks without valid PI metadata in diagnosticJson return null and are filtered out.
+            const pendingPITasks = pendingTasks
+                .filter(t => isPeerRunnerKind(t.taskKind))
+                .map(t => hydratePITaskRecord(t))
+                .filter((t) => t !== null);
+            const retryWaitPITasks = retryWaitTasks
+                .filter(t => isPeerRunnerKind(t.taskKind))
+                .map(t => hydratePITaskRecord(t))
+                .filter((t) => t !== null);
+            const candidateTasks = [...pendingPITasks, ...retryWaitPITasks];
+            // No candidates → NOOP
+            if (candidateTasks.length === 0) {
+                emitLog(logger, {
+                    event: 'INTERNALIZATION_TRIGGER_NOOP',
+                    workspaceDir: ctx.workspaceDir,
+                    timestamp: new Date().toISOString(),
+                });
+                return;
+            }
+            // Evaluate each candidate
+            let hasReadyTask = false;
+            for (const task of candidateTasks) {
+                // Fetch dependency tasks for gate validation
+                const dependencies = [];
+                if (task.dependencyTaskIds && task.dependencyTaskIds.length > 0) {
+                    for (const depId of task.dependencyTaskIds) {
+                        const dep = await provider.getTask(depId);
+                        if (dep)
+                            dependencies.push(dep);
+                        // Fail closed: if dep not found, dependencies array is incomplete
+                        // validateInternalizationTaskReady will return 'blocked'
+                    }
+                }
+                const gateResult = validateInternalizationTaskReady(task, dependencies);
+                if (gateResult.decision === 'proceed') {
+                    // Task is ready — log WAKE event (read-only, no mutation)
+                    emitLog(logger, {
+                        event: 'INTERNALIZATION_TRIGGER_WAKE',
+                        workspaceDir: ctx.workspaceDir,
+                        taskId: task.taskId,
+                        taskKind: task.taskKind,
+                        correlationId: task.correlationId,
+                        gateDecision: gateResult.decision,
+                        timestamp: new Date().toISOString(),
+                    });
+                    hasReadyTask = true;
+                }
+                else {
+                    // blocked, dependency_failed, or retry_wait_pending — debug visibility for operators
+                    emitLog(logger, {
+                        event: 'INTERNALIZATION_TRIGGER_BLOCKED',
+                        workspaceDir: ctx.workspaceDir,
+                        taskId: task.taskId,
+                        taskKind: task.taskKind,
+                        gateDecision: gateResult.decision,
+                        blockedBy: gateResult.decision === 'blocked' ? gateResult.blockedBy : undefined,
+                        failedDependencies: gateResult.decision === 'dependency_failed' ? gateResult.failedDependencies : undefined,
+                        retryAfter: gateResult.decision === 'retry_wait_pending' ? gateResult.retryAfter : undefined,
+                        timestamp: new Date().toISOString(),
+                    });
+                }
+            }
+            // All candidates were blocked
+            if (!hasReadyTask) {
+                emitLog(logger, {
+                    event: 'INTERNALIZATION_TRIGGER_NOOP',
+                    workspaceDir: ctx.workspaceDir,
+                    timestamp: new Date().toISOString(),
+                });
+            }
+        }
+        catch (err) {
+            emitLog(logger, {
+                event: 'INTERNALIZATION_TRIGGER_FAILED',
+                workspaceDir: ctx.workspaceDir,
+                failureCategory: 'provider_error',
+                error: err instanceof Error ? err.message : String(err),
+                timestamp: new Date().toISOString(),
+            });
+        }
+    }
+    // ── start: begin periodic wake cycles ─────────────────────────────────────
+    function start(ctx, intervalMs = 5 * 60 * 1000) {
+        // Prevent re-entrancy: if already running, warn and return existing stop
+        if (state.intervalId !== null) {
+            logger?.warn?.('[PD:InternalizationTrigger] start() called while already running — returning existing stop', {
+                workspaceDir: ctx.workspaceDir,
+                stateDir: ctx.stateDir,
+            });
+            return stop;
+        }
+        // Immediate first wake
+        wake(ctx).catch(err => {
+            logger?.error?.('[PD:InternalizationTrigger] start() initial wake failed', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        });
+        // Schedule periodic wake
+        state.intervalId = setInterval(() => {
+            wake(ctx).catch(err => {
+                logger?.error?.('[PD:InternalizationTrigger] periodic wake failed', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            });
+        }, intervalMs);
+        return stop;
+    }
+    // ── stop: halt periodic wake ──────────────────────────────────────────────
+    function stop() {
+        if (state.intervalId !== null) {
+            clearInterval(state.intervalId);
+            state.intervalId = null;
+        }
+    }
+    return { wake, start, stop };
+}

package/plugin/dist/service/keyword-optimization-service.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Keyword Optimization Service
+ *
+ * Applies LLM optimization results (ADD/UPDATE/REMOVE mutations) to the
+ * correction keyword store. Called by evolution-worker.ts after the
+ * keyword_optimization workflow completes.
+ */
+import type { CorrectionObserverOutputV1 as CorrectionObserverResult } from '@principles/core/runtime-v2';
+import type { PluginLogger } from '../openclaw-sdk.js';
+/**
+ * Applies CorrectionObserverResult mutations to the keyword store.
+ * - ADD: calls learner.add() with new keyword
+ * - UPDATE: updates weight on existing keyword
+ * - REMOVE: removes keyword from store
+ */
+export declare class KeywordOptimizationService {
+    private readonly stateDir;
+    private readonly workspaceDir;
+    private readonly logger;
+    constructor(stateDir: string, workspaceDir: string, logger: PluginLogger);
+    applyResult(result: CorrectionObserverResult): void;
+    /**
+     * Builds trajectory history for payload:
+     * - Calls TrajectoryDatabase.listUserTurnsForSession() for recent sessions
+     * - Filters to turns where correctionDetected=true
+     * - Returns last 50 correction events
+     */
+    buildTrajectoryHistory(sessionIds: string[]): Promise<TrajectoryHistoryEntry[]>;
+    private static _instances;
+    static get(stateDir: string, workspaceDir: string, logger: PluginLogger): KeywordOptimizationService;
+    static reset(): void;
+}
+/**
+ * Internal type mirroring the trajectoryHistory field in CorrectionObserverPayload.
+ * Exported here so buildTrajectoryHistory can reference it without a circular import.
+ */
+export type TrajectoryHistoryEntry = {
+    sessionId: string;
+    timestamp: string;
+    term: string;
+    userMessage: string;
+};
+/** Re-export CorrectionObserverPayload for convenience */
+export type { CorrectionObserverPayload } from '@principles/core/runtime-v2';

package/plugin/dist/service/keyword-optimization-service.js

@@ -0,0 +1,137 @@
+/**
+ * Keyword Optimization Service
+ *
+ * Applies LLM optimization results (ADD/UPDATE/REMOVE mutations) to the
+ * correction keyword store. Called by evolution-worker.ts after the
+ * keyword_optimization workflow completes.
+ */
+import { CorrectionCueLearner } from '../core/correction-cue-learner.js';
+import { TrajectoryRegistry } from '../core/trajectory.js';
+/**
+ * Applies CorrectionObserverResult mutations to the keyword store.
+ * - ADD: calls learner.add() with new keyword
+ * - UPDATE: updates weight on existing keyword
+ * - REMOVE: removes keyword from store
+ */
+export class KeywordOptimizationService {
+    stateDir;
+    workspaceDir;
+    logger;
+    constructor(stateDir, workspaceDir, logger) {
+        this.stateDir = stateDir;
+        this.workspaceDir = workspaceDir;
+        this.logger = logger;
+    }
+    applyResult(result) {
+        const learner = CorrectionCueLearner.get(this.stateDir);
+        const updates = result.updates ?? {};
+        if (!result.updated || Object.keys(updates).length === 0) {
+            this.logger?.info?.('[KeywordOptimizationService] No updates to apply');
+            return;
+        }
+        for (const [term, update] of Object.entries(updates)) {
+            try {
+                switch (update.action) {
+                    case 'add': {
+                        const normalizedTerm = term.trim().toLowerCase();
+                        // Check for existing normalized term to avoid duplicates
+                        const existing = learner.getStore().keywords.find(k => k.term.toLowerCase() === normalizedTerm);
+                        if (existing) {
+                            this.logger?.info?.(`[KeywordOptimizationService] ADD skipped: "${term}" already exists as "${existing.term}"`);
+                            break;
+                        }
+                        const weight = update.weight !== undefined
+                            ? Math.max(0.1, Math.min(0.9, update.weight))
+                            : 0.5;
+                        learner.add({ term: normalizedTerm, weight, source: 'llm' });
+                        this.logger?.info?.(`[KeywordOptimizationService] ADD term="${normalizedTerm}" weight=${weight}`);
+                        break;
+                    }
+                    case 'update': {
+                        if (update.weight !== undefined) {
+                            learner.updateWeight(term, update.weight);
+                            this.logger?.info?.(`[KeywordOptimizationService] UPDATE term="${term}" weight=${update.weight}`);
+                        }
+                        break;
+                    }
+                    case 'remove': {
+                        learner.remove(term);
+                        this.logger?.info?.(`[KeywordOptimizationService] REMOVE term="${term}"`);
+                        break;
+                    }
+                }
+            }
+            catch (opErr) {
+                // Log and skip individual operation failures — don't fail the whole batch
+                this.logger?.warn?.(`[KeywordOptimizationService] ${update.action.toUpperCase()} failed for term="${term}": ${String(opErr)}`);
+            }
+        }
+        // H-1: Record confirmed false positives — terms where correctionDetected fired
+        // but trajectory analysis shows user wasn't actually expressing frustration.
+        if (result.fpAnalysisStatus === 'completed' && result.fpTerms && result.fpTerms.length > 0) {
+            // Normalize: trim, lowercase, dedupe, sanity cap
+            const MAX_FP_TERMS = 20;
+            const normalizedFpTerms = [...new Set(result.fpTerms
+                    .map((t) => t.trim().toLowerCase())
+                    .filter((t) => t.length > 0))].slice(0, MAX_FP_TERMS);
+            for (const term of normalizedFpTerms) {
+                try {
+                    learner.recordFalsePositive(term);
+                    this.logger?.info?.(`[KeywordOptimizationService] FP recorded for term="${term}" (weight x0.8)`);
+                }
+                catch (fpErr) {
+                    this.logger?.warn?.(`[KeywordOptimizationService] recordFalsePositive failed for term="${term}": ${String(fpErr)}`);
+                }
+            }
+        }
+    }
+    /**
+     * Builds trajectory history for payload:
+     * - Calls TrajectoryDatabase.listUserTurnsForSession() for recent sessions
+     * - Filters to turns where correctionDetected=true
+     * - Returns last 50 correction events
+     */
+    async buildTrajectoryHistory(sessionIds) {
+        const history = [];
+        const db = TrajectoryRegistry.get(this.workspaceDir);
+        for (const sessionId of sessionIds.slice(0, 10)) { // Last 10 sessions
+            try {
+                const turns = db.listUserTurnsForSession(sessionId);
+                for (const turn of turns) {
+                    if (turn.correctionDetected) {
+                        history.push({
+                            sessionId,
+                            timestamp: turn.createdAt ?? new Date().toISOString(),
+                            term: turn.correctionCue ?? 'unknown',
+                            // Note: rawText is not available from listUserTurnsForSession (privacy: no raw text stored).
+                            // userMessage left empty — trajectory section is used for FPR trend analysis,
+                            // not for understanding user intent (correctionCue term is sufficient).
+                            userMessage: '',
+                        });
+                    }
+                    if (history.length >= 50)
+                        break; // Cap at 50 events
+                }
+            }
+            catch (dbErr) {
+                // Skip individual session DB errors — try remaining sessions
+                this.logger?.warn?.(`[KeywordOptimizationService] Failed to read trajectory for session ${sessionId}: ${String(dbErr)}`);
+            }
+            if (history.length >= 50)
+                break;
+        }
+        return history;
+    }
+    // ── Singleton factory ───────────────────────────────────────────────────
+    static _instances = new Map();
+    static get(stateDir, workspaceDir, logger) {
+        const key = `${stateDir}::${workspaceDir}`;
+        if (!KeywordOptimizationService._instances.has(key)) {
+            KeywordOptimizationService._instances.set(key, new KeywordOptimizationService(stateDir, workspaceDir, logger));
+        }
+        return KeywordOptimizationService._instances.get(key);
+    }
+    static reset() {
+        KeywordOptimizationService._instances.clear();
+    }
+}

package/plugin/dist/service/monitoring-query-service.d.ts

@@ -0,0 +1,21 @@
+export declare class MonitoringQueryService {
+    private readonly workspaceDir;
+    private readonly store;
+    constructor(workspaceDir: string);
+    dispose(): void;
+    getWorkflows(filters?: {
+        state?: string;
+        type?: string;
+    }): WorkflowListResponse;
+}
+export interface WorkflowListResponse {
+    workflows: WorkflowInfo[];
+}
+export interface WorkflowInfo {
+    workflowId: string;
+    type: string;
+    state: string;
+    duration: number;
+    createdAt: string;
+    stuckDuration: number | null;
+}

package/plugin/dist/service/monitoring-query-service.js

@@ -0,0 +1,45 @@
+import { WorkflowStore } from './subagent-workflow/workflow-store.js';
+export class MonitoringQueryService {
+    workspaceDir;
+    store;
+    constructor(workspaceDir) {
+        this.workspaceDir = workspaceDir;
+        this.store = new WorkflowStore({ workspaceDir });
+    }
+    dispose() {
+        this.store.dispose();
+    }
+    getWorkflows(filters = {}) {
+        let workflows = filters.state
+            ? this.store.listWorkflows(filters.state)
+            : this.store.listWorkflows();
+        if (filters.type) {
+            workflows = workflows.filter(wf => wf.workflow_type === filters.type);
+        }
+        const now = Date.now();
+        const workflowsWithStuckDetection = workflows.map(wf => {
+            const metadata = parseWorkflowMetadata(wf.metadata_json);
+            const timeoutMs = metadata.timeoutMs ?? 15 * 60 * 1000;
+            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 };
+    }
+}
+function parseWorkflowMetadata(metadataJson) {
+    try {
+        const parsed = JSON.parse(metadataJson);
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}

package/plugin/dist/service/phase3-input-filter.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Phase 3 Input Filter
+ *
+ * CRITICAL: evaluatePhase3Inputs() does NOT read or use evolution_directive.json
+ * Directive is a compatibility-only display artifact, not a truth source.
+ *
+ * Phase 3 eligibility depends ONLY on:
+ * - Queue truth (valid evolution samples from queue)
+ *
+ * Any directive file is ignored for eligibility decisions.
+ *
+ * THREE-LANE CLASSIFICATION:
+ * - authoritative: Valid inputs that can be used for Phase 3 eligibility decisions
+ * - reference_only: Valid evidence that must NOT be used as positive eligibility input
+ *   (e.g., timeout-only outcomes - they indicate completion but not success)
+ * - rejected: Invalid, corrupt, or policy-prohibited input
+ */
+/**
+ * Classification for Phase 3 inputs.
+ * - authoritative: Can be used for Phase 3 eligibility decisions
+ * - reference_only: Valid data but not for eligibility (e.g., timeout outcomes)
+ * - rejected: Invalid or corrupt data
+ */
+export type Phase3Classification = 'authoritative' | 'reference_only' | 'rejected';
+export interface Phase3EvolutionInput {
+    id?: string | null;
+    status?: string | null;
+    started_at?: string | null;
+    completed_at?: string | null;
+    resolution?: string | null;
+}
+export interface Phase3EvolutionSample {
+    taskId: string;
+    status: 'pending' | 'in_progress' | 'completed';
+    startedAt: string | null;
+    completedAt: string | null;
+}
+export interface Phase3ReferenceOnlySample {
+    taskId: string;
+    status: string;
+    classification: 'timeout_only' | 'other_reference';
+    reason: string;
+}
+export interface Phase3RejectedEvolutionSample {
+    taskId: string | null;
+    status: string | null;
+    reasons: string[];
+}
+export interface Phase3InputFilterResult {
+    queueTruthReady: boolean;
+    phase3ShadowEligible: boolean;
+    evolution: {
+        eligible: Phase3EvolutionSample[];
+        referenceOnly: Phase3ReferenceOnlySample[];
+        rejected: Phase3RejectedEvolutionSample[];
+    };
+}
+/**
+ * Evaluates Phase 3 readiness based on queue inputs.
+ *
+ * IMPORTANT: Does NOT use evolution_directive.json.
+ * Directive is compatibility-only display artifact, not a truth source.
+ * Queue is the only authoritative execution truth source for Phase 3.
+ *
+ * THREE-LANE CLASSIFICATION:
+ * - authoritative: Valid inputs for Phase 3 eligibility
+ * - reference_only: Valid evidence but not for eligibility (e.g., timeout outcomes)
+ * - rejected: Invalid, corrupt, or policy-prohibited input
+ *
+ * @param queue - Evolution queue items to validate
+ * @returns Phase 3 eligibility results
+ */
+export declare function evaluatePhase3Inputs(queue: Phase3EvolutionInput[]): Phase3InputFilterResult;