@cleocode/cleo 2026.4.10 → 2026.4.12

package/dist/dispatch/engines/system-engine.js

@@ -0,0 +1,1258 @@
+/**
+ * System Engine
+ *
+ * Thin wrapper layer that delegates to core modules.
+ * All business logic lives in src/core/.
+ *
+ * Read-only queries: dash, stats, labels, archive-stats, log, context, sequence,
+ *   metrics, health, diagnostics, help, roadmap, compliance
+ * Mutate operations: inject.generate, backup, restore, migrate, cleanup, audit,
+ *   sync, safestop, uncancel
+ *
+ * @task T4631
+ * @task T4783
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { auditData, cleanupSystem, systemCreateBackup as createBackup, ensureCleoOsHub, generateInjection, getAccessor, getArchiveStats, getCleoCantWorkflowsDir, getCleoConfigDir, getCleoGlobalAgentsDir, getCleoGlobalJustfilePath, getCleoGlobalRecipesDir, getCleoHome, getCleoPiExtensionsDir, getDashboard, getLabels, getMigrationStatus, getProjectStats, getRoadmap, getRuntimeDiagnostics, getSystemDiagnostics, getSystemHealth, getSystemMetrics, listSystemBackups, repairSequence, restoreBackup, safestop, uncancelTask, } from '@cleocode/core/internal';
+import { cleoErrorToEngineError, engineError } from './_error.js';
+// ===== Help topics (static data, stays in engine) =====
+const HELP_TOPICS = {
+    session: {
+        topic: 'session',
+        content: [
+            'Session Management',
+            '',
+            '  cleosession list                        - List all sessions',
+            '  cleosession start --scope epic:T001     - Start session',
+            '  cleosession end --note "Progress"       - End session',
+            '  cleosession resume <id>                 - Resume session',
+        ].join('\n'),
+        relatedCommands: ['cleo session list', 'cleo session start', 'cleo session end'],
+    },
+    tasks: {
+        topic: 'tasks',
+        content: [
+            'Task Operations',
+            '',
+            '  cleoadd "Title" --desc "Description"    - Create task',
+            '  cleoupdate T1234 --status active        - Update task',
+            '  cleocomplete T1234                      - Complete task',
+            '  cleofind "query"                        - Search tasks',
+            '  cleoshow T1234                          - Show task details',
+        ].join('\n'),
+        relatedCommands: ['cleo add', 'cleo update', 'cleo complete', 'cleo find', 'cleo show'],
+    },
+    focus: {
+        topic: 'focus',
+        content: [
+            'Task Work Management',
+            '',
+            '  cleostart T1234    - Start working on task',
+            '  cleocurrent        - Show current task',
+            '  cleostop           - Stop working on current task',
+        ].join('\n'),
+        relatedCommands: ['cleo start', 'cleo current', 'cleo stop'],
+    },
+    labels: {
+        topic: 'labels',
+        content: [
+            'Label Operations',
+            '',
+            '  cleolabels              - List all labels',
+            '  cleolabels show <name>  - Show tasks with label',
+        ].join('\n'),
+        relatedCommands: ['cleo labels'],
+    },
+    compliance: {
+        topic: 'compliance',
+        content: [
+            'Compliance Monitoring',
+            '',
+            '  cleocompliance summary     - Compliance overview',
+            '  cleocompliance violations  - List violations',
+            '  cleocompliance trend       - Compliance trend',
+        ].join('\n'),
+        relatedCommands: ['cleo compliance summary', 'cleo compliance violations'],
+    },
+};
+// ===== Dashboard =====
+/**
+ * Project dashboard: task counts by status, active session info,
+ * current focus, recent completions.
+ *
+ * @remarks
+ * This is the primary overview endpoint for the CLEO CLI `dash` command.
+ * It aggregates task counts, current session/focus state, high-priority tasks,
+ * blocked tasks, and recent completions into a single response.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param params - Optional parameters to control blocked tasks display limit
+ * @returns EngineResult with comprehensive dashboard data
+ *
+ * @example
+ * ```typescript
+ * const result = await systemDash('/project', { blockedTasksLimit: 5 });
+ * ```
+ */
+export async function systemDash(projectRoot, params) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const result = await getDashboard({ cwd: projectRoot, blockedTasksLimit: params?.blockedTasksLimit }, accessor);
+        // Add missing fields that core doesn't produce
+        const data = result;
+        const summary = data.summary;
+        return {
+            success: true,
+            data: {
+                project: data.project,
+                currentPhase: data.currentPhase,
+                summary: {
+                    pending: summary.pending,
+                    active: summary.active,
+                    blocked: summary.blocked,
+                    done: summary.done,
+                    cancelled: summary.cancelled ?? 0,
+                    total: summary.total,
+                    archived: summary.archived ?? 0,
+                    grandTotal: summary.grandTotal ?? summary.total,
+                },
+                taskWork: (data.focus ?? data.taskWork),
+                activeSession: data.activeSession ?? null,
+                highPriority: data.highPriority,
+                blockedTasks: data.blockedTasks,
+                recentCompletions: (data.recentCompletions ?? []),
+                topLabels: data.topLabels,
+            },
+        };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_NOT_INITIALIZED', 'System not initialized');
+    }
+}
+// ===== Stats =====
+/**
+ * Detailed statistics: tasks by status/priority/type/phase,
+ * completion rate, average cycle time.
+ */
+export async function systemStats(projectRoot, params) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const result = await getProjectStats({ period: String(params?.period ?? 30), cwd: projectRoot }, accessor);
+        // Core stats lacks byPriority, byType, byPhase, cycleTimes — fill from accessor
+        const queryResult = await accessor.queryTasks({});
+        const tasks = queryResult?.tasks ?? [];
+        // Distribution breakdowns: active tasks only (exclude cancelled — not actionable work)
+        const activeTasks = tasks.filter((t) => t.status !== 'cancelled');
+        const byPriority = {};
+        for (const t of activeTasks) {
+            byPriority[t.priority] = (byPriority[t.priority] ?? 0) + 1;
+        }
+        const byType = {};
+        for (const t of activeTasks) {
+            const type = t.type || 'task';
+            byType[type] = (byType[type] ?? 0) + 1;
+        }
+        const byPhase = {};
+        for (const t of activeTasks) {
+            const phase = t.phase || 'unassigned';
+            byPhase[phase] = (byPhase[phase] ?? 0) + 1;
+        }
+        // Cycle times
+        const completedTasks = tasks.filter((t) => t.status === 'done' && t.completedAt && t.createdAt);
+        let totalCycleDays = 0;
+        let samples = 0;
+        for (const t of completedTasks) {
+            const created = new Date(t.createdAt).getTime();
+            const completed = new Date(t.completedAt).getTime();
+            if (completed > created) {
+                totalCycleDays += (completed - created) / 86400000;
+                samples++;
+            }
+        }
+        const averageDays = samples > 0 ? Math.round((totalCycleDays / samples) * 100) / 100 : null;
+        const coreData = result;
+        const currentState = coreData.currentState;
+        const completionMetrics = coreData.completionMetrics;
+        const activityMetrics = coreData.activityMetrics;
+        const allTime = coreData.allTime;
+        return {
+            success: true,
+            data: {
+                currentState: {
+                    pending: currentState.pending,
+                    active: currentState.active,
+                    done: currentState.done,
+                    blocked: currentState.blocked,
+                    cancelled: tasks.filter((t) => t.status === 'cancelled').length,
+                    totalActive: currentState.totalActive,
+                    archived: currentState.archived ?? 0,
+                    grandTotal: currentState.grandTotal ?? currentState.totalActive,
+                },
+                byPriority,
+                byType,
+                byPhase,
+                completionMetrics: completionMetrics,
+                activityMetrics: activityMetrics,
+                allTime: allTime,
+                cycleTimes: { averageDays, samples },
+            },
+        };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_NOT_INITIALIZED', 'Failed to get stats');
+    }
+}
+// ===== Labels =====
+/**
+ * List all unique labels across tasks with counts and task IDs per label.
+ */
+export async function systemLabels(projectRoot) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const result = await getLabels(projectRoot, accessor);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_NOT_INITIALIZED', 'Failed to get labels');
+    }
+}
+// ===== Archive Stats =====
+/**
+ * Archive metrics: total archived, by reason, average cycle time, archive rate.
+ */
+export async function systemArchiveStats(projectRoot, params) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const result = await getArchiveStats({ period: params?.period, cwd: projectRoot }, accessor);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_NOT_INITIALIZED', 'Failed to get archive stats');
+    }
+}
+// ===== Log =====
+/**
+ * Query audit log with optional filters.
+ * Reads from SQLite audit_log table.
+ *
+ * @task T4837
+ */
+export async function systemLog(projectRoot, filters) {
+    try {
+        // Canonical path: SQLite audit_log table.
+        const entries = await queryAuditLogSqlite(projectRoot, filters);
+        return { success: true, data: entries };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_FILE_ERROR', 'Failed to read audit log');
+    }
+}
+/**
+ * Query audit_log from SQLite.
+ * Includes dispatch-level fields (domain, requestId, durationMs, success,
+ * source, gateway, errorMessage) when present (T4844).
+ *
+ * @task T4837
+ * @task T4844
+ */
+async function queryAuditLogSqlite(projectRoot, filters) {
+    try {
+        const { join } = await import('node:path');
+        const { existsSync } = await import('node:fs');
+        const dbPath = join(projectRoot, '.cleo', 'tasks.db');
+        if (!existsSync(dbPath)) {
+            const offset = filters?.offset ?? 0;
+            const limit = filters?.limit ?? 20;
+            return {
+                entries: [],
+                pagination: { total: 0, offset, limit, hasMore: false },
+            };
+        }
+        const { getDb } = await import('@cleocode/core/internal');
+        const { auditLog } = await import('@cleocode/core/internal');
+        const { sql } = await import('drizzle-orm');
+        const db = await getDb(projectRoot);
+        // Check if audit_log table exists and has data
+        try {
+            // Build dynamic WHERE conditions
+            const conditions = [];
+            if (filters?.operation) {
+                // Match against both legacy 'action' column and new 'operation' column
+                conditions.push(sql `(${auditLog.action} = ${filters.operation} OR ${auditLog.operation} = ${filters.operation})`);
+            }
+            if (filters?.taskId) {
+                conditions.push(sql `${auditLog.taskId} = ${filters.taskId}`);
+            }
+            if (filters?.since) {
+                conditions.push(sql `${auditLog.timestamp} >= ${filters.since}`);
+            }
+            if (filters?.until) {
+                conditions.push(sql `${auditLog.timestamp} <= ${filters.until}`);
+            }
+            const whereClause = conditions.length > 0 ? sql.join(conditions, sql ` AND `) : sql `1=1`;
+            // Count total matching entries
+            const countResult = await db.all(sql `SELECT count(*) as cnt FROM ${auditLog} WHERE ${whereClause}`);
+            const total = countResult[0]?.cnt ?? 0;
+            if (total === 0) {
+                return {
+                    entries: [],
+                    pagination: {
+                        total: 0,
+                        offset: filters?.offset ?? 0,
+                        limit: filters?.limit ?? 20,
+                        hasMore: false,
+                    },
+                };
+            }
+            const offset = filters?.offset ?? 0;
+            const limit = filters?.limit ?? 20;
+            // Fetch paginated results (includes dispatch-level columns)
+            const rows = await db.all(sql `SELECT * FROM ${auditLog}
+            WHERE ${whereClause}
+            ORDER BY ${auditLog.timestamp} DESC
+            LIMIT ${limit} OFFSET ${offset}`);
+            const entries = rows.map((row) => ({
+                operation: row.operation ?? row.action,
+                taskId: row.task_id,
+                timestamp: row.timestamp,
+                actor: row.actor,
+                details: row.details_json ? JSON.parse(row.details_json) : {},
+                before: row.before_json ? JSON.parse(row.before_json) : undefined,
+                after: row.after_json ? JSON.parse(row.after_json) : undefined,
+                // Dispatch-level fields (may be null for legacy task-only entries)
+                ...(row.domain != null && {
+                    domain: row.domain,
+                    sessionId: row.session_id,
+                    requestId: row.request_id,
+                    durationMs: row.duration_ms,
+                    success: row.success === 1,
+                    source: row.source,
+                    gateway: row.gateway,
+                    error: row.error_message,
+                }),
+            }));
+            return {
+                entries,
+                pagination: { total, offset, limit, hasMore: offset + limit < total },
+            };
+        }
+        catch {
+            const offset = filters?.offset ?? 0;
+            const limit = filters?.limit ?? 20;
+            return {
+                entries: [],
+                pagination: { total: 0, offset, limit, hasMore: false },
+            };
+        }
+    }
+    catch {
+        const offset = filters?.offset ?? 0;
+        const limit = filters?.limit ?? 20;
+        return {
+            entries: [],
+            pagination: { total: 0, offset, limit, hasMore: false },
+        };
+    }
+}
+// ===== Context =====
+/**
+ * Context window tracking: estimate token usage from current session/state.
+ */
+export function systemContext(projectRoot, params) {
+    try {
+        const cleoDir = join(projectRoot, '.cleo');
+        // Resolve state file
+        let stateFile;
+        if (params?.session) {
+            const sessionFile = join(cleoDir, 'context-states', `context-state-${params.session}.json`);
+            stateFile = existsSync(sessionFile) ? sessionFile : join(cleoDir, '.context-state.json');
+        }
+        else {
+            const currentSessionPath = join(cleoDir, '.current-session');
+            if (existsSync(currentSessionPath)) {
+                const currentSession = readFileSync(currentSessionPath, 'utf-8').trim();
+                if (currentSession) {
+                    const sessionFile = join(cleoDir, 'context-states', `context-state-${currentSession}.json`);
+                    stateFile = existsSync(sessionFile) ? sessionFile : join(cleoDir, '.context-state.json');
+                }
+                else {
+                    stateFile = join(cleoDir, '.context-state.json');
+                }
+            }
+            else {
+                stateFile = join(cleoDir, '.context-state.json');
+            }
+        }
+        // Collect session files
+        const sessions = [];
+        const statesDir = join(cleoDir, 'context-states');
+        if (existsSync(statesDir)) {
+            for (const file of readdirSync(statesDir)) {
+                if (file.startsWith('context-state-') && file.endsWith('.json')) {
+                    try {
+                        const state = JSON.parse(readFileSync(join(statesDir, file), 'utf-8'));
+                        sessions.push({
+                            file: basename(file),
+                            sessionId: state.sessionId ?? null,
+                            percentage: state.contextWindow?.percentage ?? 0,
+                            status: state.status ?? 'unknown',
+                            timestamp: state.timestamp,
+                        });
+                    }
+                    catch {
+                        // skip invalid files
+                    }
+                }
+            }
+        }
+        const singletonFile = join(cleoDir, '.context-state.json');
+        if (existsSync(singletonFile)) {
+            try {
+                const state = JSON.parse(readFileSync(singletonFile, 'utf-8'));
+                sessions.push({
+                    file: '.context-state.json',
+                    sessionId: state.sessionId ?? 'global',
+                    percentage: state.contextWindow?.percentage ?? 0,
+                    status: state.status ?? 'unknown',
+                    timestamp: state.timestamp,
+                });
+            }
+            catch {
+                // skip
+            }
+        }
+        if (!existsSync(stateFile)) {
+            return {
+                success: true,
+                data: {
+                    available: false,
+                    status: 'unavailable',
+                    percentage: 0,
+                    currentTokens: 0,
+                    maxTokens: 0,
+                    timestamp: null,
+                    stale: true,
+                    sessions,
+                },
+            };
+        }
+        try {
+            const state = JSON.parse(readFileSync(stateFile, 'utf-8'));
+            const timestamp = state.timestamp;
+            const staleMs = state.staleAfterMs ?? 5000;
+            const percentage = state.contextWindow?.percentage ?? 0;
+            const current = state.contextWindow?.currentTokens ?? 0;
+            const max = state.contextWindow?.maxTokens ?? 0;
+            let status = state.status ?? 'unknown';
+            const fileTime = new Date(timestamp).getTime();
+            if (Date.now() - fileTime > staleMs) {
+                status = 'stale';
+            }
+            return {
+                success: true,
+                data: {
+                    available: true,
+                    status,
+                    percentage,
+                    currentTokens: current,
+                    maxTokens: max,
+                    timestamp,
+                    stale: status === 'stale',
+                    sessions,
+                },
+            };
+        }
+        catch {
+            return {
+                success: true,
+                data: {
+                    available: false,
+                    status: 'error',
+                    percentage: 0,
+                    currentTokens: 0,
+                    maxTokens: 0,
+                    timestamp: null,
+                    stale: true,
+                    sessions,
+                },
+            };
+        }
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_GENERAL', 'System operation failed');
+    }
+}
+// ===== Sequence =====
+/**
+ * Read task ID sequence state from canonical SQLite metadata.
+ * Supports 'show' and 'check' actions.
+ * @task T4815
+ */
+export async function systemSequence(projectRoot, params) {
+    const { showSequence, checkSequence } = await import('@cleocode/core/internal');
+    try {
+        const action = params?.action ?? 'show';
+        if (action === 'check') {
+            const check = await checkSequence(projectRoot);
+            return { success: true, data: check };
+        }
+        const seq = await showSequence(projectRoot);
+        return {
+            success: true,
+            data: {
+                counter: Number(seq.counter ?? 0),
+                lastId: String(seq.lastId ?? ''),
+                checksum: String(seq.checksum ?? ''),
+                nextId: String(seq.nextId ?? ''),
+            },
+        };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_NOT_FOUND', 'Sequence not found');
+    }
+}
+// ===== Inject Generate (MVI) =====
+/**
+ * Generate Minimum Viable Injection (MVI).
+ */
+export async function systemInjectGenerate(projectRoot) {
+    try {
+        const root = projectRoot || process.cwd();
+        const accessor = await getAccessor(root);
+        const result = await generateInjection(root, accessor);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_GENERAL', 'Failed to generate injection');
+    }
+}
+// ===== Metrics =====
+/**
+ * System metrics: token usage, compliance summary, session counts.
+ * @task T4631
+ */
+export async function systemMetrics(projectRoot, params) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const result = await getSystemMetrics(projectRoot, params, accessor);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_GENERAL', 'Failed to get metrics');
+    }
+}
+// ===== Health =====
+/**
+ * System health check: verify core data files exist and are valid.
+ * @task T4631
+ */
+export async function systemHealth(projectRoot, params) {
+    try {
+        const result = await getSystemHealth(projectRoot, params);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_GENERAL', 'Failed to get health');
+    }
+}
+// ===== Diagnostics =====
+/**
+ * System diagnostics: extended health checks with fix suggestions.
+ * @task T4631
+ */
+export async function systemDiagnostics(projectRoot, params) {
+    try {
+        const result = await getSystemDiagnostics(projectRoot, params);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_GENERAL', 'Failed to get diagnostics');
+    }
+}
+// ===== Help =====
+/**
+ * Return help text for the system.
+ * @task T4631
+ */
+export function systemHelp(_projectRoot, params) {
+    const topic = params?.topic;
+    if (topic) {
+        const topicHelp = HELP_TOPICS[topic];
+        if (topicHelp) {
+            return { success: true, data: topicHelp };
+        }
+        return engineError('E_NOT_FOUND', `Unknown help topic: ${topic}. Available topics: ${Object.keys(HELP_TOPICS).join(', ')}`);
+    }
+    return {
+        success: true,
+        data: {
+            content: [
+                'CLEO Task Management System',
+                '',
+                'Essential Commands:',
+                '  cleofind "query"    - Fuzzy search tasks',
+                '  cleoshow T1234      - Full task details',
+                '  cleoadd "Task"      - Create task',
+                '  cleodone <id>       - Complete task',
+                '  cleostart <id>      - Start working on task',
+                '  cleodash            - Project overview',
+                '  cleosession list    - List sessions',
+                '',
+                'Help Topics: session, tasks, focus, labels, compliance',
+            ].join('\n'),
+            relatedCommands: ['cleo find', 'cleo show', 'cleo add', 'cleo done', 'cleo dash'],
+        },
+    };
+}
+// ===== Roadmap =====
+/**
+ * Generate roadmap from pending epics and optional CHANGELOG history.
+ * @task T4631
+ */
+export async function systemRoadmap(projectRoot, params) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const result = await getRoadmap({
+            includeHistory: params?.includeHistory,
+            upcomingOnly: params?.upcomingOnly,
+            cwd: projectRoot,
+        }, accessor);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_NOT_INITIALIZED', 'System not initialized');
+    }
+}
+// ===== Compliance =====
+/**
+ * System compliance report from COMPLIANCE.jsonl.
+ * @task T4631
+ */
+export function systemCompliance(projectRoot, params) {
+    try {
+        if (params?.subcommand === 'trend') {
+            const compliancePath = join(projectRoot, '.cleo', 'metrics', 'COMPLIANCE.jsonl');
+            let entries = [];
+            if (existsSync(compliancePath)) {
+                const content = readFileSync(compliancePath, 'utf-8').trim();
+                if (content) {
+                    entries = content
+                        .split('\n')
+                        .filter((l) => l.trim())
+                        .map((l) => JSON.parse(l));
+                }
+            }
+            if (params.epic) {
+                entries = entries.filter((e) => {
+                    const ctx = (e._context ?? {});
+                    return ctx.epic_id === params.epic || ctx.task_id === params.epic;
+                });
+            }
+            if (params.days) {
+                const cutoff = new Date(Date.now() - params.days * 86400000).toISOString();
+                entries = entries.filter((e) => e.timestamp >= cutoff);
+            }
+            const totalEntries = entries.length;
+            const compliance = entries.map((e) => (e.compliance ?? {}));
+            const avgPassRate = totalEntries > 0
+                ? Math.round((compliance.reduce((sum, c) => sum + (c.compliance_pass_rate ?? 0), 0) /
+                    totalEntries) *
+                    1000) / 1000
+                : 0;
+            const avgAdherence = totalEntries > 0
+                ? Math.round((compliance.reduce((sum, c) => sum + (c.rule_adherence_score ?? 0), 0) /
+                    totalEntries) *
+                    1000) / 1000
+                : 0;
+            const totalViolations = compliance.reduce((sum, c) => sum + (c.violation_count ?? 0), 0);
+            const byDate = {};
+            for (const e of entries) {
+                const date = e.timestamp.split('T')[0];
+                if (!byDate[date])
+                    byDate[date] = [];
+                byDate[date].push(e);
+            }
+            const dataPoints = Object.entries(byDate)
+                .sort(([a], [b]) => a.localeCompare(b))
+                .map(([date, dayEntries]) => {
+                const dayCompliance = dayEntries.map((de) => (de.compliance ?? {}));
+                return {
+                    date,
+                    entries: dayEntries.length,
+                    avgPassRate: dayCompliance.reduce((s, c) => s + (c.compliance_pass_rate ?? 0), 0) /
+                        dayEntries.length,
+                    violations: dayCompliance.reduce((s, c) => s + (c.violation_count ?? 0), 0),
+                };
+            });
+            let trend;
+            if (dataPoints.length >= 2) {
+                const first = dataPoints[0].avgPassRate;
+                const last = dataPoints[dataPoints.length - 1].avgPassRate;
+                trend = last > first ? 'improving' : last < first ? 'declining' : 'stable';
+            }
+            else {
+                trend = 'insufficient_data';
+            }
+            return {
+                success: true,
+                data: {
+                    totalEntries,
+                    averagePassRate: avgPassRate,
+                    averageAdherence: avgAdherence,
+                    totalViolations,
+                    trend,
+                    dataPoints,
+                },
+            };
+        }
+        // Default: summary (possibly filtered by epic/days)
+        const compliancePath = join(projectRoot, '.cleo', 'metrics', 'COMPLIANCE.jsonl');
+        let entries = [];
+        if (existsSync(compliancePath)) {
+            const content = readFileSync(compliancePath, 'utf-8').trim();
+            if (content) {
+                entries = content
+                    .split('\n')
+                    .filter((l) => l.trim())
+                    .map((l) => JSON.parse(l));
+            }
+        }
+        if (params?.epic) {
+            entries = entries.filter((e) => {
+                const ctx = (e._context ?? {});
+                return ctx.epic_id === params.epic || ctx.task_id === params.epic;
+            });
+        }
+        if (params?.days) {
+            const cutoff = new Date(Date.now() - params.days * 86400000).toISOString();
+            entries = entries.filter((e) => e.timestamp >= cutoff);
+        }
+        const totalEntries = entries.length;
+        const compliance = entries.map((e) => (e.compliance ?? {}));
+        const avgPassRate = totalEntries > 0
+            ? Math.round((compliance.reduce((sum, c) => sum + (c.compliance_pass_rate ?? 0), 0) /
+                totalEntries) *
+                1000) / 1000
+            : 0;
+        const avgAdherence = totalEntries > 0
+            ? Math.round((compliance.reduce((sum, c) => sum + (c.rule_adherence_score ?? 0), 0) /
+                totalEntries) *
+                1000) / 1000
+            : 0;
+        const totalViolations = compliance.reduce((sum, c) => sum + (c.violation_count ?? 0), 0);
+        return {
+            success: true,
+            data: {
+                totalEntries,
+                averagePassRate: avgPassRate,
+                averageAdherence: avgAdherence,
+                totalViolations,
+            },
+        };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_GENERAL', 'Failed to get roadmap');
+    }
+}
+// ===== Backup =====
+/**
+ * Create a backup of CLEO data files.
+ *
+ * Async because `createBackup` (T5158) now opens tasks.db + brain.db via
+ * their drizzle accessors before snapshotting so both databases are
+ * captured even when the current CLI command path hasn't already opened
+ * them (e.g. `cleo backup add` in a fresh process).
+ *
+ * @task T4631
+ * @task T5158
+ */
+export async function systemBackup(projectRoot, params) {
+    try {
+        const result = await createBackup(projectRoot, params);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_GENERAL', 'Failed to create backup');
+    }
+}
+/**
+ * List available system backups (read-only).
+ * @task T4783
+ */
+export function systemListBackups(projectRoot) {
+    try {
+        const result = listSystemBackups(projectRoot);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_GENERAL', 'Failed to list backups');
+    }
+}
+// ===== Restore =====
+/**
+ * Restore from a backup.
+ * @task T4631
+ */
+export function systemRestore(projectRoot, params) {
+    try {
+        const result = restoreBackup(projectRoot, params);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_RESTORE_FAILED', 'Failed to restore');
+    }
+}
+/**
+ * Restore an individual file from backup.
+ * @task T5329
+ */
+export async function backupRestore(projectRoot, fileName, options) {
+    try {
+        const { getBackupDir, getTaskPath, getConfigPath } = await import('@cleocode/core/internal');
+        const { restoreFromBackup, listBackups } = await import('@cleocode/core/internal');
+        const backupDir = getBackupDir(projectRoot);
+        const targetPathMap = {
+            'tasks.db': getTaskPath,
+            'config.json': getConfigPath,
+        };
+        const pathGetter = targetPathMap[fileName];
+        if (!pathGetter) {
+            return engineError('E_INVALID_INPUT', `Unknown file: ${fileName}. Valid files: tasks.db, config.json`);
+        }
+        const targetPath = pathGetter();
+        const backups = await listBackups(fileName, backupDir);
+        if (backups.length === 0) {
+            return engineError('E_NOT_FOUND', `No backups found for ${fileName}`);
+        }
+        if (options?.dryRun) {
+            return {
+                success: true,
+                data: {
+                    restored: false,
+                    file: fileName,
+                    from: backups[0],
+                    targetPath,
+                    dryRun: true,
+                },
+            };
+        }
+        const restoredFrom = await restoreFromBackup(fileName, backupDir, targetPath);
+        return {
+            success: true,
+            data: {
+                restored: true,
+                file: fileName,
+                from: restoredFrom,
+                targetPath,
+            },
+        };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_GENERAL', 'Backup restore failed');
+    }
+}
+// ===== Migrate =====
+/**
+ * Check/run schema migrations.
+ * @task T4631
+ */
+export async function systemMigrate(projectRoot, params) {
+    try {
+        const result = await getMigrationStatus(projectRoot, params);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_MIGRATE_FAILED', 'Failed to migrate');
+    }
+}
+// ===== Cleanup =====
+/**
+ * Cleanup stale data (sessions, backups, logs).
+ * @task T4631
+ */
+export async function systemCleanup(projectRoot, params) {
+    try {
+        const result = await cleanupSystem(projectRoot, params);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_CLEANUP_FAILED', 'Failed to cleanup');
+    }
+}
+// ===== Audit =====
+/**
+ * Audit data integrity.
+ * @task T4631
+ */
+export async function systemAudit(projectRoot, params) {
+    try {
+        const result = await auditData(projectRoot, params);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_GENERAL', 'Failed to audit');
+    }
+}
+/**
+ * Sync check (no external sync targets in native mode).
+ * @task T4631
+ */
+export function systemSync(_projectRoot, params) {
+    return {
+        success: true,
+        data: {
+            direction: params?.direction ?? 'up',
+            synced: 0,
+            conflicts: 0,
+            message: 'Sync is a no-op in native mode (no external sync targets configured)',
+        },
+    };
+}
+// ===== Safestop =====
+/**
+ * Safe stop: signal clean shutdown for agents.
+ * @task T4631
+ */
+export function systemSafestop(projectRoot, params) {
+    try {
+        const result = safestop(projectRoot, params);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_GENERAL', 'Sync failed');
+    }
+}
+// ===== Uncancel =====
+/**
+ * Uncancel a cancelled task (restore to pending).
+ * @task T4631
+ */
+export async function systemUncancel(projectRoot, params) {
+    try {
+        const result = await uncancelTask(projectRoot, params);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_UNCANCEL_FAILED', 'Failed to uncancel');
+    }
+}
+// ===== Doctor Report =====
+/**
+ * Run comprehensive doctor diagnostics.
+ * @task T4795
+ */
+export async function systemDoctor(projectRoot) {
+    const { coreDoctorReport } = await import('@cleocode/core/internal');
+    try {
+        const result = await coreDoctorReport(projectRoot);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_GENERAL', 'Doctor check failed');
+    }
+}
+// ===== Doctor Fix =====
+/**
+ * Run auto-fix for failed doctor checks.
+ * @task T4795
+ */
+export async function systemFix(projectRoot) {
+    const { runDoctorFixes } = await import('@cleocode/core/internal');
+    try {
+        const result = await runDoctorFixes(projectRoot);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_GENERAL', 'Doctor fix failed');
+    }
+}
+/**
+ * Runtime/channel diagnostics for CLI installation mode checks.
+ * @task T4815
+ */
+export async function systemRuntime(_projectRoot, params) {
+    try {
+        const data = await getRuntimeDiagnostics({ detailed: params?.detailed ?? false });
+        return { success: true, data };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_RUNTIME_ERROR', 'Runtime check failed');
+    }
+}
+/**
+ * Report all resolved CleoOS paths (project + global hub).
+ *
+ * Backs the `cleo admin paths` CLI command. Read-only: reports current state
+ * without mutating the filesystem. Use `systemScaffoldHub()` to create
+ * missing hub directories and seed the starter justfile.
+ *
+ * @task Phase 1 — XDG Foundation + Justfile Hub Skeleton
+ */
+export async function systemPaths(projectRoot) {
+    try {
+        const cleoHome = getCleoHome();
+        const configDir = getCleoConfigDir();
+        const globalRecipes = getCleoGlobalRecipesDir();
+        const globalJustfile = getCleoGlobalJustfilePath();
+        const piExtensions = getCleoPiExtensionsDir();
+        const cantWorkflows = getCleoCantWorkflowsDir();
+        const globalAgents = getCleoGlobalAgentsDir();
+        return {
+            success: true,
+            data: {
+                projectCleoDir: join(projectRoot, '.cleo'),
+                cleoHome,
+                configDir,
+                hub: {
+                    globalRecipes,
+                    globalJustfile,
+                    piExtensions,
+                    cantWorkflows,
+                    globalAgents,
+                },
+                scaffolded: {
+                    globalRecipes: existsSync(globalRecipes),
+                    globalJustfile: existsSync(globalJustfile),
+                    piExtensions: existsSync(piExtensions),
+                    cantWorkflows: existsSync(cantWorkflows),
+                    globalAgents: existsSync(globalAgents),
+                },
+            },
+        };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_PATHS_RESOLVE_FAILED', 'Failed to resolve paths');
+    }
+}
+/**
+ * Create the CleoOS Hub directories and seed the starter justfile if absent.
+ *
+ * Idempotent: safe to call repeatedly. Never overwrites existing user-edited
+ * justfile or README content. Backs the `cleo admin scaffold-hub` CLI
+ * command and is invoked automatically by `cleo init` (Phase 5).
+ *
+ * @task Phase 1 — XDG Foundation + Justfile Hub Skeleton
+ */
+export async function systemScaffoldHub() {
+    try {
+        const result = await ensureCleoOsHub();
+        return { success: true, data: result };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_SCAFFOLD_HUB_FAILED', 'Failed to scaffold hub');
+    }
+}
+/**
+ * Repair task ID sequence using canonical core implementation.
+ * @task T4815
+ */
+export async function systemSequenceRepair(projectRoot) {
+    try {
+        const repair = await repairSequence(projectRoot);
+        return {
+            success: true,
+            data: {
+                repaired: repair.repaired,
+                message: repair.message,
+                counter: repair.counter,
+                oldCounter: repair.oldCounter,
+                newCounter: repair.newCounter,
+            },
+        };
+    }
+    catch (err) {
+        return cleoErrorToEngineError(err, 'E_SEQUENCE_REPAIR_FAILED', 'Failed to repair sequence');
+    }
+}
+/**
+ * Smoke-test definitions: one lightweight read-only query per domain.
+ * Each probe exercises the full dispatch pipeline (middleware, handler, engine, core).
+ */
+const SMOKE_PROBES = [
+    { domain: 'admin', operation: 'version' },
+    { domain: 'tasks', operation: 'find', params: { query: '__smoke_probe__', limit: 1 } },
+    { domain: 'session', operation: 'status' },
+    { domain: 'memory', operation: 'find', params: { query: '__smoke_probe__' } },
+    { domain: 'pipeline', operation: 'list' },
+    { domain: 'check', operation: 'schema' },
+    { domain: 'tools', operation: 'list', params: { limit: 1 } },
+    { domain: 'sticky', operation: 'list', params: { limit: 1 } },
+    { domain: 'nexus', operation: 'status' },
+    { domain: 'orchestrate', operation: 'status' },
+];
+/**
+ * Run operational smoke tests across all domains.
+ *
+ * Dispatches one read-only query per domain through the full CLI dispatch
+ * pipeline and reports pass/fail with timing. Catches crashes (TypeError,
+ * ReferenceError, etc.) not just structured error responses.
+ *
+ * @task T130
+ */
+export async function systemSmoke() {
+    const { dispatchRaw } = await import('../adapters/cli.js');
+    const totalStart = Date.now();
+    const probes = [];
+    for (const probe of SMOKE_PROBES) {
+        const start = Date.now();
+        try {
+            const response = await dispatchRaw('query', probe.domain, probe.operation, probe.params);
+            const elapsed = Date.now() - start;
+            if (response.success) {
+                probes.push({
+                    domain: probe.domain,
+                    operation: probe.operation,
+                    status: 'pass',
+                    timeMs: elapsed,
+                });
+            }
+            else {
+                // Structured error responses that are domain-specific (like "no session") are still valid
+                // operational results — the dispatch pipeline worked. Only treat E_INTERNAL / E_NO_HANDLER as failures.
+                const code = response.error?.code ?? '';
+                const isCrash = code === 'E_INTERNAL' || code === 'E_NO_HANDLER';
+                probes.push({
+                    domain: probe.domain,
+                    operation: probe.operation,
+                    status: isCrash ? 'fail' : 'pass',
+                    timeMs: elapsed,
+                    ...(isCrash ? { error: response.error?.message } : {}),
+                });
+            }
+        }
+        catch (err) {
+            const elapsed = Date.now() - start;
+            probes.push({
+                domain: probe.domain,
+                operation: probe.operation,
+                status: 'fail',
+                timeMs: elapsed,
+                error: err instanceof Error ? `${err.constructor.name}: ${err.message}` : String(err),
+            });
+        }
+    }
+    // --- DB connectivity and migration state checks ---
+    const dbChecks = [];
+    // tasks.db connectivity + integrity
+    {
+        const start = Date.now();
+        try {
+            const { getDb, getNativeDb } = await import('@cleocode/core/internal');
+            const projectRoot = (await import('@cleocode/core/internal')).getProjectRoot();
+            await getDb(projectRoot);
+            const nativeDb = getNativeDb();
+            if (nativeDb) {
+                const result = nativeDb.prepare('PRAGMA integrity_check').get();
+                const ok = result?.integrity_check === 'ok';
+                dbChecks.push({
+                    domain: 'db',
+                    operation: 'tasks.db',
+                    status: ok ? 'pass' : 'fail',
+                    timeMs: Date.now() - start,
+                    ...(!ok ? { error: 'SQLite integrity check failed' } : {}),
+                });
+            }
+            else {
+                dbChecks.push({
+                    domain: 'db',
+                    operation: 'tasks.db',
+                    status: 'fail',
+                    timeMs: Date.now() - start,
+                    error: 'Native DB handle unavailable',
+                });
+            }
+        }
+        catch (err) {
+            dbChecks.push({
+                domain: 'db',
+                operation: 'tasks.db',
+                status: 'fail',
+                timeMs: Date.now() - start,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    // brain.db connectivity
+    {
+        const start = Date.now();
+        try {
+            const { getBrainDb } = await import('@cleocode/core/internal');
+            const projectRoot = (await import('@cleocode/core/internal')).getProjectRoot();
+            const brainDb = await getBrainDb(projectRoot);
+            if (brainDb) {
+                dbChecks.push({
+                    domain: 'db',
+                    operation: 'brain.db',
+                    status: 'pass',
+                    timeMs: Date.now() - start,
+                });
+            }
+            else {
+                dbChecks.push({
+                    domain: 'db',
+                    operation: 'brain.db',
+                    status: 'fail',
+                    timeMs: Date.now() - start,
+                    error: 'brain.db not initialized',
+                });
+            }
+        }
+        catch (err) {
+            dbChecks.push({
+                domain: 'db',
+                operation: 'brain.db',
+                status: 'fail',
+                timeMs: Date.now() - start,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    // Migration state validation (detect stale journals)
+    {
+        const start = Date.now();
+        try {
+            const migrationStatus = await getMigrationStatus((await import('@cleocode/core/internal')).getProjectRoot());
+            const hasPending = migrationStatus.migrations.some((m) => !m.applied);
+            dbChecks.push({
+                domain: 'db',
+                operation: 'migrations',
+                status: hasPending ? 'fail' : 'pass',
+                timeMs: Date.now() - start,
+                ...(hasPending
+                    ? {
+                        error: `Unapplied migrations detected (${migrationStatus.from} → ${migrationStatus.to}). Run: cleo upgrade`,
+                    }
+                    : {}),
+            });
+        }
+        catch (err) {
+            dbChecks.push({
+                domain: 'db',
+                operation: 'migrations',
+                status: 'fail',
+                timeMs: Date.now() - start,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    const allProbes = [...probes, ...dbChecks];
+    const totalMs = Date.now() - totalStart;
+    const passed = allProbes.filter((p) => p.status === 'pass').length;
+    const failed = allProbes.filter((p) => p.status === 'fail').length;
+    const skipped = allProbes.filter((p) => p.status === 'skip').length;
+    return {
+        success: failed === 0,
+        data: { probes, dbChecks, passed, failed, skipped, totalMs },
+        ...(failed > 0
+            ? {
+                error: {
+                    code: 'E_SMOKE_FAILURES',
+                    message: `${failed} probe(s) failed smoke test`,
+                    exitCode: 1,
+                },
+            }
+            : {}),
+    };
+}
+//# sourceMappingURL=system-engine.js.map