create-principles-disciple 1.0.0 → 1.74.0

package/plugin/dist/service/runtime-summary-service.js

@@ -0,0 +1,636 @@
+import * as fs from 'fs';
+import Database from 'better-sqlite3';
+import * as path from 'path';
+import { readPainFlagData } from '../core/pain.js';
+import { listSessions } from '../core/session-tracker.js';
+import { WorkspaceContext } from '../core/workspace-context.js';
+import { evaluatePhase3Inputs } from './phase3-input-filter.js';
+import { TrajectoryRegistry } from '../core/trajectory.js';
+import { buildGfiWorkspaceSnapshot } from '@principles/core/runtime-v2';
+const MAX_SOURCE_EVENTS = 5;
+const GFI_PARTIAL_WARNING = 'GFI source attribution remains partial in Phase 2b because only the empathy slice is source-attributed; most non-empathy friction still lacks full per-source attribution.';
+const DAILY_GFI_WARNING = 'daily-stats.gfi is not authoritative in Phase 1 and is used only as a fallback reference.';
+const EVENT_BUFFER_WARNING = 'Live event buffer is unavailable in this context, so status may lag until events.jsonl flushes.';
+function pushWarning(warnings, message) {
+    if (!warnings.includes(message)) {
+        warnings.push(message);
+    }
+}
+/**
+ * YAML-SSOT-03: resolve a dot-path (e.g. 'evolution.nocturnalDreamerCompleted') from dailyStats.
+ * Returns { count, resolvable } to distinguish "field not found / non-numeric" from "legitimate zero".
+ */
+function resolveStatsField(stats, dotPath) {
+    const parts = dotPath.split('.');
+    let current = stats;
+    for (const part of parts) {
+        if (current == null || typeof current !== 'object')
+            return { count: 0, resolvable: false };
+        current = current[part];
+    }
+    if (typeof current === 'number') {
+        return { count: current, resolvable: true };
+    }
+    return { count: 0, resolvable: false };
+}
+export class RuntimeSummaryService {
+    static getSummary(workspaceDir, options) {
+        const generatedAt = new Date().toISOString();
+        const warnings = [];
+        const wctx = WorkspaceContext.fromHookContext({ workspaceDir });
+        const sessions = this.mergeSessionSnapshots(this.readSessions(wctx.resolve('SESSION_DIR'), warnings), workspaceDir);
+        const selectedSession = this.selectSession(sessions, options?.sessionId ?? null);
+        const selectedSessionId = selectedSession.session?.sessionId ?? null;
+        const persistedEvents = this.readEvents(path.join(wctx.stateDir, 'logs'), warnings);
+        const hasBufferedEventAccess = typeof wctx.eventLog.getBufferedEvents === 'function';
+        const bufferedEvents = hasBufferedEventAccess
+            ? wctx.eventLog.getBufferedEvents()
+            : [];
+        const events = this.mergeEvents(persistedEvents, bufferedEvents);
+        const dailyStats = this.readJsonFile(path.join(wctx.stateDir, 'logs', 'daily-stats.json'), warnings, false);
+        // Unified date for all "today"-scope reads in this summary — ensures funnel counts,
+        // heartbeat stats, and dailyStats all agree on the same date and never contradict.
+        const todayStr = generatedAt.slice(0, 10);
+        // YAML-SSOT-02/03: build workflowFunnels from funnels Map if provided
+        let workflowFunnelsOutput;
+        if (options?.funnels) {
+            workflowFunnelsOutput = [];
+            for (const [funnelKey, stages] of options.funnels) {
+                const stageOutputs = stages.map(stage => {
+                    const { count, resolvable } = resolveStatsField(dailyStats?.[todayStr], stage.statsField);
+                    return {
+                        key: stage.name,
+                        label: stage.name,
+                        statsField: stage.statsField,
+                        count,
+                        _resolvable: resolvable, // internal tag for degraded detection
+                    };
+                });
+                workflowFunnelsOutput.push({ funnelKey, funnelLabel: funnelKey, stages: stageOutputs });
+            }
+        }
+        // YAML-SSOT-04: warn for any unresolvable statsField paths
+        let hasUnresolvableStage = false;
+        if (workflowFunnelsOutput) {
+            for (const funnel of workflowFunnelsOutput) {
+                for (const stage of funnel.stages) {
+                    if (!stage._resolvable) {
+                        hasUnresolvableStage = true;
+                        pushWarning(warnings, `statsField not resolvable: ${stage.statsField}`);
+                    }
+                }
+            }
+        }
+        // DEGRADED-01/02: status is degraded when YAML load errors or unresolvable statsField paths exist
+        const loaderWarnings = options?.loaderWarnings ?? [];
+        if (loaderWarnings.length > 0) {
+            for (const w of loaderWarnings) {
+                pushWarning(warnings, `YAML load warning: ${w}`);
+            }
+        }
+        const status = (loaderWarnings.length > 0 || hasUnresolvableStage) ? 'degraded' : 'ok';
+        // GFI peak — use today's data (consistent with funnel/heartbeat)
+        const dailyGfiPeak = dailyStats?.[todayStr]?.gfi?.peak;
+        const gfiCurrent = selectedSession.session && Number.isFinite(selectedSession.session.currentGfi)
+            ? Number(selectedSession.session.currentGfi)
+            : null;
+        const sessionPeak = selectedSession.session && Number.isFinite(selectedSession.session.dailyGfiPeak)
+            ? Number(selectedSession.session.dailyGfiPeak)
+            : null;
+        const gfiPeak = sessionPeak ?? (Number.isFinite(dailyGfiPeak) ? Number(dailyGfiPeak) : null);
+        // PRI-78/PRI-82: Build authoritative GFI workspace snapshot (active vs stale)
+        // Uses real persisted GFI fields: gfiBySource, consecutiveErrors, lastErrorSource,
+        // lastGfiDecayAt, dailyGfiPeak from session-tracker persistence.
+        const gfiWorkspaceSnapshot = buildGfiWorkspaceSnapshot({
+            sessions: sessions.map((s) => ({
+                sessionId: s.sessionId,
+                currentGfi: s.currentGfi ?? 0,
+                gfiBySource: s.gfiBySource ?? {},
+                consecutiveErrors: s.consecutiveErrors ?? 0,
+                lastErrorSource: s.lastErrorSource,
+                lastGfiDecayAt: s.lastGfiDecayAt,
+                dailyGfiPeak: s.dailyGfiPeak,
+                lastActivityAt: s.lastControlActivityAt ?? s.lastActivityAt ?? 0,
+            })),
+            nowMs: Date.now(),
+        });
+        pushWarning(warnings, GFI_PARTIAL_WARNING);
+        if (sessionPeak === null && Number.isFinite(dailyGfiPeak)) {
+            pushWarning(warnings, DAILY_GFI_WARNING);
+        }
+        if (!hasBufferedEventAccess) {
+            pushWarning(warnings, EVENT_BUFFER_WARNING);
+        }
+        if (!selectedSession.session) {
+            pushWarning(warnings, 'No persisted session state was found; current session GFI is unavailable.');
+        }
+        const queue = this.readJsonFile(wctx.resolve('EVOLUTION_QUEUE'), warnings, false);
+        // compatibility-only display artifact - not a truth source for Phase 3 eligibility
+        // queue is the only authoritative execution truth source for Phase 3
+        const directive = this.readJsonFile(wctx.resolve('EVOLUTION_DIRECTIVE'), warnings, false);
+        const queueStats = this.buildQueueStats(queue);
+        const directiveSummary = this.buildDirectiveSummary(queue, directive, generatedAt, warnings);
+        const painFlag = readPainFlagData(workspaceDir);
+        const painCandidates = this.readJsonFile(wctx.resolve('PAIN_CANDIDATES'), warnings, false);
+        const phase3Inputs = evaluatePhase3Inputs(queue ?? []);
+        const lastPainSignal = this.findLastPainSignal(events, selectedSessionId);
+        const gfiSources = this.buildGfiSources(events, selectedSessionId);
+        const gateStats = this.buildGateStats(events, selectedSessionId, warnings);
+        // D: Runtime Diagnostician chain (M8) — queries runtime-v2 SQLite task store
+        // Read heartbeat diagnosis stats from daily event log
+        const diagDailyStats = dailyStats?.[todayStr]?.evolution;
+        let pendingRuntimeDiagTasks = 0;
+        try {
+            const taskStoreDbPath = path.join(wctx.stateDir, '.principles', 'db', 'task-store.db');
+            if (fs.existsSync(taskStoreDbPath)) {
+                const db = new Database(taskStoreDbPath, { readonly: true });
+                const row = db.prepare(`
+          SELECT COUNT(*) as count FROM tasks
+          WHERE task_kind = 'diagnostician' AND status = 'pending'
+        `).get();
+                pendingRuntimeDiagTasks = row?.count ?? 0;
+                db.close();
+            }
+        }
+        catch { /* task store not yet initialized — 0 pending */ }
+        // TODO(PRI-XXX): distinguish "not initialized" from permission/corruption/query errors
+        const runtimeDiagnosis = {
+            pendingTasks: pendingRuntimeDiagTasks,
+            tasksWrittenToday: diagDailyStats?.diagnosisTasksWritten ?? 0,
+            reportsWrittenToday: diagDailyStats?.diagnosticianReportsWritten ?? 0,
+            reportsMissingJsonToday: diagDailyStats?.reportsMissingJson ?? 0,
+            reportsIncompleteFieldsToday: diagDailyStats?.reportsIncompleteFields ?? 0,
+            candidatesCreatedToday: diagDailyStats?.principleCandidatesCreated ?? 0,
+            heartbeatsInjectedToday: diagDailyStats?.heartbeatsInjected ?? 0,
+        };
+        // D: Stall detection — high-signal warning when the diagnostician loop appears broken.
+        // Conditions: tasks are being injected (heartbeats > 0) but no reports are being written.
+        if (runtimeDiagnosis.heartbeatsInjectedToday > 0 &&
+            runtimeDiagnosis.reportsWrittenToday === 0 &&
+            runtimeDiagnosis.pendingTasks > 0) {
+            pushWarning(warnings, 'Diagnostician appears stalled: heartbeats are injecting tasks ' +
+                `(${runtimeDiagnosis.heartbeatsInjectedToday}) but no reports are being written. ` +
+                `${runtimeDiagnosis.pendingTasks} task(s) remain pending. ` +
+                'Check prompt injection size limits and diagnostician task processing.');
+        }
+        // Read trajectory analytics data (historical data, NOT runtime truth)
+        const trajectoryStats = this.readTrajectoryStats(workspaceDir, warnings);
+        // Build runtime truth section (current state for control decisions)
+        const activeSessionIds = sessions.map(s => s.sessionId);
+        const runtimeTruth = {
+            queueState: {
+                total: queueStats.pending + queueStats.inProgress + queueStats.completed,
+                pending: queueStats.pending,
+                inProgress: queueStats.inProgress,
+                completed: queueStats.completed,
+                lastUpdated: generatedAt,
+            },
+            activeSessions: activeSessionIds,
+        };
+        // Build analytics truth section (historical data for insights)
+        const analyticsTruth = {
+            trajectoryData: {
+                totalTasks: trajectoryStats.assistantTurns + trajectoryStats.userTurns,
+                successRate: trajectoryStats.toolCalls > 0
+                    ? (trajectoryStats.toolCalls - trajectoryStats.failures) / trajectoryStats.toolCalls
+                    : 0,
+                timeoutRate: trajectoryStats.failures > 0
+                    ? trajectoryStats.failures / (trajectoryStats.assistantTurns + trajectoryStats.userTurns || 1)
+                    : 0,
+                lastUpdated: trajectoryStats.lastIngestAt ?? generatedAt,
+            },
+            dailyStats: {
+                toolCalls: dailyStats?.[todayStr]?.toolCalls ?? 0,
+                painSignals: dailyStats?.[todayStr]?.painSignals ?? 0,
+                evolutionTasks: dailyStats?.[todayStr]?.evolutionTasks ?? 0,
+                lastUpdated: todayStr,
+            },
+            trends: {
+                sevenDay: { successRateChange: 0, toolCallVolumeChange: 0, painSignalRateChange: 0 },
+                thirtyDay: { successRateChange: 0, toolCallVolumeChange: 0, painSignalRateChange: 0 },
+            },
+        };
+        return {
+            runtime: runtimeTruth,
+            analytics: analyticsTruth,
+            gfi: {
+                current: gfiCurrent,
+                peak: gfiPeak,
+                sources: gfiSources,
+                dataQuality: 'partial',
+                workspaceSnapshot: gfiWorkspaceSnapshot,
+            },
+            evolution: {
+                queue: queueStats,
+                directive: directiveSummary,
+                dataQuality: this.resolveEvolutionDataQuality(queue),
+            },
+            phase3: {
+                queueTruthReady: phase3Inputs.queueTruthReady,
+                phase3ShadowEligible: phase3Inputs.phase3ShadowEligible,
+                evolutionEligible: phase3Inputs.evolution.eligible.length,
+                evolutionReferenceOnly: phase3Inputs.evolution.referenceOnly.length,
+                evolutionReferenceOnlyReasons: [...new Set(phase3Inputs.evolution.referenceOnly.map((entry) => entry.classification))],
+                evolutionRejected: phase3Inputs.evolution.rejected.length,
+                evolutionRejectedReasons: phase3Inputs.evolution.rejected.flatMap((entry) => entry.reasons),
+                legacyDirectiveFilePresent: directive !== null,
+                directiveStatus: directive ? 'compatibility-only' : 'missing',
+                directiveIgnoredReason: 'queue is only truth source',
+                eligibilitySource: 'runtime_truth',
+            },
+            pain: {
+                activeFlag: Object.keys(painFlag).length > 0,
+                activeFlagSource: painFlag.source || null,
+                candidates: painCandidates?.candidates && typeof painCandidates.candidates === 'object'
+                    ? Object.keys(painCandidates.candidates).length
+                    : null,
+                lastSignal: lastPainSignal,
+            },
+            gate: gateStats,
+            // D: Heartbeat Diagnostician chain
+            runtimeDiagnosis,
+            ...(workflowFunnelsOutput && { workflowFunnels: workflowFunnelsOutput }),
+            metadata: {
+                generatedAt,
+                workspaceDir,
+                sessionId: selectedSessionId,
+                selectedSessionReason: selectedSession.reason,
+                status,
+                warnings,
+            },
+        };
+    }
+    static readSessions(sessionDir, warnings) {
+        if (!fs.existsSync(sessionDir)) {
+            pushWarning(warnings, 'No persisted session directory exists yet; session-scoped runtime state is unavailable.');
+            return [];
+        }
+        const sessions = [];
+        for (const file of fs.readdirSync(sessionDir)) {
+            if (!file.endsWith('.json'))
+                continue;
+            try {
+                const raw = fs.readFileSync(path.join(sessionDir, file), 'utf8');
+                const parsed = JSON.parse(raw);
+                if (parsed?.sessionId) {
+                    sessions.push(parsed);
+                }
+            }
+            catch {
+                pushWarning(warnings, `Failed to parse session snapshot: ${file}`);
+            }
+        }
+        return sessions.sort((a, b) => this.resolveSessionSortTime(b) - this.resolveSessionSortTime(a));
+    }
+    static selectSession(sessions, explicitSessionId) {
+        if (explicitSessionId) {
+            const explicit = sessions.find((session) => session.sessionId === explicitSessionId) ?? null;
+            return { session: explicit, reason: explicit ? 'explicit' : 'none' };
+        }
+        if (sessions.length === 0) {
+            return { session: null, reason: 'none' };
+        }
+        return { session: sessions[0], reason: 'latest_active' };
+    }
+    static mergeSessionSnapshots(persistedSessions, workspaceDir) {
+        const merged = new Map();
+        for (const session of persistedSessions) {
+            merged.set(session.sessionId, { ...session });
+        }
+        for (const live of listSessions(workspaceDir)) {
+            const persisted = merged.get(live.sessionId);
+            merged.set(live.sessionId, {
+                sessionId: live.sessionId,
+                currentGfi: Number.isFinite(live.currentGfi) ? Number(live.currentGfi) : persisted?.currentGfi,
+                gfiBySource: live.gfiBySource ? { ...live.gfiBySource } : persisted?.gfiBySource,
+                lastErrorSource: live.lastErrorSource || persisted?.lastErrorSource,
+                consecutiveErrors: Number.isFinite(live.consecutiveErrors) ? Number(live.consecutiveErrors) : persisted?.consecutiveErrors,
+                lastGfiDecayAt: live.lastGfiDecayAt || persisted?.lastGfiDecayAt,
+                dailyGfiPeak: Number.isFinite(live.dailyGfiPeak) ? Number(live.dailyGfiPeak) : persisted?.dailyGfiPeak,
+                lastActivityAt: Number.isFinite(live.lastActivityAt) ? Number(live.lastActivityAt) : persisted?.lastActivityAt,
+                lastControlActivityAt: Number.isFinite(live.lastControlActivityAt)
+                    ? Number(live.lastControlActivityAt)
+                    : persisted?.lastControlActivityAt,
+            });
+        }
+        return [...merged.values()].sort((a, b) => this.resolveSessionSortTime(b) - this.resolveSessionSortTime(a));
+    }
+    static buildQueueStats(queue) {
+        const stats = { pending: 0, inProgress: 0, completed: 0 };
+        if (!queue)
+            return stats;
+        for (const item of queue) {
+            if (item?.status === 'completed') {
+                stats.completed++;
+            }
+            else if (item?.status === 'in_progress') {
+                stats.inProgress++;
+            }
+            else {
+                stats.pending++;
+            }
+        }
+        return stats;
+    }
+    /**
+     * Builds directive summary for compatibility display only.
+     * NOT a truth source for Phase 3 eligibility or decisions.
+     * Queue is the only authoritative execution truth source.
+     */
+    static buildDirectiveSummary(queue, directive, generatedAt, warnings) {
+        const inProgressTask = this.selectInProgressTask(queue);
+        if (!inProgressTask) {
+            if (directive) {
+                this.warnOnLegacyDirectiveMismatch(directive, null, warnings);
+            }
+            return {
+                exists: false,
+                active: null,
+                ageSeconds: null,
+                taskPreview: null,
+            };
+        }
+        const derivedTaskPreview = this.buildDirectiveTaskPreview(inProgressTask);
+        const timestampMs = this.resolveDirectiveTimestamp(inProgressTask);
+        const ageSeconds = Number.isFinite(timestampMs)
+            ? Math.max(0, Math.floor((new Date(generatedAt).getTime() - timestampMs) / 1000))
+            : null;
+        if (directive) {
+            this.warnOnLegacyDirectiveMismatch(directive, {
+                active: true,
+                taskPreview: derivedTaskPreview,
+                taskId: inProgressTask.taskId ?? inProgressTask.id ?? null,
+            }, warnings);
+        }
+        return {
+            exists: true,
+            active: true,
+            ageSeconds,
+            taskPreview: derivedTaskPreview,
+        };
+    }
+    static readEvents(logsDir, warnings) {
+        // The event log is stored as daily files: events_YYYY-MM-DD.jsonl.
+        // Prefer today's file; fall back to the most recent daily file so that
+        // gate/pain stats are still populated when the day rolled over.
+        const dir = logsDir;
+        let bestFile = null;
+        if (fs.existsSync(dir)) {
+            const today = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+            // Prefer exact match on today's file
+            const todayFile = path.join(dir, `events_${today}.jsonl`);
+            if (fs.existsSync(todayFile)) {
+                bestFile = todayFile;
+            }
+            else {
+                // Fallback: pick the most recent file by date embedded in the filename
+                // (lexical comparison works for ISO dates YYYY-MM-DD).
+                let newestDate = '';
+                try {
+                    for (const file of fs.readdirSync(dir)) {
+                        const m = file.match(/^events_(\d{4}-\d{2}-\d{2})\.jsonl$/);
+                        if (!m)
+                            continue;
+                        const fileDate = m[1];
+                        if (fileDate > newestDate) {
+                            newestDate = fileDate;
+                            bestFile = path.join(dir, file);
+                        }
+                    }
+                }
+                catch { /* ignore scan errors */ }
+            }
+        }
+        if (!bestFile) {
+            pushWarning(warnings, 'No event log file found; recent pain and gate summaries are partial. ' +
+                'Expected format: events_YYYY-MM-DD.jsonl in the logs directory.');
+            return [];
+        }
+        try {
+            const raw = fs.readFileSync(bestFile, 'utf8').trim();
+            if (!raw)
+                return [];
+            let parseFailures = 0;
+            const entries = raw
+                .split('\n')
+                .map((line) => {
+                try {
+                    return JSON.parse(line);
+                }
+                catch {
+                    parseFailures += 1;
+                    return null;
+                }
+            })
+                .filter((entry) => entry !== null);
+            if (parseFailures > 0) {
+                pushWarning(warnings, `Skipped ${parseFailures} malformed event line${parseFailures === 1 ? '' : 's'} while reading ${path.basename(bestFile)}.`);
+            }
+            return entries;
+        }
+        catch {
+            pushWarning(warnings, `Failed to read ${path.basename(bestFile)}; recent pain and gate summaries are partial.`);
+            return [];
+        }
+    }
+    static buildGfiSources(events, sessionId) {
+        const filtered = events
+            .filter((entry) => {
+            if (sessionId && entry.sessionId !== sessionId)
+                return false;
+            return (entry.type === 'pain_signal' ||
+                (entry.type === 'tool_call' && entry.category === 'failure'));
+        })
+            .slice(-MAX_SOURCE_EVENTS)
+            .reverse();
+        return filtered.map((entry) => {
+            if (entry.type === 'pain_signal') {
+                return {
+                    source: String(entry.data?.source ?? 'pain_signal'),
+                    score: this.asFiniteNumber(entry.data?.score),
+                    ts: entry.ts,
+                    confidence: this.asFiniteNumber(entry.data?.confidence),
+                    origin: typeof entry.data?.origin === 'string' ? entry.data.origin : undefined,
+                };
+            }
+            return {
+                source: `tool_failure:${String(entry.data?.toolName ?? 'unknown')}`,
+                score: this.asFiniteNumber(entry.data?.gfiAfter ?? entry.data?.gfi),
+                ts: entry.ts,
+            };
+        });
+    }
+    static findLastPainSignal(events, sessionId) {
+        for (let i = events.length - 1; i >= 0; i--) {
+            const entry = events[i];
+            if (entry.type !== 'pain_signal')
+                continue;
+            if (sessionId && entry.sessionId !== sessionId)
+                continue;
+            return {
+                source: String(entry.data?.source ?? 'pain_signal'),
+                ts: entry.ts ?? null,
+                reason: typeof entry.data?.reason === 'string' ? entry.data.reason : null,
+            };
+        }
+        return null;
+    }
+    static buildGateStats(events, sessionId, warnings) {
+        const scoped = events.filter((entry) => {
+            if (sessionId && entry.sessionId !== sessionId)
+                return false;
+            return entry.type === 'gate_block' || entry.type === 'gate_bypass';
+        });
+        if (scoped.length === 0) {
+            pushWarning(warnings, 'Gate block counts before Phase 1 may be incomplete because older block events were not recorded to event-log.');
+        }
+        return {
+            recentBlocks: scoped.filter((entry) => entry.type === 'gate_block').length,
+            recentBypasses: scoped.filter((entry) => entry.type === 'gate_bypass').length,
+            dataQuality: scoped.length > 0 ? 'authoritative' : 'partial',
+        };
+    }
+    static resolveSessionSortTime(session) {
+        return session.lastControlActivityAt ?? session.lastActivityAt ?? 0;
+    }
+    static mergeEvents(persistedEvents, bufferedEvents) {
+        const merged = new Map();
+        for (const entry of [...persistedEvents, ...bufferedEvents]) {
+            merged.set(this.getEventDedupKey(entry), entry);
+        }
+        return [...merged.values()].sort((a, b) => (a.ts || '').localeCompare(b.ts || ''));
+    }
+    static getEventDedupKey(entry) {
+        const eventId = typeof entry.data?.eventId === 'string' ? entry.data.eventId : null;
+        if (eventId) {
+            return `${entry.type}:${entry.sessionId ?? 'none'}:${eventId}`;
+        }
+        return [
+            entry.ts ?? 'no-ts',
+            entry.type ?? 'no-type',
+            entry.category ?? 'no-category',
+            entry.sessionId ?? 'no-session',
+            typeof entry.data?.source === 'string' ? entry.data.source : 'no-source',
+            typeof entry.data?.toolName === 'string' ? entry.data.toolName : 'no-tool',
+            typeof entry.data?.reason === 'string' ? entry.data.reason : 'no-reason',
+        ].join('::');
+    }
+    static resolveEvolutionDataQuality(queue) {
+        return queue ? 'authoritative' : 'partial';
+    }
+    static selectInProgressTask(queue) {
+        if (!queue || queue.length === 0)
+            return null;
+        const inProgress = queue.filter((item) => item?.status === 'in_progress');
+        if (inProgress.length === 0)
+            return null;
+        for (const item of [...inProgress].sort((a, b) => this.getQueuePriority(b) - this.getQueuePriority(a))) {
+            if (this.isResolvableEvolutionTask(item)) {
+                return item;
+            }
+        }
+        return null;
+    }
+    static getQueuePriority(item) {
+        return Number.isFinite(item.score) ? Number(item.score) : 0;
+    }
+    static isResolvableEvolutionTask(item) {
+        const rawTask = typeof item.task === 'string' ? item.task.trim() : '';
+        if (rawTask && rawTask.toLowerCase() !== 'undefined') {
+            return true;
+        }
+        return typeof item.id === 'string' && item.id.trim().length > 0;
+    }
+    static resolveDirectiveTimestamp(item) {
+        const candidate = item.started_at || item.enqueued_at || item.timestamp || null;
+        return candidate ? new Date(candidate).getTime() : NaN;
+    }
+    static buildDirectiveTaskPreview(item) {
+        const task = typeof item.task === 'string' ? item.task.trim() : '';
+        if (task && task.toLowerCase() !== 'undefined') {
+            return task.slice(0, 160);
+        }
+        const triggerTextPreview = typeof item.trigger_text_preview === 'string' ? item.trigger_text_preview.trim() : '';
+        const taskId = typeof item.taskId === 'string' && item.taskId.trim()
+            ? item.taskId.trim()
+            : typeof item.id === 'string' && item.id.trim()
+                ? item.id.trim()
+                : 'unknown';
+        const source = typeof item.source === 'string' && item.source.trim() ? item.source.trim() : 'unknown';
+        const reason = typeof item.reason === 'string' && item.reason.trim() ? item.reason.trim() : 'Systemic pain detected';
+        const preview = triggerTextPreview || 'N/A';
+        return `Diagnose systemic pain [ID: ${taskId}]. Source: ${source}. Reason: ${reason}. Trigger text: "${preview}"`.slice(0, 160);
+    }
+    static warnOnLegacyDirectiveMismatch(directive, derived, warnings) {
+        const legacyActive = typeof directive.active === 'boolean' ? directive.active : null;
+        const legacyTask = typeof directive.task === 'string' && directive.task.trim() ? directive.task.trim().slice(0, 160) : null;
+        const legacyTaskId = typeof directive.taskId === 'string' && directive.taskId.trim() ? directive.taskId.trim() : null;
+        const mismatchDetails = [];
+        if (derived === null) {
+            if (legacyActive === true || legacyTask || legacyTaskId) {
+                mismatchDetails.push('legacy directive exists but queue has no in_progress task');
+            }
+        }
+        else {
+            if (legacyActive !== null && legacyActive !== derived.active) {
+                mismatchDetails.push(`active=${String(legacyActive)} vs queue=${String(derived.active)}`);
+            }
+            if (legacyTask && derived.taskPreview && legacyTask !== derived.taskPreview) {
+                mismatchDetails.push('task text differs');
+            }
+            if (legacyTaskId && derived.taskId && legacyTaskId !== derived.taskId) {
+                mismatchDetails.push('task id differs');
+            }
+        }
+        if (mismatchDetails.length > 0) {
+            pushWarning(warnings, `Legacy directive file disagrees with queue-derived evolution state; queue is authoritative (${mismatchDetails.join(', ')}).`);
+        }
+    }
+    static readJsonFile(filePath, warnings, warnOnMissing) {
+        if (!fs.existsSync(filePath)) {
+            if (warnOnMissing) {
+                pushWarning(warnings, `Missing expected file: ${path.basename(filePath)}`);
+            }
+            return null;
+        }
+        try {
+            return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        }
+        catch {
+            pushWarning(warnings, `Failed to parse ${path.basename(filePath)}.`);
+            return null;
+        }
+    }
+    static asFiniteNumber(value) {
+        return Number.isFinite(value) ? Number(value) : undefined;
+    }
+    /**
+     * Read trajectory analytics data from trajectory database.
+     *
+     * Returns: Analytics data (historical metrics) aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
+    static readTrajectoryStats(workspaceDir, warnings) {
+        try {
+            // Use transient database instance to avoid locking issues
+            const stats = TrajectoryRegistry.use(workspaceDir, (db) => db.getDataStats());
+            return {
+                assistantTurns: stats.assistantTurns,
+                userTurns: stats.userTurns,
+                toolCalls: stats.toolCalls,
+                failures: stats.painEvents, // Approximate failures from pain events
+                lastIngestAt: stats.lastIngestAt,
+            };
+        }
+        catch (error) {
+            pushWarning(warnings, `Failed to read trajectory analytics: ${error instanceof Error ? error.message : String(error)}`);
+            return {
+                assistantTurns: 0,
+                userTurns: 0,
+                toolCalls: 0,
+                failures: 0,
+                lastIngestAt: null,
+            };
+        }
+    }
+}

package/plugin/dist/service/subagent-workflow/index.d.ts

@@ -0,0 +1,3 @@
+export { isExpectedSubagentError } from './subagent-error-utils.js';
+export { WorkflowStore, type WorkflowStoreOptions } from './workflow-store.js';
+export type { WorkflowState, WorkflowTransport, WorkflowMetadata, WorkflowResultContext, WorkflowPersistContext, WorkflowHandle, SubagentWorkflowSpec, WorkflowRow, WorkflowEventRow, WorkflowDebugSummary, } from './types.js';

package/plugin/dist/service/subagent-workflow/index.js

@@ -0,0 +1,2 @@
+export { isExpectedSubagentError } from './subagent-error-utils.js';
+export { WorkflowStore } from './workflow-store.js';

package/plugin/dist/service/subagent-workflow/subagent-error-utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared utility for detecting expected subagent unavailability errors.
+ * These occur during cron jobs, boot sessions, daemon mode, or isolated sessions
+ * where the gateway request context is not available.
+ *
+ * Callers should suppress warnings for these errors — they are not real failures.
+ */
+export declare function isExpectedSubagentError(err: unknown): boolean;

package/plugin/dist/service/subagent-workflow/subagent-error-utils.js

@@ -0,0 +1,23 @@
+/**
+ * Shared utility for detecting expected subagent unavailability errors.
+ * These occur during cron jobs, boot sessions, daemon mode, or isolated sessions
+ * where the gateway request context is not available.
+ *
+ * Callers should suppress warnings for these errors — they are not real failures.
+ */
+export function isExpectedSubagentError(err) {
+    const msg = String(err);
+    return (msg.includes('Plugin runtime subagent methods are only available during a gateway request') ||
+        msg.includes('cannot start workflow for boot session') ||
+        msg.includes('subagent runtime unavailable') ||
+        // #208/#209: Daemon mode — subagent process not connected
+        msg.includes('subagent is not available') ||
+        // NocturnalWorkflowManager explicit throw when subagent unavailable
+        (msg.includes('NocturnalWorkflowManager') && msg.includes('subagent runtime unavailable')) ||
+        // Gateway not running (daemon/cron context)
+        msg.includes('gateway is not running') ||
+        // Process isolation in cron jobs
+        msg.includes('process isolation') ||
+        // Review fix: Subagent connection issues in daemon mode (more specific to reduce false positives)
+        (msg.includes('subagent') && msg.toLowerCase().includes('connection') && (msg.includes('refused') || msg.includes('reset') || msg.includes('econnrefused'))));
+}