@cleocode/cleo 2026.2.5

package/dist/mcp/domains/system.js

@@ -0,0 +1,1000 @@
+/**
+ * System Domain Handler
+ *
+ * Implements all 30 system operations for CLEO MCP server:
+ * - Query (17): context, metrics, health, diagnostics, version, help, config.get, stats, job.status, job.list, dash, roadmap, labels, compliance, log, archive.stats, sequence
+ * - Mutate (11): backup, restore, migrate, cleanup, audit, init, config.set, sync, job.cancel, safestop, uncancel
+ *
+ * Each operation maps to corresponding CLEO CLI commands for system management,
+ * health checks, configuration, and maintenance operations.
+ *
+ * @task T2935
+ * @task T4269
+ */
+import { createGatewayMeta } from '../lib/gateway-meta.js';
+import { canRunNatively } from '../engine/capability-matrix.js';
+import { configGet as nativeConfigGet, configSet as nativeConfigSet, initProject as nativeInitProject, getVersion as nativeGetVersion, 
+// System engine
+systemDash as nativeSystemDash, systemStats as nativeSystemStats, systemLabels as nativeSystemLabels, systemArchiveStats as nativeSystemArchiveStats, systemLog as nativeSystemLog, systemContext as nativeSystemContext, systemSequence as nativeSystemSequence, systemInjectGenerate as nativeSystemInjectGenerate, systemMetrics as nativeSystemMetrics, systemHealth as nativeSystemHealth, systemDiagnostics as nativeSystemDiagnostics, systemHelp as nativeSystemHelp, systemRoadmap as nativeSystemRoadmap, systemCompliance as nativeSystemCompliance, systemBackup as nativeSystemBackup, systemRestore as nativeSystemRestore, systemMigrate as nativeSystemMigrate, systemCleanup as nativeSystemCleanup, systemAudit as nativeSystemAudit, systemSync as nativeSystemSync, systemSafestop as nativeSystemSafestop, systemUncancel as nativeSystemUncancel, 
+// CAAMP adapter
+providerList, providerGet, providerDetect, providerInstalled, mcpList as caampMcpList, mcpInstall as caampMcpInstall, mcpRemove as caampMcpRemove, injectionCheck as caampInjectionCheck, injectionCheckAll as caampInjectionCheckAll, injectionUpdate as caampInjectionUpdate, injectionUpdateAll as caampInjectionUpdateAll, } from '../engine/index.js';
+import { getProjectRoot, isProjectInitialized } from '../../core/paths.js';
+import { createCLIRequiredError, createNotInitializedError } from '../lib/mode-detector.js';
+export class SystemHandler {
+    executor;
+    jobManager;
+    executionMode;
+    projectRoot;
+    constructor(executor, jobManager, executionMode = 'cli') {
+        this.executor = executor;
+        this.jobManager = jobManager;
+        this.executionMode = executionMode;
+        this.projectRoot = getProjectRoot();
+    }
+    /**
+     * Check if we should use native engine for this operation
+     */
+    useNative(operation, gateway) {
+        if (this.executionMode === 'cli' && this.executor?.isAvailable()) {
+            return false;
+        }
+        return canRunNatively('system', operation, gateway);
+    }
+    /**
+     * Wrap a native engine result in DomainResponse format
+     */
+    wrapNativeResult(result, gateway, operation, startTime) {
+        if (result.success) {
+            return {
+                _meta: createGatewayMeta(gateway, 'system', operation, startTime),
+                success: true,
+                data: result.data,
+            };
+        }
+        return {
+            _meta: createGatewayMeta(gateway, 'system', operation, startTime),
+            success: false,
+            error: { code: result.error?.code || 'E_UNKNOWN', message: result.error?.message || 'Unknown error' },
+        };
+    }
+    /**
+     * Set the background job manager (allows post-construction injection)
+     */
+    setJobManager(jobManager) {
+        this.jobManager = jobManager;
+    }
+    /**
+     * Get the background job manager
+     */
+    getJobManager() {
+        return this.jobManager;
+    }
+    async query(operation, params) {
+        const startTime = Date.now();
+        // Native engine routing for supported operations
+        if (this.useNative(operation, 'query')) {
+            try {
+                return this.queryNative(operation, params, startTime);
+            }
+            catch (error) {
+                return this.handleError('query', 'system', operation, error, startTime);
+            }
+        }
+        if (!this.executor || !this.executor.isAvailable()) {
+            const err = createCLIRequiredError('system', operation);
+            return this.wrapNativeResult(err, 'query', operation, startTime);
+        }
+        try {
+            switch (operation) {
+                case 'context':
+                    return this.getContext(params, startTime);
+                case 'metrics':
+                    return this.getMetrics(params, startTime);
+                case 'health':
+                    return this.checkHealth(params, startTime);
+                case 'diagnostics':
+                    return this.runDiagnostics(params, startTime);
+                case 'version':
+                    return this.getVersion(params, startTime);
+                case 'help':
+                    return this.getHelp(params, startTime);
+                case 'config.get':
+                    return this.getConfig(params, startTime);
+                case 'stats':
+                    return this.getMetrics(params, startTime);
+                case 'job.status':
+                    return this.queryJobStatus(params, startTime);
+                case 'job.list':
+                    return this.queryJobList(params, startTime);
+                case 'dash':
+                    return this.getDash(params, startTime);
+                case 'roadmap':
+                    return this.getRoadmap(params, startTime);
+                case 'labels':
+                    return this.getLabels(params, startTime);
+                case 'compliance':
+                    return this.getCompliance(params, startTime);
+                case 'log':
+                    return this.getLog(params, startTime);
+                case 'archive.stats':
+                    return this.getArchiveStats(params, startTime);
+                case 'sequence':
+                    return this.getSequence(params, startTime);
+                // CAAMP provider operations
+                case 'provider.list':
+                    return this.wrapNativeResult(providerList(), 'query', operation, startTime);
+                case 'provider.get': {
+                    const p = params;
+                    if (!p?.idOrAlias) {
+                        return this.createErrorResponse('query', 'system', operation, 'E_INVALID_INPUT', 'idOrAlias parameter is required', startTime);
+                    }
+                    return this.wrapNativeResult(providerGet(p.idOrAlias), 'query', operation, startTime);
+                }
+                case 'provider.detect':
+                    return this.wrapNativeResult(providerDetect(), 'query', operation, startTime);
+                case 'provider.installed':
+                    return this.wrapNativeResult(providerInstalled(), 'query', operation, startTime);
+                default:
+                    return this.createErrorResponse('query', 'system', operation, 'E_INVALID_OPERATION', `Unknown query operation: ${operation}`, startTime);
+            }
+        }
+        catch (error) {
+            return this.handleError('query', 'system', operation, error, startTime);
+        }
+    }
+    async mutate(operation, params) {
+        const startTime = Date.now();
+        // Native engine routing for supported operations
+        if (this.useNative(operation, 'mutate')) {
+            try {
+                return await this.mutateNative(operation, params, startTime);
+            }
+            catch (error) {
+                return this.handleError('mutate', 'system', operation, error, startTime);
+            }
+        }
+        if (!this.executor || !this.executor.isAvailable()) {
+            const err = createCLIRequiredError('system', operation);
+            return this.wrapNativeResult(err, 'mutate', operation, startTime);
+        }
+        try {
+            switch (operation) {
+                case 'backup':
+                    return this.createBackup(params, startTime);
+                case 'restore':
+                    return this.restoreBackup(params, startTime);
+                case 'migrate':
+                    return this.runMigrations(params, startTime);
+                case 'cleanup':
+                    return this.cleanup(params, startTime);
+                case 'audit':
+                    return this.runAudit(params, startTime);
+                case 'init':
+                    return this.mutateInit(params, startTime);
+                case 'config.set':
+                    return this.mutateConfigSet(params, startTime);
+                case 'sync':
+                    return this.mutateSync(params, startTime);
+                case 'job.cancel':
+                    return this.mutateJobCancel(params, startTime);
+                case 'safestop':
+                    return this.mutateSafestop(params, startTime);
+                case 'uncancel':
+                    return this.mutateUncancel(params, startTime);
+                case 'inject.generate':
+                    return this.wrapNativeResult(await nativeSystemInjectGenerate(this.projectRoot), 'mutate', operation, startTime);
+                // CAAMP MCP config operations
+                case 'mcp.list': {
+                    const p = params;
+                    if (!p?.providerId || !p?.scope) {
+                        return this.createErrorResponse('mutate', 'system', operation, 'E_INVALID_INPUT', 'providerId and scope are required', startTime);
+                    }
+                    const result = await caampMcpList(p.providerId, p.scope, p.projectDir);
+                    return this.wrapNativeResult(result, 'mutate', operation, startTime);
+                }
+                case 'mcp.install': {
+                    const p = params;
+                    if (!p?.providerId || !p?.serverName || !p?.config) {
+                        return this.createErrorResponse('mutate', 'system', operation, 'E_INVALID_INPUT', 'providerId, serverName, and config are required', startTime);
+                    }
+                    const result = await caampMcpInstall(p.providerId, p.serverName, p.config, p.scope, p.projectDir);
+                    return this.wrapNativeResult(result, 'mutate', operation, startTime);
+                }
+                case 'mcp.remove': {
+                    const p = params;
+                    if (!p?.providerId || !p?.serverName || !p?.scope) {
+                        return this.createErrorResponse('mutate', 'system', operation, 'E_INVALID_INPUT', 'providerId, serverName, and scope are required', startTime);
+                    }
+                    const result = await caampMcpRemove(p.providerId, p.serverName, p.scope, p.projectDir);
+                    return this.wrapNativeResult(result, 'mutate', operation, startTime);
+                }
+                // CAAMP injection operations
+                case 'injection.check': {
+                    const p = params;
+                    if (!p?.filePath) {
+                        return this.createErrorResponse('mutate', 'system', operation, 'E_INVALID_INPUT', 'filePath is required', startTime);
+                    }
+                    const result = await caampInjectionCheck(p.filePath, p.expectedContent);
+                    return this.wrapNativeResult(result, 'mutate', operation, startTime);
+                }
+                case 'injection.check.all': {
+                    const p = params;
+                    if (!p?.projectDir || !p?.scope) {
+                        return this.createErrorResponse('mutate', 'system', operation, 'E_INVALID_INPUT', 'projectDir and scope are required', startTime);
+                    }
+                    const result = await caampInjectionCheckAll(p.projectDir, p.scope, p.expectedContent);
+                    return this.wrapNativeResult(result, 'mutate', operation, startTime);
+                }
+                case 'injection.update': {
+                    const p = params;
+                    if (!p?.filePath || !p?.content) {
+                        return this.createErrorResponse('mutate', 'system', operation, 'E_INVALID_INPUT', 'filePath and content are required', startTime);
+                    }
+                    const result = await caampInjectionUpdate(p.filePath, p.content);
+                    return this.wrapNativeResult(result, 'mutate', operation, startTime);
+                }
+                case 'injection.update.all': {
+                    const p = params;
+                    if (!p?.projectDir || !p?.scope || !p?.content) {
+                        return this.createErrorResponse('mutate', 'system', operation, 'E_INVALID_INPUT', 'projectDir, scope, and content are required', startTime);
+                    }
+                    const result = await caampInjectionUpdateAll(p.projectDir, p.scope, p.content);
+                    return this.wrapNativeResult(result, 'mutate', operation, startTime);
+                }
+                default:
+                    return this.createErrorResponse('mutate', 'system', operation, 'E_INVALID_OPERATION', `Unknown mutate operation: ${operation}`, startTime);
+            }
+        }
+        catch (error) {
+            return this.handleError('mutate', 'system', operation, error, startTime);
+        }
+    }
+    getSupportedOperations() {
+        return {
+            query: [
+                'context', 'metrics', 'health', 'diagnostics', 'version', 'help',
+                'config.get', 'stats', 'job.status', 'job.list', 'dash', 'roadmap', 'labels',
+                'compliance', 'log', 'archive.stats', 'sequence',
+                // CAAMP provider queries
+                'provider.list', 'provider.get', 'provider.detect', 'provider.installed',
+            ],
+            mutate: [
+                'backup', 'restore', 'migrate', 'cleanup', 'audit', 'init', 'config.set', 'sync',
+                'job.cancel', 'safestop', 'uncancel', 'inject.generate',
+                // CAAMP MCP config
+                'mcp.list', 'mcp.install', 'mcp.remove',
+                // CAAMP injection
+                'injection.check', 'injection.check.all', 'injection.update', 'injection.update.all',
+            ],
+        };
+    }
+    /**
+     * QUERY OPERATIONS
+     */
+    async getContext(_params, startTime) {
+        const result = await this.executor.execute({
+            domain: 'system',
+            operation: 'context',
+            customCommand: 'cleo context --json'
+        });
+        return this.wrapExecutorResult(result, 'query', 'system', 'context', startTime);
+    }
+    async getMetrics(params, startTime) {
+        const parts = ['cleo', 'stats', '--json'];
+        if (params?.scope)
+            parts.push('--scope', params.scope);
+        if (params?.since)
+            parts.push('--since', params.since);
+        const result = await this.executor.execute({
+            domain: 'system',
+            operation: 'stats',
+            customCommand: parts.join(' ')
+        });
+        return this.wrapExecutorResult(result, 'query', 'system', 'metrics', startTime);
+    }
+    async checkHealth(params, startTime) {
+        const result = await this.executor.execute({
+            domain: 'system',
+            operation: 'health',
+            customCommand: params?.detailed
+                ? 'cleo doctor --verbose --json'
+                : 'cleo doctor --json'
+        });
+        return this.wrapExecutorResult(result, 'query', 'system', 'health', startTime);
+    }
+    async getConfig(params, startTime) {
+        // Read config file directly since there's no cleo config command
+        const result = await this.executor.execute({
+            domain: 'system',
+            operation: 'config',
+            customCommand: 'cat .cleo/config.json | jq .'
+        });
+        if (!result.success) {
+            return this.wrapExecutorResult(result, 'query', 'system', 'config', startTime);
+        }
+        // If specific key requested, extract it
+        if (params?.key && result.data) {
+            const keys = params.key.split('.');
+            let value = result.data;
+            for (const key of keys) {
+                if (typeof value === 'object' && value !== null && key in value) {
+                    value = value[key];
+                }
+                else {
+                    return this.createErrorResponse('query', 'system', 'config', 'E_NOT_FOUND', `Config key not found: ${params.key}`, startTime);
+                }
+            }
+            result.data = { [params.key]: value };
+        }
+        return this.wrapExecutorResult(result, 'query', 'system', 'config', startTime);
+    }
+    async runDiagnostics(params, startTime) {
+        const args = params?.checks && params.checks.length > 0 ? ['--checks', params.checks.join(',')] : [];
+        const result = await this.executor.execute({
+            domain: 'validate',
+            operation: 'all',
+            args,
+            flags: { json: true }
+        });
+        return this.wrapExecutorResult(result, 'query', 'system', 'diagnostics', startTime);
+    }
+    async getVersion(_params, startTime) {
+        const result = await this.executor.execute({
+            domain: 'system',
+            operation: 'version',
+            customCommand: 'cleo version --json'
+        });
+        return this.wrapExecutorResult(result, 'query', 'system', 'version', startTime);
+    }
+    async getHelp(params, startTime) {
+        const args = params?.topic ? [params.topic] : [];
+        const result = await this.executor.execute({
+            domain: 'help',
+            operation: 'show',
+            args,
+            flags: { json: true }
+        });
+        return this.wrapExecutorResult(result, 'query', 'system', 'help', startTime);
+    }
+    /**
+     * MUTATE OPERATIONS
+     */
+    async createBackup(params, startTime) {
+        const args = [params?.type || 'snapshot'];
+        const flags = { json: true };
+        if (params?.note)
+            flags.note = params.note;
+        const result = await this.executor.execute({
+            domain: 'backup',
+            operation: 'create',
+            args,
+            flags
+        });
+        return this.wrapExecutorResult(result, 'mutate', 'system', 'backup', startTime);
+    }
+    async restoreBackup(params, startTime) {
+        if (!params.backupId) {
+            return this.createErrorResponse('mutate', 'system', 'restore', 'E_INVALID_INPUT', 'backupId parameter is required', startTime);
+        }
+        const flags = { json: true };
+        if (params.force)
+            flags.force = true;
+        const result = await this.executor.execute({
+            domain: 'backup',
+            operation: 'restore',
+            args: [params.backupId],
+            flags
+        });
+        return this.wrapExecutorResult(result, 'mutate', 'system', 'restore', startTime);
+    }
+    async runMigrations(params, startTime) {
+        const args = params?.target ? ['to', params.target] : ['up'];
+        const flags = { json: true };
+        if (params?.dryRun)
+            flags['dry-run'] = true;
+        const result = await this.executor.execute({
+            domain: 'migrate',
+            operation: 'run',
+            args,
+            flags
+        });
+        return this.wrapExecutorResult(result, 'mutate', 'system', 'migrate', startTime);
+    }
+    async cleanup(params, startTime) {
+        if (!params.target) {
+            return this.createErrorResponse('mutate', 'system', 'cleanup', 'E_INVALID_INPUT', 'target parameter is required (sessions|backups|logs|archive)', startTime);
+        }
+        const flags = { json: true };
+        if (params.olderThan)
+            flags['older-than'] = params.olderThan;
+        if (params.dryRun)
+            flags['dry-run'] = true;
+        let domain;
+        let operation;
+        switch (params.target) {
+            case 'archive':
+                domain = 'archive';
+                operation = 'cleanup';
+                break;
+            case 'sessions':
+                domain = 'session';
+                operation = 'gc';
+                break;
+            case 'backups':
+                domain = 'backup';
+                operation = 'cleanup';
+                break;
+            case 'logs':
+                domain = 'log';
+                operation = 'cleanup';
+                break;
+            default:
+                return this.createErrorResponse('mutate', 'system', 'cleanup', 'E_INVALID_INPUT', `Invalid cleanup target: ${params.target}. Must be sessions, backups, logs, or archive`, startTime);
+        }
+        const result = await this.executor.execute({
+            domain,
+            operation,
+            flags
+        });
+        return this.wrapExecutorResult(result, 'mutate', 'system', 'cleanup', startTime);
+    }
+    async runAudit(params, startTime) {
+        const args = [params?.scope || 'all'];
+        const flags = { json: true };
+        if (params?.fix)
+            flags.fix = true;
+        const result = await this.executor.execute({
+            domain: 'validate',
+            operation: 'audit',
+            args,
+            flags
+        });
+        return this.wrapExecutorResult(result, 'mutate', 'system', 'audit', startTime);
+    }
+    /**
+     * init - Initialize CLEO project
+     * CLI: cleo init [--project-type X] [--detect]
+     */
+    async mutateInit(params, startTime) {
+        const flags = { json: true };
+        if (params?.projectType)
+            flags['project-type'] = params.projectType;
+        if (params?.detect)
+            flags.detect = true;
+        const result = await this.executor.execute({
+            domain: 'init',
+            operation: '',
+            flags,
+        });
+        return this.wrapExecutorResult(result, 'mutate', 'system', 'init', startTime);
+    }
+    /**
+     * config.set - Set configuration value
+     * CLI: cleo config set <key> <value>
+     */
+    async mutateConfigSet(params, startTime) {
+        if (!params?.key || params?.value === undefined) {
+            return this.createErrorResponse('mutate', 'system', 'config.set', 'E_INVALID_INPUT', 'key and value are required', startTime);
+        }
+        const result = await this.executor.execute({
+            domain: 'config',
+            operation: 'set',
+            args: [params.key, String(params.value)],
+            flags: { json: true },
+        });
+        return this.wrapExecutorResult(result, 'mutate', 'system', 'config.set', startTime);
+    }
+    /**
+     * sync - Sync with external systems
+     * CLI: cleo sync [--direction up|down]
+     */
+    async mutateSync(params, startTime) {
+        const flags = { json: true };
+        if (params?.direction)
+            flags.direction = params.direction;
+        const result = await this.executor.execute({
+            domain: 'sync',
+            operation: '',
+            flags,
+        });
+        return this.wrapExecutorResult(result, 'mutate', 'system', 'sync', startTime);
+    }
+    /**
+     * dash - Project overview dashboard
+     * CLI: cleo dash --json
+     * @task T4269
+     */
+    async getDash(_params, startTime) {
+        const result = await this.executor.execute({
+            domain: 'system',
+            operation: 'dash',
+            customCommand: 'cleo dash --json'
+        });
+        // The dash command returns many top-level fields (project, summary, focus,
+        // phases, etc.). The executor's smart unwrapping incorrectly picks a single
+        // primary field (e.g., 'focus') instead of the full dashboard. Re-parse
+        // raw stdout to return the complete payload.
+        if (result.success && result.stdout) {
+            try {
+                const parsed = JSON.parse(result.stdout.trim());
+                if (parsed && parsed.success) {
+                    const envelope = new Set(['$schema', '_meta', 'success', 'error', 'warnings']);
+                    const payload = {};
+                    for (const [key, value] of Object.entries(parsed)) {
+                        if (!envelope.has(key)) {
+                            payload[key] = value;
+                        }
+                    }
+                    return {
+                        _meta: createGatewayMeta('query', 'system', 'dash', startTime),
+                        success: true,
+                        data: payload,
+                    };
+                }
+            }
+            catch {
+                // Fall through to default handling
+            }
+        }
+        return this.wrapExecutorResult(result, 'query', 'system', 'dash', startTime);
+    }
+    /**
+     * roadmap - Generate roadmap from pending epics and CHANGELOG history
+     * CLI: cleo roadmap [--json] [--include-history] [--upcoming-only]
+     * @task T4269
+     */
+    async getRoadmap(params, startTime) {
+        const flags = { json: true };
+        if (params?.includeHistory)
+            flags['include-history'] = true;
+        if (params?.upcomingOnly)
+            flags['upcoming-only'] = true;
+        const result = await this.executor.execute({
+            domain: 'roadmap',
+            operation: '',
+            flags
+        });
+        return this.wrapExecutorResult(result, 'query', 'system', 'roadmap', startTime);
+    }
+    /**
+     * labels - List all labels with counts or show tasks with specific label
+     * CLI: cleo labels [show <label>] [--json]
+     * @task T4269
+     */
+    async getLabels(params, startTime) {
+        const flags = { json: true };
+        let operation = '';
+        if (params?.subcommand === 'show' && params?.label) {
+            operation = `show ${params.label}`;
+        }
+        else if (params?.subcommand === 'stats') {
+            operation = 'stats';
+        }
+        else if (params?.label) {
+            operation = `show ${params.label}`;
+        }
+        const result = await this.executor.execute({
+            domain: 'labels',
+            operation,
+            flags
+        });
+        return this.wrapExecutorResult(result, 'query', 'system', 'labels', startTime);
+    }
+    /**
+     * compliance - Monitor and report compliance metrics
+     * CLI: cleo compliance [subcommand] [--json] [--days N] [--epic T###]
+     * @task T4269
+     */
+    async getCompliance(params, startTime) {
+        const flags = { json: true };
+        if (params?.days)
+            flags.days = params.days;
+        if (params?.epic)
+            flags.epic = params.epic;
+        const result = await this.executor.execute({
+            domain: 'compliance',
+            operation: params?.subcommand || 'summary',
+            flags
+        });
+        return this.wrapExecutorResult(result, 'query', 'system', 'compliance', startTime);
+    }
+    /**
+     * log - View audit log entries
+     * CLI: cleo log [--json] [--limit N] [--operation OP] [--task T###]
+     * @task T4269
+     */
+    async getLog(params, startTime) {
+        const flags = { json: true };
+        if (params?.limit)
+            flags.limit = params.limit;
+        if (params?.operation)
+            flags.operation = params.operation;
+        if (params?.task)
+            flags.task = params.task;
+        const result = await this.executor.execute({
+            domain: 'log',
+            operation: '',
+            flags
+        });
+        return this.wrapExecutorResult(result, 'query', 'system', 'log', startTime);
+    }
+    /**
+     * archive.stats - Generate analytics from archived tasks
+     * CLI: cleo archive-stats [--json] [--by-phase] [--by-label]
+     * @task T4269
+     */
+    async getArchiveStats(params, startTime) {
+        const flags = { json: true };
+        if (params?.byPhase)
+            flags['by-phase'] = true;
+        if (params?.byLabel)
+            flags['by-label'] = true;
+        const result = await this.executor.execute({
+            domain: 'archive-stats',
+            operation: '',
+            flags
+        });
+        return this.wrapExecutorResult(result, 'query', 'system', 'archive.stats', startTime);
+    }
+    /**
+     * sequence - Inspect and manage task ID sequence
+     * CLI: cleo sequence [show|check|repair] [--json]
+     * @task T4269
+     */
+    async getSequence(params, startTime) {
+        const result = await this.executor.execute({
+            domain: 'sequence',
+            operation: params?.subcommand || 'show',
+            flags: { json: true }
+        });
+        return this.wrapExecutorResult(result, 'query', 'system', 'sequence', startTime);
+    }
+    /**
+     * JOB QUERY OPERATIONS
+     */
+    /**
+     * job.status - Get a specific background job's status
+     */
+    queryJobStatus(params, startTime) {
+        if (!this.jobManager) {
+            return this.createErrorResponse('query', 'system', 'job.status', 'E_NOT_INITIALIZED', 'Background job manager not initialized', startTime);
+        }
+        const jobId = params?.jobId;
+        if (!jobId) {
+            return this.createErrorResponse('query', 'system', 'job.status', 'E_INVALID_INPUT', 'jobId parameter is required', startTime);
+        }
+        const job = this.jobManager.getJob(jobId);
+        if (!job) {
+            return this.createErrorResponse('query', 'system', 'job.status', 'E_NOT_FOUND', `Job not found: ${jobId}`, startTime);
+        }
+        return {
+            _meta: createGatewayMeta('query', 'system', 'job.status', startTime),
+            success: true,
+            data: job,
+        };
+    }
+    /**
+     * job.list - List all background jobs, optionally filtered by status
+     */
+    queryJobList(params, startTime) {
+        if (!this.jobManager) {
+            return this.createErrorResponse('query', 'system', 'job.list', 'E_NOT_INITIALIZED', 'Background job manager not initialized', startTime);
+        }
+        const status = params?.status;
+        const jobs = this.jobManager.listJobs(status);
+        return {
+            _meta: createGatewayMeta('query', 'system', 'job.list', startTime),
+            success: true,
+            data: { jobs, count: jobs.length },
+        };
+    }
+    /**
+     * JOB MUTATE OPERATIONS
+     */
+    /**
+     * job.cancel - Cancel a running background job
+     */
+    mutateJobCancel(params, startTime) {
+        if (!this.jobManager) {
+            return this.createErrorResponse('mutate', 'system', 'job.cancel', 'E_NOT_INITIALIZED', 'Background job manager not initialized', startTime);
+        }
+        const jobId = params?.jobId;
+        if (!jobId) {
+            return this.createErrorResponse('mutate', 'system', 'job.cancel', 'E_INVALID_INPUT', 'jobId parameter is required', startTime);
+        }
+        const cancelled = this.jobManager.cancelJob(jobId);
+        if (!cancelled) {
+            return this.createErrorResponse('mutate', 'system', 'job.cancel', 'E_NOT_FOUND', `Job not found or not running: ${jobId}`, startTime);
+        }
+        return {
+            _meta: createGatewayMeta('mutate', 'system', 'job.cancel', startTime),
+            success: true,
+            data: { jobId, cancelled: true },
+        };
+    }
+    /**
+     * safestop - Graceful shutdown for agents approaching context limits
+     * CLI: cleo safestop [--reason "..."] [--commit] [--handoff "..."] [--no-session-end] [--dry-run] [--json]
+     * @task T4269
+     */
+    async mutateSafestop(params, startTime) {
+        const flags = { json: true };
+        if (params?.reason)
+            flags.reason = params.reason;
+        if (params?.commit)
+            flags.commit = true;
+        if (params?.handoff)
+            flags.handoff = params.handoff;
+        if (params?.noSessionEnd)
+            flags['no-session-end'] = true;
+        if (params?.dryRun)
+            flags['dry-run'] = true;
+        const result = await this.executor.execute({
+            domain: 'safestop',
+            operation: '',
+            flags,
+        });
+        return this.wrapExecutorResult(result, 'mutate', 'system', 'safestop', startTime);
+    }
+    /**
+     * uncancel - Restore cancelled tasks back to pending status
+     * CLI: cleo uncancel <taskId> [--cascade] [--notes "..."] [--dry-run] [--json]
+     * @task T4269
+     */
+    async mutateUncancel(params, startTime) {
+        if (!params?.taskId) {
+            return this.createErrorResponse('mutate', 'system', 'uncancel', 'E_INVALID_INPUT', 'taskId parameter is required', startTime);
+        }
+        const flags = { json: true };
+        if (params?.cascade)
+            flags.cascade = true;
+        if (params?.notes)
+            flags.notes = params.notes;
+        if (params?.dryRun)
+            flags['dry-run'] = true;
+        const result = await this.executor.execute({
+            domain: 'uncancel',
+            operation: params.taskId,
+            flags,
+        });
+        return this.wrapExecutorResult(result, 'mutate', 'system', 'uncancel', startTime);
+    }
+    /**
+     * Helper methods
+     */
+    wrapExecutorResult(result, gateway, domain, operation, startTime) {
+        if (result.success) {
+            return {
+                _meta: createGatewayMeta(gateway, domain, operation, startTime),
+                success: true,
+                data: result.data,
+            };
+        }
+        return {
+            _meta: createGatewayMeta(gateway, domain, operation, startTime),
+            success: false,
+            error: result.error || {
+                code: 'E_UNKNOWN',
+                message: 'Unknown error occurred',
+            },
+        };
+    }
+    // ===== Native Engine Operations =====
+    /**
+     * Route query operations to native TypeScript engine
+     */
+    async queryNative(operation, params, startTime) {
+        switch (operation) {
+            case 'version':
+                return this.wrapNativeResult(nativeGetVersion(this.projectRoot), 'query', operation, startTime);
+            case 'config.get': {
+                if (!isProjectInitialized(this.projectRoot)) {
+                    return this.wrapNativeResult(createNotInitializedError(), 'query', operation, startTime);
+                }
+                const key = params?.key;
+                return this.wrapNativeResult(nativeConfigGet(this.projectRoot, key), 'query', operation, startTime);
+            }
+            case 'dash': {
+                if (!isProjectInitialized(this.projectRoot)) {
+                    return this.wrapNativeResult(createNotInitializedError(), 'query', operation, startTime);
+                }
+                return this.wrapNativeResult(await nativeSystemDash(this.projectRoot), 'query', operation, startTime);
+            }
+            case 'stats': {
+                if (!isProjectInitialized(this.projectRoot)) {
+                    return this.wrapNativeResult(createNotInitializedError(), 'query', operation, startTime);
+                }
+                return this.wrapNativeResult(await nativeSystemStats(this.projectRoot), 'query', operation, startTime);
+            }
+            case 'labels': {
+                if (!isProjectInitialized(this.projectRoot)) {
+                    return this.wrapNativeResult(createNotInitializedError(), 'query', operation, startTime);
+                }
+                return this.wrapNativeResult(await nativeSystemLabels(this.projectRoot), 'query', operation, startTime);
+            }
+            case 'archive.stats': {
+                if (!isProjectInitialized(this.projectRoot)) {
+                    return this.wrapNativeResult(createNotInitializedError(), 'query', operation, startTime);
+                }
+                return this.wrapNativeResult(await nativeSystemArchiveStats(this.projectRoot), 'query', operation, startTime);
+            }
+            case 'log': {
+                if (!isProjectInitialized(this.projectRoot)) {
+                    return this.wrapNativeResult(createNotInitializedError(), 'query', operation, startTime);
+                }
+                const logp = params;
+                return this.wrapNativeResult(nativeSystemLog(this.projectRoot, { limit: logp?.limit, operation: logp?.operation, taskId: logp?.task }), 'query', operation, startTime);
+            }
+            case 'context': {
+                if (!isProjectInitialized(this.projectRoot)) {
+                    return this.wrapNativeResult(createNotInitializedError(), 'query', operation, startTime);
+                }
+                return this.wrapNativeResult(nativeSystemContext(this.projectRoot), 'query', operation, startTime);
+            }
+            case 'sequence': {
+                if (!isProjectInitialized(this.projectRoot)) {
+                    return this.wrapNativeResult(createNotInitializedError(), 'query', operation, startTime);
+                }
+                return this.wrapNativeResult(nativeSystemSequence(this.projectRoot), 'query', operation, startTime);
+            }
+            case 'metrics': {
+                if (!isProjectInitialized(this.projectRoot)) {
+                    return this.wrapNativeResult(createNotInitializedError(), 'query', operation, startTime);
+                }
+                const mp = params;
+                return this.wrapNativeResult(await nativeSystemMetrics(this.projectRoot, { scope: mp?.scope, since: mp?.since }), 'query', operation, startTime);
+            }
+            case 'health': {
+                if (!isProjectInitialized(this.projectRoot)) {
+                    return this.wrapNativeResult(createNotInitializedError(), 'query', operation, startTime);
+                }
+                const hp = params;
+                return this.wrapNativeResult(nativeSystemHealth(this.projectRoot, { detailed: hp?.detailed }), 'query', operation, startTime);
+            }
+            case 'diagnostics': {
+                if (!isProjectInitialized(this.projectRoot)) {
+                    return this.wrapNativeResult(createNotInitializedError(), 'query', operation, startTime);
+                }
+                const dp = params;
+                return this.wrapNativeResult(nativeSystemDiagnostics(this.projectRoot, { checks: dp?.checks }), 'query', operation, startTime);
+            }
+            case 'help': {
+                const helpp = params;
+                return this.wrapNativeResult(nativeSystemHelp(this.projectRoot, { topic: helpp?.topic }), 'query', operation, startTime);
+            }
+            case 'roadmap': {
+                if (!isProjectInitialized(this.projectRoot)) {
+                    return this.wrapNativeResult(createNotInitializedError(), 'query', operation, startTime);
+                }
+                const rp = params;
+                return this.wrapNativeResult(await nativeSystemRoadmap(this.projectRoot, { includeHistory: rp?.includeHistory, upcomingOnly: rp?.upcomingOnly }), 'query', operation, startTime);
+            }
+            case 'compliance': {
+                if (!isProjectInitialized(this.projectRoot)) {
+                    return this.wrapNativeResult(createNotInitializedError(), 'query', operation, startTime);
+                }
+                const cp = params;
+                return this.wrapNativeResult(nativeSystemCompliance(this.projectRoot, { subcommand: cp?.subcommand, days: cp?.days, epic: cp?.epic }), 'query', operation, startTime);
+            }
+            case 'job.status':
+                return this.queryJobStatus(params, startTime);
+            case 'job.list':
+                return this.queryJobList(params, startTime);
+            default:
+                return this.createErrorResponse('query', 'system', operation, 'E_INVALID_OPERATION', `No native handler for: ${operation}`, startTime);
+        }
+    }
+    /**
+     * Route mutate operations to native TypeScript engine
+     */
+    async mutateNative(operation, params, startTime) {
+        switch (operation) {
+            case 'init': {
+                const p = params;
+                const result = nativeInitProject(this.projectRoot, {
+                    projectName: p?.projectType,
+                    force: false,
+                });
+                return this.wrapNativeResult(result, 'mutate', operation, startTime);
+            }
+            case 'config.set': {
+                if (!isProjectInitialized(this.projectRoot)) {
+                    return this.wrapNativeResult(createNotInitializedError(), 'mutate', operation, startTime);
+                }
+                const p = params;
+                if (!p?.key) {
+                    return this.createErrorResponse('mutate', 'system', operation, 'E_INVALID_INPUT', 'key is required', startTime);
+                }
+                const result = await nativeConfigSet(this.projectRoot, p.key, p.value);
+                return this.wrapNativeResult(result, 'mutate', operation, startTime);
+            }
+            case 'inject.generate': {
+                const result = await nativeSystemInjectGenerate(this.projectRoot);
+                return this.wrapNativeResult(result, 'mutate', operation, startTime);
+            }
+            case 'backup': {
+                if (!isProjectInitialized(this.projectRoot)) {
+                    return this.wrapNativeResult(createNotInitializedError(), 'mutate', operation, startTime);
+                }
+                const bp = params;
+                return this.wrapNativeResult(nativeSystemBackup(this.projectRoot, { type: bp?.type, note: bp?.note }), 'mutate', operation, startTime);
+            }
+            case 'restore': {
+                if (!isProjectInitialized(this.projectRoot)) {
+                    return this.wrapNativeResult(createNotInitializedError(), 'mutate', operation, startTime);
+                }
+                const rp = params;
+                if (!rp?.backupId) {
+                    return this.createErrorResponse('mutate', 'system', operation, 'E_INVALID_INPUT', 'backupId is required', startTime);
+                }
+                return this.wrapNativeResult(nativeSystemRestore(this.projectRoot, { backupId: rp.backupId, force: rp.force }), 'mutate', operation, startTime);
+            }
+            case 'migrate': {
+                if (!isProjectInitialized(this.projectRoot)) {
+                    return this.wrapNativeResult(createNotInitializedError(), 'mutate', operation, startTime);
+                }
+                const mp = params;
+                return this.wrapNativeResult(nativeSystemMigrate(this.projectRoot, { target: mp?.target, dryRun: mp?.dryRun }), 'mutate', operation, startTime);
+            }
+            case 'cleanup': {
+                if (!isProjectInitialized(this.projectRoot)) {
+                    return this.wrapNativeResult(createNotInitializedError(), 'mutate', operation, startTime);
+                }
+                const clp = params;
+                if (!clp?.target) {
+                    return this.createErrorResponse('mutate', 'system', operation, 'E_INVALID_INPUT', 'target is required', startTime);
+                }
+                return this.wrapNativeResult(nativeSystemCleanup(this.projectRoot, { target: clp.target, olderThan: clp.olderThan, dryRun: clp.dryRun }), 'mutate', operation, startTime);
+            }
+            case 'audit': {
+                if (!isProjectInitialized(this.projectRoot)) {
+                    return this.wrapNativeResult(createNotInitializedError(), 'mutate', operation, startTime);
+                }
+                const ap = params;
+                return this.wrapNativeResult(nativeSystemAudit(this.projectRoot, { scope: ap?.scope, fix: ap?.fix }), 'mutate', operation, startTime);
+            }
+            case 'sync': {
+                const sp = params;
+                return this.wrapNativeResult(nativeSystemSync(this.projectRoot, { direction: sp?.direction }), 'mutate', operation, startTime);
+            }
+            case 'job.cancel':
+                return this.mutateJobCancel(params, startTime);
+            case 'safestop': {
+                const sfp = params;
+                return this.wrapNativeResult(nativeSystemSafestop(this.projectRoot, {
+                    reason: sfp?.reason, commit: sfp?.commit, handoff: sfp?.handoff,
+                    noSessionEnd: sfp?.noSessionEnd, dryRun: sfp?.dryRun,
+                }), 'mutate', operation, startTime);
+            }
+            case 'uncancel': {
+                if (!isProjectInitialized(this.projectRoot)) {
+                    return this.wrapNativeResult(createNotInitializedError(), 'mutate', operation, startTime);
+                }
+                const ucp = params;
+                if (!ucp?.taskId) {
+                    return this.createErrorResponse('mutate', 'system', operation, 'E_INVALID_INPUT', 'taskId is required', startTime);
+                }
+                return this.wrapNativeResult(nativeSystemUncancel(this.projectRoot, {
+                    taskId: ucp.taskId, cascade: ucp.cascade, notes: ucp.notes, dryRun: ucp.dryRun,
+                }), 'mutate', operation, startTime);
+            }
+            default:
+                return this.createErrorResponse('mutate', 'system', operation, 'E_INVALID_OPERATION', `No native handler for: ${operation}`, startTime);
+        }
+    }
+    // ===== Helper Methods =====
+    createErrorResponse(gateway, domain, operation, code, message, startTime) {
+        return {
+            _meta: createGatewayMeta(gateway, domain, operation, startTime),
+            success: false,
+            error: {
+                code,
+                message,
+            },
+        };
+    }
+    handleError(gateway, domain, operation, error, startTime) {
+        return this.createErrorResponse(gateway, domain, operation, 'E_EXECUTION_ERROR', error instanceof Error ? error.message : String(error), startTime);
+    }
+}
+//# sourceMappingURL=system.js.map